Subtitle Burner

Burn captions onto an existing video file. The user has a video (their own recording, a downloaded clip, output from reel-builder) and either has a subtitle file (SRT / VTT) OR wants plain text distributed across the video timeline.

Distinct from reel-builder:

• reel-builder generates the video itself (T2V) + can optionally burn its own captions.
• This skill takes an EXISTING video as input. No generation.

This skill does NOT:

• Generate the video — the input is yours.
• Auto-transcribe audio to captions — requires Whisper, planned for a separate transcribe skill (see ROADMAP).
• Translate captions between languages — pass already-translated subtitles.
• Re-encode video at different resolutions / formats beyond what ffmpeg's drawtext requires (output matches input resolution + codec where possible).
• Add audio (TTS overlay) — use voiceover-maker for that.
• Mix multiple subtitle tracks — single track per run.

Requires ffmpeg on PATH. install.sh offers to install it; otherwise brew install ffmpeg (Mac) / apt-get install -y ffmpeg (Debian).

ROLE

Read the input video + subtitle source → parse cues (SRT / VTT / plain text) → call ffmpeg drawtext filter for each cue with chosen styling → save the subtitled video → print the path.

PIPELINE

1. Resolve input video:

• `` path — local MP4 / MOV / WebM.
• Must exist + be readable.

1. Resolve subtitle source:

• --subtitle — SRT / VTT / TXT file
• --inline "" — single caption applied to the entire video
• File extension determines parser (.srt / .vtt / .txt)

1. Parse cues:

• SRT: standard subtitle format with index → timecode → text blocks.
• VTT: WebVTT with WEBVTT header.
• TXT: plain text, one cue per line, distributed evenly across the video duration (ffprobe used for duration detection).
• Inline: one cue starting at 0:00, ending at end-of-video.

1. Apply style preset — see references/ffmpeg-styling.md:

• modern (default): white text, black 60% backplate, lower-third, 48pt
• minimal: white text, no backplate, lower-third, 42pt
• bold: yellow text, dense black backplate, larger 56pt
• Custom: override per-flag (--font-size, --font-color, --box-color)

1. Burn via ffmpeg — calls common.runners.ffmpeg.burn_captions. drawtext filter sequence, re-encodes video, copies audio.

1. Output:

`` /-subtitled ` or --output ` for explicit destination.

MODES

Burn

subtitle-burner burn  --subtitle 
subtitle-burner burn  --inline ""
subtitle-burner burn  --subtitle  --style modern|minimal|bold
subtitle-burner burn  --subtitle  --font-size 56 --font-color white
subtitle-burner burn  --subtitle  --output ./final.mp4

Preview (no burn)

subtitle-burner preview --subtitle 
subtitle-burner preview --subtitle  --video    # txt requires video for timing
subtitle-burner preview --inline ""

Prints the parsed cue list (index, start/end timestamps, text) without burning. Useful to verify timing before committing.

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/subtitle-formats.md](references/subtitle-formats.md) | SRT vs. VTT vs. plain-text — when to use which, format specifics, parsing edge cases | | [references/ffmpeg-styling.md](references/ffmpeg-styling.md) | Style presets + per-flag customization, font selection, multilingual glyph support | | [references/troubleshoot.md](references/troubleshoot.md) | When captions don't render, font missing, sync drift, etc. |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: burn an SRT onto a TikTok export, plain-text captions distributed across a 30s reel, single inline caption for an entire 5s clip.

CONSTRAINTS

• ffmpeg required. No API calls; the skill is a pure ffmpeg wrapper. install.sh detects + offers install at setup time.

• Subtitle source parsing is strict. SRT must have valid timecodes (HH:MM:SS,mmm); VTT must have WEBVTT header; TXT must have ≥1 non-empty line.

• Plain text is distributed evenly. N lines across the video duration. Works for short videos with clear logical breaks; less ideal for narrative content where timing must match audio cues. For audio-synced captions, use a real subtitle tool (Whisper / Premiere / DaVinci) to produce SRT first.

• Output preserves video codec where possible. ffmpeg's drawtext requires re-encoding the video stream, so the output IS re-encoded (audio is copied as-is). For large files this can take seconds-to-minutes depending on duration.

• Default font may lack non-Latin glyphs. Cyrillic / CJK / Arabic captions may render as boxes on systems with only Latin-only default fonts. Workaround: specify --font /path/to/font-with-coverage.ttf (currently planned — set FFMPEG_CAPTION_FONT env var as a workaround in v1).

• Style presets are starting points. Most users want some tweak. The CLI accepts per-flag override (font-size, font-color, box-color).

• Position is lower-third by default. Hardcoded in ffmpeg.py:burn_captions. To change position: edit the drawtext filter in common/runners/ffmpeg.py directly (or PR a --position flag).

• Single text track per run. For multiple tracks (e.g., translation overlay + original): run twice, second time using the output of the first as input.

• No subtitle file is generated. Captions are burned INTO the video pixels — not soft-subtitles you can toggle off in a player. For toggleable subtitles, embed as a separate track via ffmpeg's -c:s mov_text (not handled by this skill).

• Never modifies the input file. Always writes to a new file (-subtitled or --output).

INVOCATION HINTS

When the user says any of:

• "add subtitles to my video", "burn captions onto this MP4"
• "subtitle my reel", "caption this video"
• "make the captions yellow and bold" (style customization)
• "I have an SRT file, apply it to this video"
• "добавь субтитры к видео", "вшей субтитры"
• "сделай надписи на видео"

Defaults: burn --subtitle --style modern. If only --inline text is given (no file), default to single-caption-across-whole-video.

If the user mentions a STYLE preference ("bold yellow" → --style bold; "minimal no background" → --style minimal; default "modern with black backplate"):

If the user mentions an SRT/VTT file → use --subtitle .

If the user mentions plain text (no file) AND a short list → use --inline for single caption OR write the text to a temp file and use it as --subtitle .txt.

This skill is distinct from:

• reel-builder — that GENERATES video + can burn captions inline. This is for existing video.
• voiceover-maker — that generates audio. This burns visual captions.
• subtitle-translator (planned, see ROADMAP) — translation; this is rendering.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mikefluff
• Source: Mikefluff/skills
• License: MIT
• Homepage: https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.