> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 21. Captions

> Add dynamic, stylized captions that match your video's tone and improve accessibility.

Add dynamic, stylized captions that match your video's tone, improve retention, and boost accessibility. Ideal for social platforms where *sound-off viewing* is common (TikTok, Reels, Shorts, LinkedIn).

## How It Works

The Captions tile listens to your video audio, transcribes speech, and overlays timed captions. You control how they look — from fonts and stroke to placement and coloring.

Captions are auto-timed to speech and update in real-time based on your styling choices.

<img src="https://mintcdn.com/mosaic/S3GLpgf8v2QfKa5r/images/captions-example.png?fit=max&auto=format&n=S3GLpgf8v2QfKa5r&q=85&s=b830de06ff871283a6c8f58d160b553a" alt="Clean captions" width="1920" height="1080" data-path="images/captions-example.png" />

## Input and Settings

### Caption Style

Controls how captions are visually rendered.

API `caption_style` values:

* **`colored`** → Highlights key words with your `highlight_color`
* **`scaling`** → Emphasis via animated word scaling
* **`karaoke`** → Progressive karaoke-style emphasis

`stroke_color` and `stroke_enabled` are controlled separately from `caption_style`.

Great for:

* Retention editing
* Educational clips
* Talking-head explanatory content

### Colors

You can customize three visual layers:

**Base Color**\
Default text color (e.g., `#FFFFFF` for white)

**Highlight Color**\
Used to emphasize specific words — increases engagement & readability

**Stroke Color**\
Outline around text for contrast on busy footage

### Font Options

Set the typography style to match your brand.

Controls include:

* **Font Family** (e.g., Montserrat)
* **Font Weight** (e.g., 400 / 700)
* **Exact Size** (optional pixel value)

Use cases:

* Bold fonts for TikTok/Shorts
* Light/fonts for cinematic edits

Supported local brand fonts include all Sun fonts (`The Sun Heavy Condensed`, `The Sun Heavy Narrow`, `The Sun Bold`, `The Sun Bold Italic`, `The Sun Medium`, `The Sun Medium Italic`, `The Sun Regular`, `The Sun Italic`) and `Knockout`. These render from bundled font files rather than Google Fonts.

By default, caption size is automatic and scales to the composition. Set `caption_font_size_px` only when you need an exact pixel size; send `null` to clear an existing exact-size setting.

### Drop Shadow

Enable a drop shadow when captions need extra separation from busy footage.

Controls:

* `shadow_enabled`
* `shadow_color`
* `shadow_blur`
* `shadow_opacity`

### Vertical Position

Adjust how high/low captions sit in the frame (via percentage slider).

Examples:

* `90%` → Just above bottom edge (common for shorts)
* `50%` → Centered (cinematic)
* `20%` → Top aligned (when lower third is busy)

### Words per Caption

Controls pacing and readability.

Two sliders:

* **Minimum words**
* **Maximum words**

Examples:

* `Min 1 / Max 3` → Fast TikTok pacing
* `Min 3 / Max 7` → YouTube educational pacing

***

## API Info

<AccordionGroup>
  <Accordion title="Node Params & API Details" icon="code">
    * **Node ID:** `cdccb204-168e-4aec-aa72-480b11e74324`

    ### Node params

    | Param                       | Type                                  | Required | Default        | Notes                                                                                                |
    | --------------------------- | ------------------------------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------- |
    | `caption_style`             | `"colored" \| "scaling" \| "karaoke"` | No       | `"colored"`    | Visual style preset.                                                                                 |
    | `base_color`                | `string` (hex)                        | No       | `"#F8FAFC"`    | Primary text color.                                                                                  |
    | `highlight_color`           | `string` (hex)                        | No       | `"#A78BCA"`    | Highlight/accent color.                                                                              |
    | `stroke_color`              | `string` (hex)                        | No       | `"#0B0B0B"`    | Stroke/outline color.                                                                                |
    | `stroke_enabled`            | `boolean`                             | No       | `true`         | Toggle the text outline on or off.                                                                   |
    | `caption_font`              | `string`                              | No       | `"Montserrat"` | Font family.                                                                                         |
    | `caption_font_weight`       | `string`                              | No       | `"700"`        | Font weight as string token.                                                                         |
    | `caption_font_size_px`      | `number \| null`                      | No       | omitted        | Exact caption font size in pixels. Send `null` to clear exact sizing and return to automatic sizing. |
    | `shadow_enabled`            | `boolean`                             | No       | `false`        | Toggle the drop shadow.                                                                              |
    | `shadow_color`              | `string` (hex)                        | No       | `"#000000"`    | Drop shadow color.                                                                                   |
    | `shadow_blur`               | `number`                              | No       | `10`           | Drop shadow blur radius in pixels (`0-40`).                                                          |
    | `shadow_opacity`            | `number`                              | No       | `0.5`          | Drop shadow opacity (`0-1`).                                                                         |
    | `caption_vertical_position` | `number` (percent)                    | No       | `88`           | Vertical caption placement (`10-90`).                                                                |
    | `caption_min_words`         | `number`                              | No       | `2`            | Minimum words grouped per caption chunk (`1-8`).                                                     |
    | `caption_max_words`         | `number`                              | No       | `4`            | Maximum words grouped per caption chunk (`1-8`).                                                     |

    ### Parameter groups

    * **Render style:** `caption_style`, `base_color`, `highlight_color`, `stroke_color`, `stroke_enabled`, `shadow_enabled`, `shadow_color`, `shadow_blur`, `shadow_opacity`
    * **Typography:** `caption_font`, `caption_font_weight`, `caption_font_size_px`
    * **Layout & pacing:** `caption_vertical_position`, `caption_min_words`, `caption_max_words`

    ### Scenario requirements

    * Keep `caption_min_words <= caption_max_words`.
    * Use valid hex color strings for color fields.
    * `caption_font_weight` must be sent as a **string** (for example `"700"`), not a number.
    * Omit `caption_font_size_px` to preserve the current sizing mode; set it for exact pixel sizing; send `null` to clear exact sizing and return to automatic sizing.

    ### Runtime notes

    * For deterministic output, set style, typography, and pacing fields explicitly.
    * For API overrides, pass these fields via `update_params[agent_node_id]`.

    ### Example

    ```json theme={null}
    {
      "caption_style": "colored",
      "base_color": "#FFFFFF",
      "highlight_color": "#EC81EE",
      "caption_font": "Montserrat",
      "caption_font_weight": "700",
      "caption_font_size_px": 42,
      "stroke_enabled": true,
      "shadow_enabled": true,
      "shadow_color": "#000000",
      "shadow_blur": 10,
      "shadow_opacity": 0.5,
      "caption_vertical_position": 88,
      "caption_min_words": 2,
      "caption_max_words": 4
    }
    ```
  </Accordion>
</AccordionGroup>