// the find
smacke/ffsubsync
Automagically synchronize subtitles with video.
ffsubsync automatically fixes subtitle timing drift by using VAD + FFT cross-correlation to align a binary speech-activity signal from audio against the on/off pattern from an SRT file. It's a CLI tool aimed at anyone who downloads subtitles that are a few seconds off from their video file. Handles the ~95% case (constant offset) well; non-linear splits are explicitly out of scope.
- The algorithm is well-chosen and clearly explained: discretize both streams to 10ms binary windows, then use FFT to compute cross-correlation in O(n log n) instead of O(n²). Not a black box.
- Language-agnostic — it never does speech-to-text, only speech detection, so it works equally well for any spoken language without model downloads.
- Practical escape hatches are documented: --gss for framerate search, --vad=auditok for noisy audio, --max-offset-seconds for edge cases, and srt-to-srt mode that skips audio extraction entirely and runs in under a second.
- Active maintenance (last push 2026), typed with mypy, formatted with black, has CI and a real test suite including integration tests.
- Only handles a single constant time offset. If the subtitle file has internal splits or gaps relative to the video (e.g., recap scenes cut from video), it fails silently and produces a best-effort result that may still be wrong in places — this has been an open issue (#10) since the project started.
- Hard dependency on ffmpeg being installed and on PATH, plus py-webrtcvad which has native extension build issues on some platforms (especially Windows without MSVC). The install story is not entirely 'pip install and go'.
- The sklearn_shim.py file exists because the project copies pipeline/transformer scaffolding from scikit-learn rather than depending on it — that's a maintenance liability and the abstraction doesn't add much given the small number of actual transformers.
- No support for subtitle formats beyond SRT (ASS/SSA, VTT, etc.) in the main sync path, which is a real limitation since ASS is the dominant format for anime fansubs.