An ffmpeg cheatsheet

I recently had some need to clean up the subtitles in some video files in my possession. It took a little while to track down the exact set of options to get it to do what I wanted it to do, so I’ve written them down here for future reference. This post may be amended from time to time to add more

Extract subpictures from file

The second number in the -map parameter selects the (zero-indexed) stream to extract. Use something like mediainfo to determine which stream to select, then issue something like this:

ffmpeg -i src.m4v -c copy -map 0:2 dest.en.sup

Subtitle Edit can read subpictures and convert them to text subtitles. As long as you have a .NET runtime available, it should work; I’ve run it on Windows 11 and Gentoo Linux. Its accuracy is pretty good, especially if you have it use one of the Tesseract OCR engines.

Extract text subtitles from file

ffmpeg -i src.m4v -f srt dest.en.srt

“srt” can be replaced with several other formats (ssa, ass, etc.) if you want those. Depending on the source, there may be extra HTML formatting that you might want to use sed to filter out. If more than one subtitle stream is present, a “-map” parameter may be necessary to select the one you want.

Mux text subtitles into file

ffmpeg -i src.m4v -i src.en.srt -c copy -c:s mov_text -map 0:0 -map 0:1 -map 1:0 -metadata:s:2 language=eng -metadata title= dest.m4v

Assumptions: the desired video and audio are in the first two streams of the first file, and the subtitles are in English. (Audio language should already be set in that stream to whatever it is.)

“-metadata title=” will clear out the title string that might have been set in the original file.

Selecting tracks by language

Instead of needing to look up track numbers, it’d be nice to just specify the language(s) we want to include. That is possible, with something like this:

ffmpeg -i src.mkv -c copy -map 0:v:0 -map 0:a:m:language:ger -map 0:s:m:language:eng dest.mkv

This example selects German audio and English subtitles…useful for something like Das Boot or Deutschland 83. (Assuming that you like foreign shows in their original language with English subtitles, anyway…which I do.) These track mapping options should also apply in the preceding examples.

Extracting chapters from existing file

ffmpeg -i src.mkv -f ffmetadata src.metadata

This creates a file with chapter information (and possibly other metadata) structured like this:

;FFMETADATA1
encoder=Lavf60.3.100
[CHAPTER]
TIMEBASE=1/1000
START=0
END=728102
title=Chapter 1
[CHAPTER]
TIMEBASE=1/1000
START=728102
END=1319902
title=Chapter 2
[CHAPTER]
TIMEBASE=1/1000
START=1319902
END=2008965
...

Inserting chapters

A metadata file structured as above can be inserted into a file when it’s encoded:

ffmpeg -i src.mkv -i src.metadata -map_chapters 1 ...