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
.srtwith 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 andmaxChars(24) characters. - A block ends after punctuation (
. , ; : ! ?), before a pause longer thanpauseBreak(0.4 s), and at every.srtcue 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
- Run with
--dry-runfirst. 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. - Run for real. The JSON report repeats the blocks and adds a
warningif any caption does not fit in the frame. - 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. - If the captions cover something important, change
positionorsafeAreaand run again.
Style
Pass only the keys you want to change in --style style.json. Unknown keys are an error.
| Key | Default | Meaning |
|---|---|---|
fontFamily | system UI stack | Any CSS font-family available on the machine. |
fontSize | 7 % of the shorter side | In px. |
fontWeight | 800 | |
lineHeight, letterSpacing | 1.15, "0" | |
uppercase | false | |
color | #FFFFFF | Text colour. |
highlightColor | #FFD84D | Colour of the word being spoken. null turns the highlight off. |
outlineColor, outlineWidth | #000000, 9 % of the font size | 0 removes the outline. |
shadow | soft dark shadow | CSS text-shadow, or null. |
boxColor | null | For example "rgba(0,0,0,0.7)" to put the text in a box. |
boxPadding, boxRadius | 0.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, maxChars | 3, 24 | Block size. |
pauseBreak, hold | 0.4, 0.3 | Seconds. |
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.