Communitygithub.com

burn-captions

Burns word-timed captions into a video, in short blocks of one to three words that appear exactly on the frame the first word is spoken, with the spoken word highlighted, using headless Chrome for the text and ffmpeg for the overlay. Use it when the user says "add captions", "burn subtitles into this video", "put the words on screen", "caption this reel" or "hardcode the subtitles".

Qu'est-ce que burn-captions ?

burn-captions is a Claude Code agent skill that burns word-timed captions into a video, in short blocks of one to three words that appear exactly on the frame the first word is spoken, with the spoken word highlighted, using headless Chrome for the text and ffmpeg for the overlay. Use it when the user says "add captions", "burn subtitles into this video", "put the words on screen", "caption this reel" or "hardcode the subtitles".

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MIQUELZAVALA/cutroom/tree/HEAD/skills/burn-captions

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Burn captions

Takes a video and a list of words with times, and writes a new video with the captions burned in. The audio stream is copied untouched.

When to use it

  • The user wants open captions (part of the picture), typically for vertical social video.
  • You already have word timestamps, or an .srt. This skill does not transcribe: get the words from a speech-to-text tool that outputs per-word times, or from the voice generator that produced the audio.
  • Not for soft subtitles (a separate track the viewer can turn off): mux the .srt with ffmpeg instead.

Command

node skills/burn-captions/scripts/burn_captions.mjs <video> --words words.json --out out.mp4 \
  [--style style.json] [--dry-run]

Needs Node 20+, ffmpeg, a local Chrome or Chromium, and npm install run once in skills/burn-captions/. If Chrome is not found, set CUTROOM_CHROME to its executable.

words.json, times in seconds from the start of the video:

[
  { "text": "Captions", "start": 0.50, "end": 0.95 },
  { "text": "that", "start": 1.00, "end": 1.20 }
]

Punctuation stays attached to its word ("frame,"). An object with a words array and the key word instead of text are also accepted. An .srt works too: each cue's time is shared out among its words by length, so blocks are exact at cue starts and approximate inside a cue.

How words become captions

  • Blocks of up to maxWords (3) words and maxChars (24) characters.
  • A block ends after punctuation (. , ; : ! ?), before a pause longer than pauseBreak (0.4 s), and at every .srt cue boundary.
  • A block appears whole on the frame that contains the start of its first word, and leaves when the next block arrives or hold (0.3 s) after its last word, whichever comes first.
  • The word being spoken takes highlightColor.

Workflow

  1. Run with --dry-run first. It prints every block with its first and last frame, without Chrome or an encode. Check the grouping reads naturally; fix the words file or the grouping keys if not.
  2. Run for real. The JSON report repeats the blocks and adds a warning if any caption does not fit in the frame.
  3. Extract one frame inside a block and look at it: ffmpeg -ss <seconds> -i out.mp4 -frames:v 1 check.png. Check position, size and contrast against the footage.
  4. If the captions cover something important, change position or safeArea and run again.

Style

Pass only the keys you want to change in --style style.json. Unknown keys are an error.

KeyDefaultMeaning
fontFamilysystem UI stackAny CSS font-family available on the machine.
fontSize7 % of the shorter sideIn px.
fontWeight800
lineHeight, letterSpacing1.15, "0"
uppercasefalse
color#FFFFFFText colour.
highlightColor#FFD84DColour of the word being spoken. null turns the highlight off.
outlineColor, outlineWidth#000000, 9 % of the font size0 removes the outline.
shadowsoft dark shadowCSS text-shadow, or null.
boxColornullFor example "rgba(0,0,0,0.7)" to put the text in a box.
boxPadding, boxRadius0.25em 0.5em, 0.25em
position"bottom""top", "middle", "bottom" inside the safe area, or a number 0..1: the vertical centre as a fraction of the height.
safeArea{top: 0.1, right: 0.08, bottom: 0.16, left: 0.08}Margins the captions stay inside. Values up to 1 are fractions; larger values are px.
maxWords, maxChars3, 24Block size.
pauseBreak, hold0.4, 0.3Seconds.

Guidance: keep the default outline for footage, use a box over busy or bright pictures, and on vertical video for social platforms raise safeArea.bottom to about 0.25 so the captions clear the interface.

Limits

  • The video is re-encoded (H.264, CRF 18 by default; --crf, --preset). Audio is stream-copied.
  • Timing assumes a constant frame rate and timestamps that start at zero.
  • No animation: captions cut in and out.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills associés