add-captions git:20261027.947a93eA

Immutable. This exact content never changes and is served at /api/v1/blob/b9ff7b3dec61f3ff.

---
name: add-captions
description: Add TikTok-style, karaoke, YouTube or minimal captions to your Remotion video. Gets word-level captions through the official remotion-captions flow (or line-level SRT via generate_subtitles), places one official caption element per clip, and applies a style preset with platform-safe placement.
---

# Add Captions: Animated Subtitles

You are helping the user add captions to their Remotion video.

**Load the `remotion-production` skill** for the `captions-workflow` rule (presets and safe zones), and the official **`remotion-captions`** skill for transcription and display. The official skill wins on any API detail.

## Workflow

### 1. Identify the Audio Source

Find the voiceover or primary audio file(s):

```bash
ls public/ public/footage/ 2>/dev/null | grep -E '\.(mp3|wav|m4a|ogg|mp4|mov|webm)$'
```

If no audio exists, suggest running `/add-voiceover` first. If the video has one voiceover per scene (`vo-scene1.mp3`, `vo-scene2.mp3`, …), caption **each file separately**.

Make sure Studio is already running (`npx remotion studio`, or `--no-open` with an in-app browser; open the URL it prints), so the user sees captions appear.

### 2. Choose Caption Style

Ask the user what style they want. The style decides which transcription route you need:

- **TikTok style** (default): bold, a few words at a time, the active word pops in a highlight color. *Needs word-level.*
- **Karaoke style**: full phrase on screen, words highlight as they're spoken. *Needs word-level.*
- **YouTube style**: bottom of screen, a sentence at a time. *Works with SRT.*
- **Minimal**: small, subtle, bottom-left. *Works with SRT.*

### 3. Transcribe

**Word-level (TikTok, karaoke):** follow official `remotion-captions/transcribe-captions.md`. It writes a Node script with `@remotion/whisper-webgpu` that outputs `Caption` JSON with one entry per word. It needs a compatible GPU and doesn't run on Linux arm64.

**Line-level (YouTube, minimal, or when whisper-webgpu can't run):**

```
Use remotion-media generate_subtitles:
- input_file: [filename inside public/, e.g. vo-scene1.mp3]
- output_name: [optional, e.g. subs-scene1]
```
Files land in `public/` of the directory your agent was launched from, so start your agent (Claude Code, Codex, Gemini CLI…) from the Remotion project root.

This returns an **SRT** file, and SRT is line-level. Convert it with `parseSrt()` from `@remotion/captions`, as official `import-srt-captions.md` shows. Each caption is then a whole subtitle line, so a word highlight can't work from it. If the user picked TikTok or karaoke and only SRT is possible, tell them and offer the YouTube style instead.

Keep each transcript's timestamps relative to its own source file.

### 4. Place the Official Caption Element

Follow official `remotion-captions/display-captions.md`:

- Install `@remotion/captions` with `npx remotion add @remotion/captions` if needed.
- Copy the element for the chosen style into the project from `https://www.remotion.dev/elements/captions/<element>.md`: Popping Word Captions for TikTok, Word Highlight Captions for karaoke, Basic Captions for YouTube and minimal.
- Put **one element per captioned clip, inside that clip's own `<Sequence>`** next to its `<Audio>`/`<Video>`. Don't add one global caption layer over the whole composition.
- **Inline the caption array** in the `captions` prop so the Studio Caption editor can write back.

### 5. Customize Appearance

Apply the preset from the `captions-workflow` rule, then offer these options. Change them through the element's `width`, `style` and `combineTokensWithinMilliseconds` props, or the style constants at the top of the copied file:

- **Position**: top (10%), center (50%), bottom (15-25% on vertical, to stay clear of platform UI). See the safe-zone table in the rule.
- **Font size**: Small (40px), Medium (56px), Large (72px) at 1080 wide
- **Highlight color**: Yellow (#FFD700), Cyan (#00FFFF), Green (#00FF88), custom
- **Background**: None, semi-transparent box
- **Font**: Inter, Poppins, or whatever the project uses (load it as official `remotion-markup` google-fonts.md shows)
- **Words per page**: `combineTokensWithinMilliseconds` (lower = fewer words per page)

Any extra animation uses inline `interpolate()` in `style` with the `scale`/`translate` properties. Never use CSS `transition` or `animation`; they don't render.

### 6. Check in the Preview

Tell the user to scrub the captions in the open Studio. Common adjustments:
- Text too small/large on mobile? → Adjust font size
- Words changing too fast? → Increase `combineTokensWithinMilliseconds`
- Wrong timing? → Check that the captions sit in the same sequence as their audio, and that timestamps weren't offset
- Overlapping with visuals or platform UI? → Change position (top vs bottom)
- Wording mistakes? → Fix them in the Studio Caption editor, or edit the inlined array

Don't render unless the user asks for an MP4.