There are two ways to add subtitles to a video with FFmpeg:

Soft subtitles : a separate text track the viewer can turn on or off. For MP4 that means converting the .srt to mov_text : ffmpeg -i in.mp4 -i subs.srt -map 0 -map 1 -c:v copy -c:a copy -c:s mov_text -metadata:s:s:0 language=eng out.mp4

Burned-in subtitles : the text is drawn into the pixels, so it shows everywhere, including players that ignore subtitle tracks: ffmpeg -i in.mp4 -vf "subtitles=subs.srt" -c:a copy out.mp4

Both commands are short. What goes wrong is everything around them: cue timings that drift from the speech, an .srt that MP4 refuses to carry, and an FFmpeg build that has no subtitles filter at all. This post builds the whole pipeline in Python, times the cues from the audio itself, and tests every step with pytest.…