FFMPEG An Intermediate Guide/subtitle options

Subtitle Background

Subtitles may come either from a separate text file (typically with a .srt extension) or from a dedicated stream within the video file. In the latter case, the subtitles are typically stored not as text but as bitmaps that are overlayed on the video and may be referred to as "VOBSUBs" for DVDs or "PGS" for Bluray.

Note that a subtitle stream need not be present for the entirety of the video and may first appear only when the first subtitled dialogue occurs. Thus, the subtitle stream may not be detected and listed by:

 ffmpeg -i <input>

which only searches a short distance into the input file.

To coerce ffmpeg to search further for the subtitle stream, use options:

 -probesize <bytes> -analyzeduration <microseconds>

which will cause ffmpeg to search until the first of those limits is reached. Note that both of these options must appear on the command line before the specification of the input via -i. For example:

 ffmpeg -probesize 50M -analyzeduration 100M -i vts.vob

will search through vts.vob for all streams until it has read 50 MB of data or 100 seconds of video, whichever comes first.

Outputting Subtitles

Subtitles may be included in an encoded video file as a parallel stream, or may be rendered permanently (aka "burned") into the video itself.

Encoding Subtitles to an Output Stream

ffmpeg -i "INPUT" [-sub_charenc [character encoding]] -i "SUBTITLE_INPUT" 
        -vcodec [codec] -acodec [codec] -scodec [codec] [...] "OUTPUT"

Set Subtitles Character Encoding Conversion

Set input text subtitles character encoding conversion

-sub_charenc [character encoding]

If you want to import and encode a subtitle plaintext file (Windows/ANSI) which contains special characters of some languages (like French, German, Italian, Spanish and so on) this option is needed for subtitle encoding conversion from Windows/ANSI to UTF-8.

[character encoding] parameter examples:
CP1252, CP874, CP936, CP1250, ... , CP1258,
LATIN1 , LATIN2 , ... , LATIN8, LATIN-9, LATIN10,
ISO-8859-1, ISO-8859-2, ... , ISO-8859-16,
UTF-8, UTF-16, UTF-32
UNICODEBIG, UNICODELITTLE

See also: sub_charenc_parameters.txt in #2431

Notes:
[-sub_charenc [character encoding]] is not mandatory, but whenever used, it must be placed right before the reference of the subtitle to be processed with that encoding.
When you set the subtitle encoding, don't forget to also set a subtitle codec (see below). The subtitle code page will not be converted if you use -c:s copy!
If you try to import ANSI subtitle files with a newer version of FFmpeg without using of "-sub_charenc" you can get an error message like:
Invalid UTF-8 in decoded subtitles text; maybe missing -sub_charenc option
Then you have to use option "-sub_charenc" to define the right coding format or code page of subtitle file.

Set Subtitle Codec

Force to set subtitle codec ('copy' to copy stream)

-scodec [subtitle codec]

Not every subtitle codec can be used for every video container format!

[subtitle codec] parameter examples:
for MKV containers: copy, ass, srt, ssa
for MP4 containers: copy, mov_text
for MOV containers: copy, mov_text

Note:
Many Philips Blu-Ray Players, Samsung Smart TV's and other standalone players can only read "SRT" subtitle streams in "MKV" files.

Set Subtitle Language

Set subtitle language using the ISO 639 language code (3 letters)

-metadata:s:s:[stream number] language=[language code]

-metadata:s:s:0 ... that means to set the metadata for ... Stream:Subtitle:Number of stream, starting with 0

[language code] parameter examples:
eng - English
fre or fra - French
ger or deu - German
ita - Italian
spa or esp - Spanish

FFmpeg command-line examples to importing subtitle files

Import a subtitle file (copy video/audio streams, without re-encoding)

ffmpeg -i input.mp4 -sub_charenc CP1252 -i subtitle.srt -map 0:v -map 0:a -c copy -map 1 -c:s:0 mov_text -metadata:s:s:0 language=ger output.mp4

ffmpeg -i input.mkv -sub_charenc CP1252 -i subtitle.srt -map 0:v -map 0:a -c copy -map 1 -c:s:0 srt -metadata:s:s:0 language=fre output.mkv

or

ffmpeg -i input.mp4 -sub_charenc CP1252 -i subtitle.srt -vcodec copy -acodec copy -scodec mov_text -metadata:s:s:0 language=ger output.mp4

ffmpeg -i input.mkv -sub_charenc CP1252 -i subtitle.srt -vcodec copy -acodec copy -scodec srt -metadata:s:s:0 language=fre output.mkv

Example for 2 separate .srt subtitle files:

ffmpeg -i input.mp4       -i subtitle_eng.srt -i subtitle_fre.srt \
       -map 0:v -map 0:a  -map 1              -map 2              \
       -c:v copy -c:a copy -c:s copy                              \
       -metadata:s:s:0 language=eng -metadata:s:s:1 language=fre  \
  output.mkv

Import subtitle and re-encode video/audio streams

ffmpeg -i input.mov -sub_charenc WINDOWS-1252 -i subtitle.srt -vcodec h264 -acodec mp3 -scodec mov_text -metadata:s:s:0 language=spa output2.mp4

ffmpeg -i input.avi -sub_charenc ISO-8859-1 -i subtitle.srt -vcodec h264 -acodec ac3 -scodec srt -metadata:s:s:0 language=ita output2.mkv

Rendering Subtitles into the Video

Subtitles may be rendered permanently into the video stream by specifying a complex filter on the command line:

 -filter_complex "[0:v][0:s]overlay"

This can be interpreted as "take all video streams from the first listed input, then all subtitle streams from the first listed input, and overlay the latter on the former to produce a single video stream that replaces all consumed streams". The new stream will be mapped by the encoder as any video input stream normally would.

Subtitle Color

For VOBSUBs (ie. bitmapped subtitles on DVDs), the color of the subtitles is determined by a palette that is specified in a .IFO file on the DVD, but this is not available to ffmpeg and thus the colors of subtitles will be largely arbitrary unless the palette is specified on the command line with:

 -palette "<list of 16 comma-separated RRGGBB hex codes>"

Unfortunately, the palette entries used to render the subtitles vary from one video to the next, so some experimentation is required. Typically one entry will determine the font color and another entry will determine the outline color, though some videos have subtitles that use multiple outlines, each with its own palette entry.

Example

The full command line to search relatively deeply for a subtitle stream and then render it in green on black into an h264 output video might look as follows:

 ffmpeg -probesize 100M -analyzeduration 120M -palette "ffffff,000000,ffffff,00ff00,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff,ffffff" -i input.vob -filter_complex "[0:v][1:s]overlay" -acodec copy -vcodec libx264 output.mp4