Subtitle SRT/VTT checker and fixer

What it does

Reads subtitle files (.srt / .vtt) and produces a list of problems plus a fixed copy. The original file is never changed.

• Sorts out-of-order cues, shortens cues that overlap the next one, repairs cues whose end is before their start, removes empty cues
• Extends cues that are too short or too fast to read, but only into the free time before the next cue
• Checks characters per second, line width and number of lines; full-width characters count as two columns, so Japanese subtitles are measured correctly
• Optional: cut overly long cues, re-break lines that are too wide, enforce a minimum gap between cues
• Converts SRT to VTT and VTT to SRT, reporting anything SRT cannot hold (positioning, voice tags)
• Lists every change and every remaining issue with the original cue number, on screen and as JSON

How to use

python scripts/subfix.py check input.srt
python scripts/subfix.py fix input.srt -o input.fixed.srt --report report.json
python scripts/subfix.py convert captions.vtt -o captions.srt

Ask your agent to check and fix a subtitle file. It shows the check result, confirms the limits, writes the fixed copy and suggests how to handle what could not be fixed automatically.

Requirements

• Python 3 (standard library only)

Caveats

• Default limits (English 17 chars/s and 42 columns, Japanese 4 chars/s and 13 full-width characters x 2 lines) are conservative starting points. Use your platform's or client's numbers when you have them.
• Japanese line re-breaking has no dictionary and may split a word; review the result.
• Subtitle wording is never changed, only timing and line breaks.