Skip to content
Skills Library
Marketing & content · Building & coding

captions

/captions

Burns captions into a spoken video and adds an animated lower third (name, role, optional logo). Transcribes locally with whisper.cpp (English, Portuguese or any whisper language), groups words into cues that never split a locked expression, paints highlight terms in an accent color, and composes everything at 1080p with ffmpeg. Outputs the MP4 plus a loose .srt. Use when the user asks to "caption this video", "add subtitles", "burn in captions", "add a lower third", "name card for the speaker", "legendar esse vídeo", "põe legenda", or hands over a talking-head clip to publish on LinkedIn, Ree

Licence
MIT
Last repository change
30.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
5
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 30.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 5 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/02_cues.py, scripts/03_card.py, scripts/04_overlay.py, scripts/lib.py, scripts/run.sh

What it does and when to use it

Burns captions into a spoken video and adds an animated lower third (name, role, optional logo). Transcribes locally with whisper.cpp (English, Portuguese or any whisper language), groups words into cues that never split a locked expression, paints highlight terms in an accent color, and composes everything at 1080p with ffmpeg. Outputs the MP4 plus a loose .srt. Use when the user asks to "caption this video", "add subtitles", "burn in captions", "add a lower third", "name card for the speaker", "legendar esse vídeo", "põe legenda", or hands over a talking-head clip to publish on LinkedIn, Ree

Triggers from the description

caption this videoadd subtitlesburn in captionsadd a lower thirdname card for the speakerlegendar esse vídeopõe legenda
Original author description

Burns captions into a spoken video and adds an animated lower third (name, role, optional logo). Transcribes locally with whisper.cpp (English, Portuguese or any whisper language), groups words into cues that never split a locked expression, paints highlight terms in an accent color, and composes everything at 1080p with ffmpeg. Outputs the MP4 plus a loose .srt. Use when the user asks to "caption this video", "add subtitles", "burn in captions", "add a lower third", "name card for the speaker", "legendar esse vídeo", "põe legenda", or hands over a talking-head clip to publish on LinkedIn, Ree

How it works

  1. Usage
  2. Prerequisites
  3. What each stage does
  4. The two decisions that make the captions good
  5. Config (defaults.json)
  6. Look
  7. Known limits
Original SKILL.md headings · 140 lines, 1,045 words
SKILL.md preview
---
name: captions
description: Burns captions into a spoken video and adds an animated lower third (name, role, optional logo). Transcribes locally with whisper.cpp (English, Portuguese or any whisper language), groups words into cues that never split a locked expression, paints highlight terms in an accent color, and composes everything at 1080p with ffmpeg. Outputs the MP4 plus a loose .srt. Use when the user asks to "caption this video", "add subtitles", "burn in captions", "add a lower third", "name card for the speaker", "legendar esse vídeo", "põe legenda", or hands over a talking-head clip to publish on LinkedIn, Reels or YouTube.
---

# captions

Local pipeline, no external service. Input: a spoken video. Output: a 1920x1080
MP4 with burned-in captions and an animated lower third, plus a loose `.srt` to
upload alongside on LinkedIn or YouTube.

## Usage

```bash
./scripts/run.sh -i talk.mp4 -o talk_captioned.mp4 \
                 -n "Ada Example" -r "Head of Product" -l en
```

Portuguese (or any whisper language code; `auto` lets whisper detect it):

```bash
./scripts/run.sh -i fala.mp4 -o fala_legendada.mp4 -n "Ana Exemplo" -r "Coordenadora" -l pt
```

With your own config (deep merged over `defaults.json`, see `examples/`):

```bash
./scripts/run.sh -i talk.mp4 -o out.mp4 -c examples/config.en.json
```

Reusing the transcription from a previous run (useful to tune style, highlights,
locks and fixes without paying for whisper again):

```bash
./scripts/run.sh -i talk.mp4 -o out.mp4 -c my_config.json --skip-asr
```

Flags: `-i` input, `-o` output (default `<input>_captioned.mp4`), `-n` name,
`-r` role, `-l` language, `-c` config, `-w` work dir (default
`.work/<video-name>/` inside the skill), `--skip-asr`.

Without a name (no `-n` and no `card.name`) the lower third is skipped and the
captions stay at the low margin for the whole video.

## Prerequisites

- `ffmpeg` and `ffprobe` (`brew install ffmpeg`)
- `whisper-cli` (`brew install whisper-cpp`) and a `ggml-*.bin` model. The default
  path is `~/.cache/whisper/ggml-large-v3-turbo.bin`. Download it once (about 1.6 GB):

  ```bash
  mkdir -p ~/.cache/whisper && curl -L -o ~/.cache/whisper/ggml-large-v3-turbo.bin \
    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
  ```

  Any other ggml model works: point `whisper_model` in your config at it.
- Python 3 with Pillow (`pip3 install pillow`)

**Heads up:** Homebrew's ffmpeg usually ships without `libass` and without
`drawtext`. That is why this pipeline does not use any ffmpeg caption filter:
captions and card are drawn as RGBA PNGs with Pillow and composed with a single
`overlay`. Side benefit: full control over kerning, outline, shadow and easing.

## What each stage does

| Stage | File | Input -> output |
|---|---|---|
| 1 | `run.sh` (inline) | video -> `audio.wav` -> `words.json` (whisper `-ml 1`, one timestamp per token) |
| 2 | `scripts/02_cues.py` | `words.json` -> `cues.json` + `captions.srt` |
| 3 | `scripts/03_card.py` | config -> `card.png` (RGBA with shadow) |
| 4 | `scripts/04_overlay.py` | `cues.json` + `card.png` -> `frames/%05d.png` |
| 5 | `run.sh` (inline) | video + frames -> final MP4 |

Intermediate files live in the work dir.

## The two decisions that make the captions good

**1. Grouping by dynamic programming, not greedy.** A greedy version (fill the cue
up to the limit) splits a two-word term across two cues and leaves its last word
alone on screen. `02_cues.py` solves a DP that minimizes a cost made of: distance
from the ideal length, a penalty for breaking away from punctuation, and a penalty
for cues that are too short.

**2. Locked expressions.** Everything in `highlights` or `locked` becomes a
forbidden boundary: the DP cannot cut there, and the line break inside a cue also
avoids that point. That is what keeps "August 10th", "6 in the evening", "public
hearing" and proper names whole. Measured on the test clip with a tight
`max_cue` of 30: without locks the DP produced "No dia 10 / de agosto" and "A
rede de / ciclovias liga"; with locks it produced "No dia / 10 de agosto" and
"A rede de ciclovias / liga".

Run stage 2 alone (with `--skip-asr`, it is the first thing printed) and read the
cue list in the terminal before spending the render minutes. It is cheap and it
is where problems show up. Highlighted runs print in `[brackets]`.

Lock the form whisper actually writes, not the one you say: whisper writes
numbers as digits ("10 de agosto", "6 in the evening"), so a lock on "six in the
evening" never matches.

## Config (`defaults.json`)

| Key | What it does |
|---|---|
| `lang` | whisper language (`en`, `pt`, ... or `auto`). `-l` overrides it |
| `whisper_model` | path to the ggml model |
| `highlights` | terms painted in `theme.accent`, whole words only, case insensitive. Locked automatically |
| `locked` | expressions that never split, even without highlight |
| `fix` | transcription corrections, lowercase word -> right form, applied word by word (trailing punctuation kept) |
| `theme.accent` / `bar` / `background` / `text` / `muted` | highlights (Beacon #EF681E), card edge bar (Cobalt #1D4AA5; falls back to `accent` when empty), card background (Ink #12141A), caption and name text (Field #F3EFE5), role text (Slate #8195B0) |
| `card.name` / `role` | lower third text. `-n` and `-r` override them. Empty name = no card |
| `card.logo` | optional PNG with alpha (white logo on transparent works best), drawn after a thin divider. Relative paths resolve from the skill root |
| `card.in_at` / `out_at` | when the lower third enters and leaves (seconds) |
| `caption.margin_low` / `margin_high` | caption baseline outside and during the card window |
| `caption.max_line` / `max_cue` | 34 and 62 characters, calibrated for 58px at 1080p |
| `caption.font`, `card.font_name`, `card.font_role` | TTF paths |

## Look

Font: Manrope SemiBold (captions and name) and IBM Plex Mono Medium (role, a
label), shipped in `assets/fonts/` under the SIL Open Font License
(`assets/fonts/Manrope-OFL.txt`, `assets/fonts/IBMPlexMono-OFL.txt`).

Colors: the default theme is the repo palette. The accent is reserved for the
highlighted terms (the one thing to notice); the card edge is structure, so it
uses `theme.bar` and never competes with a highlight.

Card: edge bar on the left, name, role, and an optional divider plus logo.
It slides in from the left with a cubic ease-out over 0.55s, holds, and leaves
with a fade plus a push to the left. While it is on screen the captions rise to
`margin_high` so they never collide.

## Known limits

- Calibrated and tested on 16:9 sources rendered at 1920x1080. The input is scaled
  to `out_w` x `out_h` without letterboxing, so a source with a different aspect
  ratio gets stretched. `out_w`/`out_h` accept 9:16, but then `max_line` has to
  drop (around 22 characters) and the card has to shrink. Not validated in that
  format.
- The PNG sequence takes about 100 MB per minute of video. The work dir can be
  deleted after the render.
- Audio is normalized to -16 LUFS / -1.5 dBTP, the usual target for social
  networks. For another target, change the `loudnorm` in `run.sh`.
- `fix` matches single words only.
Files in this package (15)
  • .gitignore 1 KB
  • SKILL.md 7 KB
  • TESTED.md 5 KB
  • defaults.json 1 KB
  • assets/fonts/IBMPlexMono-Medium.ttf 153 KB
  • assets/fonts/IBMPlexMono-OFL.txt 4 KB
  • assets/fonts/Manrope-OFL.txt 4 KB
  • assets/fonts/Manrope-SemiBold.ttf 142 KB
  • examples/config.en.json 1 KB
  • examples/config.pt.json 1 KB
  • scripts/02_cues.py 6 KB
  • scripts/03_card.py 3 KB
  • scripts/04_overlay.py 4 KB
  • scripts/lib.py 1 KB
  • scripts/run.sh 4 KB

Versions

RepositoryScoreLicence
This page · zuckenbert/video-from-code100MIT
jameslashmar/chroma-ae-mcp100AGPL-3.0
alfaris/full-production-studio100MIT
evanbaker315/attentionos100MIT
zaddy99999/video-editing-skills100MIT
ZeroPointRepo/youtube-skills100MIT
ZeroPointRepo/youtube-skills100MIT
Rudywizz/rudywizz-motion96MIT
Liamrjohnston/ai-video-editor-v286MIT

Database snapshot: 13.11.2026 · package version 84c2ef07d0e3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100burn-subtitles
    Generate subtitles (whisper.cpp / faster-whisper) for a video and either save the SRT alongside or burn them into the picture. Use when the user says "subtitle this", "add captions", "burn subtitles", "transcribe and caption this video", "generate SRT for this". Accepts an…
  • 100media-whisper
    Speech-to-text transcription and subtitle generation with whisper.cpp and faster-whisper: extract spoken text from audio/video, generate SRT/VTT subtitles, translate speech to English, word-level timestamps, multilingual support, speaker diarization optional. Use when the user…
  • 100add-subtitles
    Add burned-in subtitles to a video the user uploads or points to on disk. Use when the user provides a local video file (mp4/mov/etc.) and wants captions/subtitles added to it. Transcribes the audio with Whisper and burns styled captions directly into the video.
  • 100captions-subtitles
    Create, edit, translate and burn in captions and subtitles - transcribe speech with Whisper, write SRT/VTT/ASS files, style them, and hard-burn word-highlight captions for Shorts, Reels and TikTok. Use for any captioning, subtitle, transcript or accessibility request.
  • 100caption-animation
    This skill should be used when the user asks to "add animated captions", "make TikTok captions", "karaoke captions", "word-by-word subtitles", "auto subtitles", "highlight the active word", "burn in captions to a video", "sync captions to a voiceover/narration", or "turn an…
  • 100video-subtitles
    Generate SRT subtitles from video/audio with translation support. Transcribes Hebrew (ivrit.ai) and English (whisper), translates between languages, burns subtitles into video. Use for creating captions, transcripts, or hardcoded subtitles for WhatsApp/social media.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.