How to Use the FFmpeg Subtitles Filter

This guide explains how to use the subtitles filter in FFmpeg to hardcode (burn) subtitles directly into your video files. You will learn the basic command syntax, how to handle path escaping issues, how to customize subtitle styles, and how to extract and burn embedded subtitles from container files like MKV.

Prerequisites

To use the subtitles filter, your FFmpeg build must be compiled with the --enable-libass library. Most pre-compiled modern builds of FFmpeg include this by default. You can verify this by running ffmpeg in your terminal and looking for --enable-libass in the configuration output.

Basic Syntax

The most straightforward way to burn external subtitles (such as .srt or .ass files) into a video is by using the -vf (video filter) flag followed by the subtitles filter.

ffmpeg -i input.mp4 -vf "subtitles=subtitle.srt" output.mp4

In this command: * -i input.mp4 specifies the input video. * -vf "subtitles=subtitle.srt" applies the subtitle filter using the file subtitle.srt. * output.mp4 is the resulting video file with the subtitles permanently burned in.

Handling File Paths and Escaping

FFmpeg’s filtergraph requires strict escaping for special characters, including colons and backslashes. This often causes errors when using absolute file paths on Windows.

The easiest workaround is to place the subtitle file in the same directory as your command line prompt and use relative paths:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt" output.mp4

If you must use an absolute path, you must escape the colon and use forward slashes:

• Windows absolute path: C:\path\to\subs.srt becomes "subtitles='C\\:/path/to/subs.srt'"
• Linux/macOS absolute path: /path/to/subs.srt becomes "subtitles='/path/to/subs.srt'"

Example command for Windows:

ffmpeg -i input.mp4 -vf "subtitles='C\\:/path/to/subs.srt'" output.mp4

Burning Embedded Subtitles

If your source video (such as an .mkv file) already contains soft subtitles, you can burn those existing subtitles into the video stream without pointing to an external file.

ffmpeg -i input.mkv -vf "subtitles=input.mkv" output.mp4

If the input file contains multiple subtitle tracks, FFmpeg will default to the first one. You can select a specific subtitle stream using the stream index (si) parameter:

ffmpeg -i input.mkv -vf "subtitles=input.mkv:si=1" output.mp4

(Note: si=0 is the first subtitle track, si=1 is the second, and so on.)

Customizing Subtitle Style

If you are using SubRip (.srt) subtitles, you can customize the font, size, and colors using the force_style option. This option uses ASS (Advanced SubStation Alpha) style parameters.

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='Fontname=Arial,Fontsize=20,PrimaryColour=&H00FFFF,Alignment=2'" output.mp4

Key style parameters include: * Fontname: The name of the font installed on your system (e.g., Arial, Verdana). * Fontsize: The size of the text. * PrimaryColour: The text color represented in BGR (Blue, Green, Red) hexadecimal format prefixed by &H. &H00FFFF represents yellow. * Alignment: The position of the text on the screen. 2 represents bottom-center, while 6 represents top-center.