Overview

Requires ffmpeg and ffprobe on PATH. `burn.py` also needs Pillow (installed via `uv run`). Scripts are Python 3.11+.

Recipes

Copy-paste command sequences agents can run via uv run.

Convert SRT to WebVTT for HTML5 players
uv run scripts/convert.py --input captions.srt --format vtt --output captions.vtt
Fix captions that start 1.5 seconds early
uv run scripts/shift.py --input captions.srt --offset-seconds 1.5
Extract embedded subtitles from MKV/MP4
uv run scripts/extract.py --input movie.mkv --output extracted.srt
Hardcode captions for social delivery
uv run scripts/burn.py --input clip.mp4 --subtitle captions.srt --output clip_subbed.mp4
Typical workflow after ASR

Operations

Each script returns structured JSON — see the script contract.

Op IDScriptCommon flags
subtitles.burnburn.py--input
subtitles.convertconvert.py--input
subtitles.extractextract.py--input, --output
subtitles.shiftshift.py--input

Do not use for

  • Automatic speech recognition (use `speech-captions`)
  • FCC/SCC compliance validation (use `captions-compliance`)
  • On-screen text / graphics QC (use `vision-analysis`)

Related cookbooks