Subtitle burner
Burn captions / subtitles onto a video via ffmpeg. Supports SRT, WebVTT, plain text. Presets: modern (white on black lower-third), minimal, bold (yellow, denser). Subcommands: burn, preview. Pure ffmpeg. Use when: 'add subtitles to my video', 'burn captions onto this MP4', 'subtitle my reel', 'добавь субтитры к видео', 'жёстко вшей субтитры'.From its SKILL.md
npx -y skills add Mikefluff/skills --skill subtitle-burnerAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
7.5 KB, as published. Nobody here has run it
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
transcribeskill (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-makerfor 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).
</objective>
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
-
Resolve input video:
<video>path — local MP4 / MOV / WebM.- Must exist + be readable.
-
Resolve subtitle source:
--subtitle <file>— SRT / VTT / TXT file--inline "<text>"— single caption applied to the entire video- File extension determines parser (
.srt/.vtt/.txt)
-
Parse cues:
- SRT: standard subtitle format with
index → timecode → textblocks. - VTT: WebVTT with
WEBVTTheader. - 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.
- SRT: standard subtitle format with
-
Apply style preset — see
references/ffmpeg-styling.md:modern(default): white text, black 60% backplate, lower-third, 48ptminimal: white text, no backplate, lower-third, 42ptbold: yellow text, dense black backplate, larger 56pt- Custom: override per-flag (
--font-size,--font-color,--box-color)
-
Burn via ffmpeg — calls
common.runners.ffmpeg.burn_captions. drawtext filter sequence, re-encodes video, copies audio. -
Output:
<video-dir>/<video-stem>-subtitled<ext>or
--output <path>for explicit destination.
MODES
Burn
subtitle-burner burn <video> --subtitle <file>
subtitle-burner burn <video> --inline "<single caption>"
subtitle-burner burn <video> --subtitle <file> --style modern|minimal|bold
subtitle-burner burn <video> --subtitle <file> --font-size 56 --font-color white
subtitle-burner burn <video> --subtitle <file> --output ./final.mp4
Preview (no burn)
subtitle-burner preview --subtitle <file>
subtitle-burner preview --subtitle <txt-file> --video <video> # txt requires video for timing
subtitle-burner preview --inline "<text>"
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 | SRT vs. VTT vs. plain-text — when to use which, format specifics, parsing edge cases |
| references/ffmpeg-styling.md | Style presets + per-flag customization, font selection, multilingual glyph support |
| references/troubleshoot.md | When captions don't render, font missing, sync drift, etc. |
EXAMPLES
See 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
WEBVTTheader; 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 — setFFMPEG_CAPTION_FONTenv 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 incommon/runners/ffmpeg.pydirectly (or PR a--positionflag). -
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 (
<video>-subtitled<ext>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 <video> --subtitle <file> --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 <file>.
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 <tmp>.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.