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

# Multi-Level Voice-Over

> Create videos with both video-level and scene-level voice-over settings for customized narration

This guide shows you how to create videos with sophisticated voice-over configurations. Learn to set a default voice for your entire video while customizing specific scenes with different voice settings, speeds, or amplification levels.

## What You'll Learn

<CardGroup cols={2}>
  <Card title="Video-Level Default" icon="video">
    Set a default voice for all scenes
  </Card>

  <Card title="Scene-Level Override" icon="layer-group">
    Customize voice for specific scenes
  </Card>

  <Card title="Voice Customization" icon="sliders">
    Control speed and amplification per voice
  </Card>

  <Card title="Multiple Voices" icon="users">
    Use different AI voices in one video
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Basic understanding of voice-over concepts

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## How Multi-Level Voice-Over Works

Multi-level voice-over gives you granular control over narration:

1. **Video-Level Settings**: Define default voice-over configuration for all scenes
2. **Scene-Level Overrides**: Customize voice settings for specific scenes
3. **Automatic Fallback**: Scenes without custom settings use the video-level default
4. **Flexible Control**: Mix and match voices, speeds, and volumes throughout your video

<Note>
  Scene-level voice-over settings always override video-level settings for that specific scene. This allows precise control while maintaining consistency across your video.
</Note>

## Complete Example

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  // Different text for different scenes
  const INTRO_TEXT = "Welcome to our comprehensive guide on AI in education.";
  const MAIN_TEXT = "AI is transforming how educators create content, automate workflows, and personalize learning experiences.";
  const OUTRO_TEXT = "Thank you for watching. Subscribe for more insights.";

  async function createVideoWithMultiLevelVoiceOver() {
    try {
      console.log("Creating video with multi-level voice-over...");

      const response = await axios.post(
        `${API_BASE_URL}/v2/video/storyboard/render`,
        {
          videoName: "multilevel_voiceover_demo",

          // Video-level voice-over (default for all scenes)
          voiceOver: {
            enabled: true,
            aiVoices: [
              {
                speaker: "Brian",
                speed: 100,           // Normal speed
                amplificationLevel: 0, // Normal volume
              },
            ],
          },

          scenes: [
            {
              story: INTRO_TEXT,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,

              // Scene-specific voice-over (slower and louder for emphasis)
              voiceOver: {
                enabled: true,
                aiVoices: [
                  {
                    speaker: "Brian",
                    speed: 85,           // 15% slower for emphasis
                    amplificationLevel: 0.3, // Slightly louder
                  },
                ],
              },
            },
            {
              story: MAIN_TEXT,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              // No scene-level voice-over = uses video-level default
            },
            {
              story: OUTRO_TEXT,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,

              // Different scene-level settings for outro
              voiceOver: {
                enabled: true,
                aiVoices: [
                  {
                    speaker: "Brian",
                    speed: 90,           // Slightly slower
                    amplificationLevel: 0.1, // Slightly louder
                  },
                ],
              },
            },
          ],
        },
        {
          headers: {
            "Content-Type": "application/json",
            Authorization: API_KEY,
          },
        }
      );

      const jobId = response.data.data.jobId;
      console.log("✓ Video creation started!");
      console.log("Job ID:", jobId);

      // Monitor progress
      console.log("\nMonitoring video creation...");
      let jobCompleted = false;
      let jobResult = null;

      while (!jobCompleted) {
        const statusResponse = await axios.get(
          `${API_BASE_URL}/v1/jobs/${jobId}`,
          {
            headers: { Authorization: API_KEY },
          }
        );

        const status = statusResponse.data.data.status;
        console.log("Status:", status);

        if (status === "completed") {
          jobCompleted = true;
          jobResult = statusResponse.data;
          console.log("\n✓ Video is ready!");
          console.log("Video URL:", jobResult.data.videoURL);
        } else if (status === "failed") {
          throw new Error("Video creation failed: " + JSON.stringify(statusResponse.data));
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
      }

      return jobResult;
    } catch (error) {
      console.error("Error:", error.response?.data || error.message);
      throw error;
    }
  }

  createVideoWithMultiLevelVoiceOver();
  ```

  ```python Python theme={null}
  import requests
  import time
  import json

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  # Different text for different scenes
  INTRO_TEXT = "Welcome to our comprehensive guide on AI in education."
  MAIN_TEXT = "AI is transforming how educators create content, automate workflows, and personalize learning experiences."
  OUTRO_TEXT = "Thank you for watching. Subscribe for more insights."

  def create_video_with_multilevel_voiceover():
      try:
          print("Creating video with multi-level voice-over...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  'videoName': 'multilevel_voiceover_demo',

                  # Video-level voice-over (default for all scenes)
                  'voiceOver': {
                      'enabled': True,
                      'aiVoices': [
                          {
                              'speaker': 'Brian',
                              'speed': 100,           # Normal speed
                              'amplificationLevel': 0  # Normal volume
                          }
                      ]
                  },

                  'scenes': [
                      {
                          'story': INTRO_TEXT,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,

                          # Scene-specific voice-over (slower and louder for emphasis)
                          'voiceOver': {
                              'enabled': True,
                              'aiVoices': [
                                  {
                                      'speaker': 'Brian',
                                      'speed': 85,           # 15% slower for emphasis
                                      'amplificationLevel': 0.3  # Slightly louder
                                  }
                              ]
                          }
                      },
                      {
                          'story': MAIN_TEXT,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False
                          # No scene-level voice-over = uses video-level default
                      },
                      {
                          'story': OUTRO_TEXT,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,

                          # Different scene-level settings for outro
                          'voiceOver': {
                              'enabled': True,
                              'aiVoices': [
                                  {
                                      'speaker': 'Brian',
                                      'speed': 90,           # Slightly slower
                                      'amplificationLevel': 0.1  # Slightly louder
                                  }
                              ]
                          }
                      }
                  ]
              },
              headers={
                  'Content-Type': 'application/json',
                  'Authorization': API_KEY
              }
          )
          response.raise_for_status()

          job_id = response.json()['data']['jobId']
          print("✓ Video creation started!")
          print(f"Job ID: {job_id}")

          # Monitor progress
          print("\nMonitoring video creation...")
          job_completed = False
          job_result = None

          while not job_completed:
              status_response = requests.get(
                  f'{API_BASE_URL}/v1/jobs/{job_id}',
                  headers={'Authorization': API_KEY}
              )
              status_response.raise_for_status()

              status = status_response.json()['data']['status']
              print(f"Status: {status}")

              if status == 'completed':
                  job_completed = True
                  job_result = status_response.json()
                  print("\n✓ Video is ready!")
                  print(f"Video URL: {job_result['data']['videoURL']}")
              elif status == 'failed':
                  raise Exception(f"Video creation failed: {status_response.json()}")

              time.sleep(5)

          return job_result

      except requests.exceptions.RequestException as error:
          print(f"Error: {error}")
          raise

  if __name__ == '__main__':
      create_video_with_multilevel_voiceover()
  ```
</CodeGroup>

## Understanding the Configuration

### Video-Level Voice-Over (Default Settings)

| Parameter                                 | Type    | Default | Description                            |
| ----------------------------------------- | ------- | ------- | -------------------------------------- |
| `voiceOver.enabled`                       | boolean | false   | Enable voice-over for the entire video |
| `voiceOver.aiVoices`                      | array   | -       | Array of AI voice configurations       |
| `voiceOver.aiVoices[].speaker`            | string  | -       | AI voice name (e.g., "Brian", "Emma")  |
| `voiceOver.aiVoices[].speed`              | number  | 100     | Voice speed (50-200)                   |
| `voiceOver.aiVoices[].amplificationLevel` | number  | 0       | Volume level (-1 to 1)                 |

### Scene-Level Voice-Over (Overrides)

| Parameter                     | Type    | Description                                                        |
| ----------------------------- | ------- | ------------------------------------------------------------------ |
| `scenes[].voiceOver`          | object  | Scene-specific voice-over settings (same structure as video-level) |
| `scenes[].voiceOver.enabled`  | boolean | Enable/disable voice-over for this scene                           |
| `scenes[].voiceOver.aiVoices` | array   | Custom voice configuration for this scene                          |

<Tip>
  **Override Behavior:** When you define scene-level voice-over, it completely replaces the video-level settings for that scene. If you want to use the same voice but different settings, you must specify the voice name again.
</Tip>

## Voice Speed Reference

| Speed Value | Playback Rate               | Best Used For                                 |
| ----------- | --------------------------- | --------------------------------------------- |
| 50          | 0.5x (Very slow)            | Complex technical content, learning materials |
| 75          | 0.75x (Slower)              | Detailed explanations, emphasis               |
| 85-90       | 0.85-0.9x (Slightly slower) | Introduction, important points                |
| 100         | 1.0x (Normal)               | Standard content, most scenes                 |
| 110-125     | 1.1-1.25x (Slightly faster) | Casual content, transitions                   |
| 150         | 1.5x (Fast)                 | Quick summaries, energetic content            |
| 200         | 2.0x (Very fast)            | Speed reading, urgent calls-to-action         |

## Amplification Level Reference

| Level | Effect                | Best Used For                    |
| ----- | --------------------- | -------------------------------- |
| -1.0  | Quietest (background) | Subtle narration, ambient voice  |
| -0.5  | Quieter than normal   | De-emphasized content            |
| 0     | Normal volume         | Standard narration               |
| 0.3   | Slightly louder       | Mild emphasis                    |
| 0.5   | Moderately louder     | Important points                 |
| 1.0   | Loudest               | Strong emphasis, calls-to-action |

<Warning>
  **Volume Considerations:** Very high amplification levels (0.7-1.0) may cause audio distortion. Test your settings and use moderation for professional results.
</Warning>

## Common Use Cases

### Emphasizing Key Sections

```javascript theme={null}
// Intro: Slower and louder for impact
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Brian",
    speed: 85,
    amplificationLevel: 0.3
  }]
}

// Main content: Normal settings
// (uses video-level default)

// Call-to-action: Faster and louder
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Brian",
    speed: 110,
    amplificationLevel: 0.5
  }]
}
```

### Tutorial Videos

```javascript theme={null}
// Step explanations: Slower for clarity
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Emma",
    speed: 90,
    amplificationLevel: 0
  }]
}

// Quick transitions: Faster pace
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Emma",
    speed: 120,
    amplificationLevel: 0
  }]
}
```

### Multi-Language Support

```javascript theme={null}
// English sections
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Brian",  // English voice
    speed: 100,
    amplificationLevel: 0
  }]
}

// Spanish sections
voiceOver: {
  enabled: true,
  aiVoices: [{
    speaker: "Maria",  // Spanish voice
    speed: 100,
    amplificationLevel: 0
  }]
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Choose Appropriate Speed Variations">
    Don't vary speed too dramatically between scenes - sudden changes can be jarring:

    * **Good:** Vary by 10-20 points (e.g., 90-110)
    * **Avoid:** Extreme jumps (e.g., 50 to 200)
    * **Tip:** Test your video to ensure smooth transitions
  </Accordion>

  <Accordion title="Use Amplification Sparingly">
    Subtle volume changes are more professional than dramatic ones:

    * **Good:** Use 0.1-0.3 for emphasis
    * **Moderate:** Use 0.5 for strong emphasis
    * **Avoid:** Levels above 0.7 unless intentional
    * **Tip:** Let the content quality drive emphasis, not just volume
  </Accordion>

  <Accordion title="Maintain Consistency">
    Keep voice settings consistent across similar scenes:

    * Use the same voice for all sections
    * Apply similar speed/volume to similar content types
    * Create a "voice style guide" for your brand
  </Accordion>

  <Accordion title="Test Before Production">
    Always review a test video before creating multiple videos:

    * Generate a short sample with your settings
    * Listen on different devices (phone, desktop, headphones)
    * Adjust based on feedback
    * Document successful settings for reuse
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Scene uses wrong voice settings">
    **Problem:** Scene is not using your custom voice-over settings.

    **Solution:**

    * Ensure scene-level `voiceOver` object is properly formatted
    * Check that you have included the `speaker` name (it must be specified even if using the same voice)
    * Verify JSON syntax is correct (commas, brackets, quotes)
  </Accordion>

  <Accordion title="Voice sounds distorted">
    **Problem:** Audio quality is poor or distorted.

    **Solution:**

    * Reduce `amplificationLevel` (try 0.3 or lower)
    * Avoid combining high speed (>150) with high amplification (>0.5)
    * Check that speed values are within 50-200 range
  </Accordion>

  <Accordion title="All scenes use video-level settings">
    **Problem:** Scene-level overrides are not being applied.

    **Solution:**

    * Verify scene-level `voiceOver` is inside the scene object
    * Check that `enabled: true` is set at scene level
    * Ensure scene-level configuration is complete (speaker, speed, amplificationLevel)
  </Accordion>
</AccordionGroup>

## Next Steps

Enhance your voice-over videos with these features:

<CardGroup cols={2}>
  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add music to complement voice-over narration
  </Card>

  <Card title="Custom Captions" icon="closed-captioning" href="/guides/text-to-video/text-to-video-captions">
    Add translated or custom subtitles to your videos
  </Card>

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Apply consistent branding across all your videos
  </Card>

  <Card title="Basic Voice-Over" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Learn the basics of AI voice-over narration
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

<CardGroup cols={2}>
  <Card title="Get Voiceover Tracks" icon="microphone" href="/api-reference/voiceovers/get-voiceover-tracks">
    List all available AI voices
  </Card>

  <Card title="Render Storyboard Video" icon="video" href="/api-reference/videos/render-storyboard-video">
    Direct video rendering with multi-level voice-over
  </Card>

  <Card title="Create Storyboard Preview" icon="eye" href="/api-reference/videos/create-storyboard-preview">
    Create preview before rendering
  </Card>

  <Card title="Get Storyboard Preview Job" icon="clock" href="/api-reference/jobs/get-storyboard-preview-job-by-id">
    Monitor storyboard creation progress
  </Card>
</CardGroup>