Fix subtitle sync with Whisper, because
handgare for cowards.
You downloaded subtitles. The first line pops up during the studio logo. By the third act, characters are reacting to things that haven't happened yet. You've spent 20 minutes in VLC tapping keys and you're 90% sure you made it worse.
Suba rips a minute of audio from a dialogue-heavy part of your video, transcribes it with Whisper, matches the transcription against the subtitle file, and tells you the offset. Then it writes out a corrected SRT so you can stop thinking about this.
You need ffmpeg and uv. Then:
uv tool install git+https://github.com/xy3/suba --with openai-whisperThat's it. One command — no clone, no build step.
suba subs.srt movie.mkv -o fixed.srtsuba <subtitles> <video> -o <output.srt|vtt>| Flag | What |
|---|---|
-o, --output |
Write corrected SRT/VTT |
-m, --model |
Whisper model (base, small, medium, large) |
-d, --duration |
Audio duration in seconds (default 60) |
-t, --start |
Manual start time in seconds |
--threshold |
Minimum similarity to accept a match (default 0.2) |
- Finds the densest 60 seconds of subtitles (more lines = more talking, probably)
- Extracts that audio with ffmpeg
- Transcribes it with Whisper
- Slides windows of the transcription over each candidate subtitle line, scoring by text similarity and timestamp proximity
- Shifts all timestamps by the detected offset and writes a fixed SRT