Burn in subtitles
Draw a subtitle track directly onto video frames, permanently. In the browser only, like video-watermark (src/tools/video-watermark.ts), because compositing needs a decoded frame from WebCodecs, which Node has no equivalent of. Reuses src/subtitleFormats.ts to parse the subtitle file (SRT, VTT, ASS/SSA or SBV) rather than parsing it a second time. Cues whose timing runs past the end of the video are never reached, and reported in the result text rather than as an error. Always outputs MP4. Nothing is uploaded.
Runs on your device. The file is never uploaded.
Burn in subtitles paints cues from any of the five subtitle formats it reads onto the video frames themselves, writing MP4. Drop exactly two files, in either order; the subtitle extension decides which is which. Inline styling is stripped, so a cue authored bold is drawn plain. Compositing needs a WebCodecs decode, which Node lacks, so the CLI turns this one away.
Questions
What subtitle formats does it accept?
SRT, VTT, ASS, SSA and SBV, recognised by the file extension. Drop exactly two files, one video and one subtitle file, in either order, and the tool works out which is which. If neither has a recognised subtitle extension it refuses and lists the ones it knows: .srt, .vtt, .ass, .ssa, .sbv.
Why did my bold and italic subtitles come out plain?
Because the cue text is stripped of inline styling before it is drawn. Tags such as <b>, <i>, <c.class> and ASS override blocks are removed, and the canvas draws one plain style for every cue. The tool counts how many cues carried styling and tells you afterwards, so a caption authored bold and rendered plain is something you hear about rather than find out on playback.
Can I change how the subtitles look?
Only the size and whether they sit at the bottom or the top. fontSizePct is a percentage of the shorter side of the video, defaulting to 5, and must be a positive number up to 20. Everything else is fixed: bold sans-serif, white with a dark outline, centred, wrapped to 90 percent of the width, on a semi-transparent black band.
Why are some of my subtitles missing?
Most likely their timings run past the end of the video, so the frames that would have shown them do not exist. That is not treated as an error. The result text says how many cues start after the video ends and were never shown, along with the video duration, so you can check your timing offset.
Are the subtitles permanent?
Yes. They are drawn into the frames themselves, which is what burning in means, so no player can switch them off. The output is always MP4, named after your video with -subtitled.mp4 on the end. Every frame is decoded and re-encoded to make this possible, so expect a generation of quality loss and a real wait on long files.
Does it run outside the browser?
No. Compositing needs decoded frames from WebCodecs, which Node has no equivalent of, so the CLI and MCP surfaces refuse it with "video-burn-subtitles needs a browser (OffscreenCanvas). Use it at /video/video-burn-subtitles instead." Both files stay on your device; nothing is uploaded.