# Captions (captions)

> Kinetic subtitle pill that groups aligned words into phrases and lights each word as it is spoken.

- Entry: component
- Category: Motion
- Preview capabilities: replay, player
- Runtime: Remotion
- Needs Remotion: yes
- QA page: https://jbm-ui.bns.studio/c/captions
- JSON: https://jbm-ui.bns.studio/catalog/captions.json
- Registry item: https://jbm-ui.bns.studio/r/captions.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/captions
```

Also installs @jbm/tokens, @jbm/motion-hooks (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.
3. Install `remotion` and render inside a Remotion `<Composition>` or `<Player>`, not a plain React tree. Timing values are in seconds.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/captions.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/captions.tsx` | `src/jbm/motion/captions.tsx` | `@/jbm/motion/captions` |

## API

### `Captions` (component)

Absolutely positioned ink pill near the bottom of the stage. Words group into phrases that break after punctuation, at pauses over 0.55 s, or at 9 words (landscape) / 6 words (vertical). A phrase fades in and out over up to 0.12 s; unspoken words sit at 0.28 opacity, and emphasized words turn the soft accent color with a small bounce. Renders nothing between phrases.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `words` | `Word[]` | required | Aligned words in order: `w` is the word (trailing punctuation ends a phrase), `s` and `e` are start and end times in seconds, and `emph` marks an emphasized word. |
| `orientation` | `Orientation` | `"landscape"` | Stage orientation: `vertical` uses a larger 54px font, 6-word phrases, a 940px max width, and sits 270px from the bottom; `landscape` uses 44px, 9 words, 1500px, and 84px. |
| `offset` | `number` | `0` | Seconds subtracted from the Sequence time before matching words, for word timings measured from a different origin. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | fill | 83 |
| Vertical (1080×1920) | fill | 104 |

Absolutely positioned from left 0 to right 0 of the positioned parent (the stage), bottom 84 in landscape and 270 in vertical. One line of text: 44px × 1.25 line-height + 2 × 14px padding = 83 in landscape; 54px × 1.25 + 2 × 18px = about 104 in vertical. Each wrapped line (past the 1500 / 940px max width) adds 55 / 68px.

## Examples

### Subtitles from aligned words

```tsx
import { Captions } from "@/jbm/motion/captions"

<Captions words={[
  { w: "Una", s: 0, e: 0.7 },
  { w: "idea.", s: 0.7, e: 1.5, emph: true },
]} />
```

### Vertical video with a timing offset

```tsx
import { Captions } from "@/jbm/motion/captions"

<Captions words={alignedWords} orientation="vertical" offset={12.4} />
// Place inside a positioned stage (e.g. Scene) in a Remotion composition.
```

## QA

- Step through the first frame of a phrase (fading in), mid-phrase (spoken words bright, upcoming words dim, emphasis in the soft color), and the phrase end (fading out, then nothing between phrases).
- Check grouping: a comma or period ends a phrase, a pause over 0.55 s starts a new one, and long runs split at 9 (landscape) or 6 (vertical) words.
- Render in vertical: the pill sits above the lower safe area and long phrases wrap inside 940px without covering the subject.
- The last phrase stays up to one second after its final word; confirm the composition is long enough to show its fade-out.

## Gallery preview cues

Cue times are seconds on the gallery preview's timeline, which renders the demo below; the Usage examples may use other timings. Map a cue to your own props by its place in the demo. The preview runs at 30 fps for 136 frames (0–135); see them side by side at https://jbm-ui.bns.studio/c/captions?view=strip, or open one frame with ?frame=<frame>.

```tsx
<Pop at={0}>
  <Big size={52}>Cada palabra cuenta.</Big>
</Pop>
<Captions words={[{ w: "Una", s: 0, e: 0.7 }, { w: "idea", s: 0.7, e: 1.4, emph: true }, { w: "a", s: 1.4, e: 1.8 }, { w: "la", s: 1.8, e: 2.2 }, { w: "vez.", s: 2.2, e: 3.5 }]} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 33 | 1.10 | Emphasis word | “idea” is spoken in the soft colour after its pop; later words wait at low opacity. |
| 75 | 2.50 | Every word spoken | All words are at full opacity while the pill holds before fading out. |
| 135 | 4.50 | End |  |

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
