FFMPEG An Intermediate Guide/subtitle options
- 1 Subtitle Background
- 2 Outputting Subtitles
- 2.1 Encoding Subtitles to an Output Stream
- 2.1.1 Set Subtitles Character Encoding Conversion
- 2.1.2 Set Subtitle Codec
- 2.1.3 Set Subtitle Language
- 2.1.4 FFmpeg command-line examples to importing subtitle files:
- 2.2 Rendering Subtitles into the Video
- 2.1 Encoding Subtitles to an Output Stream
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 dialog 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.
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
[-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.
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:
for MP4 containers:
for MOV containers:
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
fra - French
deu - German
ita - Italian
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
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
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:
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.
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.
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