Add subtitles to a video with FFmpeg

ffmpeg -i input.mp4 -vf "subtitles=captions.srt" -c:v libx264 -crf 23 -preset medium -c:a copy subtitled.mp4

Renders each cue of captions.srt onto the frames at the right time with libass default styling (white text, black outline, bottom centre) and re-encodes the video; the audio is copied. The bottom band of the frame at 1.5 s went from a peak luma of 228 to 248, i.e. the white text is there.

Flags, explained

subtitles=captions.srt

Render the subtitle file onto the video with libass. SRT, ASS, SSA, WebVTT and subtitle streams inside media files are accepted.

force_style=...

Override the ASS style: FontName, FontSize, PrimaryColour, OutlineColour, Outline, Shadow, Alignment, MarginV and the other [V4+ Styles] fields.

-c:s mov_text

Encode the subtitle stream in the MP4-native text format. MKV would take -c:s srt or copy instead.

-map 0 -map 1

Take every stream of the video and the subtitle file. Without explicit maps FFmpeg keeps one stream per type and may drop the subtitles.

-metadata:s:s:0 language=eng

Tag the first subtitle stream with a language so players list it properly.

ass=captions.ass

Same renderer, but the file is read as ASS with its own styles, positions and effects.

Variants

ffmpeg -i input.mp4 -vf "subtitles=captions.srt:force_style='FontName=DejaVu Sans,FontSize=28,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,MarginV=40'" -c:v libx264 -crf 23 -preset medium -c:a copy subtitled.mp4

ffmpeg -i input.mp4 -i captions.srt -map 0 -map 1 -c copy -c:s mov_text -metadata:s:s:0 language=eng subtitled.mp4

ffmpeg -i input.mp4 -vf "ass=captions.ass" -c:v libx264 -crf 23 -preset medium -c:a copy subtitled.mp4

ffmpeg -i input.mp4 -vf "subtitles='sub dir/my captions.srt'" -c:v libx264 -crf 23 -preset medium -c:a copy subtitled.mp4

Pitfalls we hit

• A build without libass gives a misleading error: the Homebrew FFmpeg 9.0.1 on macOS answered "No option name near 'captions.srt'" to the exact same command that works on a build with --enable-libass. Check ffmpeg -buildconf before debugging the syntax.
• Hardcoding always re-encodes the video; -c:v copy with the subtitles filter is an error. Expect the full encode time of the file.
• Timing comes from the subtitle file, not from -ss. If you trim with -ss before -i and burn in the same command, the cues shift: cut first, then burn, or use the setpts-aware ass filter with a shifted file.
• mov_text tracks are ignored by most social platforms and by many HTML5 players; when the subtitles must be seen, burn them.
• ASS colours are &HAABBGGRR. &H0000FF is red, not blue, and the leading AA is alpha where 00 means opaque.

The same edit as a typed operation

add_subtitles_to_video takes the video and the SRT as two named inputs and burns the cues in on workers that ship libass and fonts, so there is no build to check and no path to escape. The caller gets a signed MP4 URL back.

{
  "inputs": [
    { "id": "main", "url": "https://example.com/video.mp4" },
    { "id": "captions", "url": "https://example.com/captions.srt" }
  ],
  "options": {}
}

FAQ