Every Shorts creator knows the look: words lighting up one by one as they're spoken. It's also the headline feature of the paid caption tools — Submagic's Starter is $19 a month for 15 videos, 2 minutes each, and your unreleased video uploads to their cloud to get captioned (submagic.co/pricing, read 2026-11-04).
But if you already have a transcript — and if you script your videos or run Whisper, you do — the remaining job is much smaller than a subscription: style the SRT, burn it in. That's all shorts-caption-studio does, locally, in pure Python standard library.
pipx install shorts-caption-studio
# or: pip install shorts-caption-studio
shorts-caption-studio video.mp4 --captions video.srt # pop, burned in
shorts-caption-studio --ass-only video.srt -o video.ass # just the sidecar
Three styles, all composed for vertical 1080x1920 with margins that keep text out of the Shorts UI zones:
- pop — one event per word; the spoken word switches to accent yellow at 120% scale.
-
karaoke — one event per cue with
\kfsweep tags; each word fills grey → accent. - clean — plain white, no highlight, bottom-third safe margin.
Watch it run (22 seconds): the demo video is the tool's own bundled example — the pop burn into the demo clip (12 caption events, the word timing labelled ESTIMATED on screen, exactly as the tool prints it), then the karaoke and clean styles emitted as styled .ass sidecars. Watch the demo
The part I refused to fake: the word timing
Here's the honest problem with building this from an SRT. Whisper-style SRTs carry timing per cue, not per word. There is no word timing in the input — so this tool estimates it, splitting each cue's duration proportionally to word length (longer word, longer on screen).
It looks like real word timing, and for short, punchy cues it works well. But it is not true word-level alignment, and the tool says so everywhere it can: in the human report, in the --json output ("word_timing": "estimated"), in the README's honest-limits section, in the changelog. If you need frame-accurate sync, run a word-level aligner upstream first — then this tool will happily style the result. What it won't do is let you believe a length-proportional split was measured from your audio.
Same rule for broken input. A cue that ends before it starts, or has no text, is skipped with a named warning and exit code 1 — never silently dropped, because a skipped cue is a caption missing from your render and you deserve to know:
$ shorts-caption-studio --ass-only examples/messy.srt -o messy.pop.ass --style pop
shorts-caption-studio v1.0.0 — ass-only
Captions: messy.srt — 2 cues, 11 words
ASS written: messy.pop.ass (11 events)
WARN: cue #2 skipped (invalid-timing: end 1.500s <= start 2.000s)
WARN: cue #3 skipped (empty-text: cue has no text)
(exit code: 1)
Two implementation details that matter
The styled .ass is generated explicitly. Burn-in goes through ffmpeg's subtitles filter pointed at a real, styled .ass file — because that filter silently ignores force_style. Generators that rely on force_style ship unstyled captions and never notice. (Ask me how I know.)
A failed render leaves nothing behind. If ffmpeg fails, any partial output is deleted. An output file existing is proof of a successful run; exit 2 with a clean ERROR: (never a traceback) is what failure looks like. And the input video is never overwritten — --out pointing at it is refused.
The boring parts that make it trustworthy
-
43 tests, standard library only. Word-split math both directions, ASS escaping (with a test proving commas survive verbatim in the text field — they're legal there), every style's UI-safe margins, karaoke's
\kfdurations summing to the cue, every CLI error path, JSON/text agreement — and a real ffmpeg integration test that generates a vertical video, burns captions in, and probes the result. -
--jsonon both modes, one object, same numbers and exit codes as the text report; errors are{"error": ...}, argparse usage errors included. There's aSKILL.mdat the repo root for agents, with the honesty rules written as constraints. - Local only. No network code. It reads the video and SRT you point it at and writes the one output you asked for. For faceless channels posting daily, "no per-video quota and nothing uploads" is the whole pitch.
What it deliberately doesn't do
No transcription (bring an SRT). No VTT, no format converting — SRT in, .ass or burned video out. No timing repair or offset shifting. Three styles, one font, no per-word customisation yet. The README's honest-limits section says all of this before the reference material, not after it.
It's the caption step for my own faceless Shorts channels — every video's Whisper SRT goes through it on the way to publishing — and it's MIT. If you already have transcripts, it might retire a subscription line for you too.
pipx install shorts-caption-studio
Top comments (0)