retime-captions-to-words

Purpose

Captions authored by hand (or generated from an LLM transcript) frequently drift ±100–300 ms relative to actual word starts in the VO. This atom snaps each cue's start time to the nearest matching word from a whisper word-timestamps file, within a tolerance.

End times are recomputed to preserve the cue's original duration unless the next cue would overlap, in which case they butt up to the next cue's new start.

Inputs

• --input <path> — source .srt (required)
• --output <path> — destination .srt (required)
• --words <path> — whisper word-level timestamps JSON (required). Expected schema: {"words": [{"text": "...", "start": 1.234, "end": 1.456}, ...]}
• --tolerance <sec> — max snap distance (default 0.10)
• --preserve-duration <bool> — keep original duration after snap (default true)

Algorithm