Subtitles

Subtitle file operations and burn-in. Use this skill when you need to work with caption files or embedded tracks — not automatic speech recognition (use speech-captions for that).

When to use

• This skill — SRT ↔ VTT conversion, sync offset, extract 0:s:0 subtitle stream, burn SRT into video.
• speech-captions — generate captions from spoken audio when no subtitle track exists.
• video-transformation — mux soft subtitles into a container, transcode, or re-wrap streams without burning.
• inspect — list streams and confirm a subtitle track exists before extract.py.

Gotchas

• Extract maps first subtitle stream only — extract.py uses -map 0:s:0. Multi-language containers may need manual ffmpeg maps for other indices.
• Burn re-encodes video — burn.py overlays PNG captions and outputs H.264 (libx264, CRF 20). Audio is stream-copied when present. Expect generation time to scale with cue count.
• Burn expects SRT — WebVTT must be converted with convert.py first. VTT timing and styling tags are not preserved on burn.
• Shift clamps to zero — negative offsets clamp cue starts at 0.0; very negative shifts can collapse short cues to a 0.1 s minimum duration.
• No libass dependency — burn uses Pillow text rendering with a simple bottom-centered box. Complex ASS styling (fonts, positioning, karaoke) is not supported.
• SRT vs VTT on shift — output format follows input extension (.srt or .vtt). Convert first if you need a different target format.