> ## 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.

# 3. AI Voiceover

> Generate a narrated voiceover for your video using AI.

Generate a narrated voiceover for your video using AI. This is useful for explainer videos, product demos, documentary-style narration, storytelling, and any situation where spoken audio enhances context.

## How It Works

The AI Voiceover tile takes a written script (or auto-generated script, depending on mode), synthesizes a natural-sounding voice, and aligns it with your video. You choose the voice style and script mode, and Mosaic handles the timing and audio mixing.

## Input and Settings

### Voice

Select from a range of AI voices with different genders, tones, and delivery styles.\
You can preview the selected voice before committing.

Use cases:

* Professional narration (corporate, training, onboarding)
* Energetic narration for social content
* Calm educational explanations

### Script Mode

Choose how the narration script is created.

Modes include:

* **Custom Script:** You provide the exact text
* **(Other modes may include auto-generated, depending on provider)**

If using **Custom Script**, the script field becomes required.

Use cases:

* Precise storytelling
* Product walkthroughs
* Brand-compliant messaging
* Reading long-form copy without re-recording

### Custom Script

Enter the exact text you want spoken in the voiceover.

Best practices:

* Keep sentences short for clarity
* Use punctuation for natural pauses
* Mention on-screen references ("as you can see here…")

### Time Script to Video Moments *(Optional)*

When enabled, Mosaic attempts to align portions of the script with visual beats in the video.

Benefits:

* More dynamic pacing
* Better alignment with scene changes
* Reduces manual timing work

***

## API Info

<AccordionGroup>
  <Accordion title="Node Params & API Details" icon="code">
    * **Node ID:** `9570c960-b32b-4e4d-8871-5775d886f7cb`

    ### Node params

    | Param                  | Type                          | Required    | Default                  | Notes                                              |
    | ---------------------- | ----------------------------- | ----------- | ------------------------ | -------------------------------------------------- |
    | `voice_provider`       | `"elevenlabs"`                | No          | `"elevenlabs"`           | Other providers are currently rejected by runtime. |
    | `voice_id`             | `string`                      | No          | `"UgBBYS2sOqTuMpoF3BR0"` | ElevenLabs voice ID (curated or custom).           |
    | `script_mode`          | `"custom_script" \| "prompt"` | Yes         | `"custom_script"`        | Controls which text source is used.                |
    | `custom_script`        | `string`                      | Conditional | `""`                     | Required when `script_mode="custom_script"`.       |
    | `prompt`               | `string`                      | Conditional | `""`                     | Required when `script_mode="prompt"`.              |
    | `time_script_to_video` | `boolean`                     | No          | `false`                  | Attempts beat/scene-aware timing.                  |

    ### Parameter groups

    * **Voice selection:** `voice_provider`, `voice_id`
    * **Script source mode:** `script_mode`, `custom_script`, `prompt`
    * **Timing behavior:** `time_script_to_video`

    ### Scenario requirements

    * `script_mode="custom_script"` -> non-empty `custom_script` required.
    * `script_mode="prompt"` -> non-empty `prompt` required.

    ### Runtime notes

    * UI filtering keeps only the active text field for the selected mode.
    * If `voice_provider` is omitted, runtime hard-defaults to ElevenLabs.

    ### Example

    ```json theme={null}
    {
      "voice_provider": "elevenlabs",
      "voice_id": "UgBBYS2sOqTuMpoF3BR0",
      "script_mode": "custom_script",
      "custom_script": "Today we're launching a faster way to review and publish your videos.",
      "time_script_to_video": true
    }
    ```
  </Accordion>
</AccordionGroup>