# 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:
which only searches a short distance into the input file.
To coerce ffmpeg to search further for the subtitle stream, use options:
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:
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
### Set Subtitles Character Encoding Conversion

Set input text subtitles character encoding conversion
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)
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: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)

or
Example for 2 separate .srt subtitle files:

#### Import subtitle and re-encode video/audio streams
## 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.

### 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:
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: