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

# Scene-Level Music Control

> Enable or disable background music for specific scenes to create dynamic audio experiences in your videos

This guide shows you how to control background music at the scene level. Enable or disable music for individual scenes within the same video to create dynamic audio experiences, emphasize key moments, or add variety to your content.

## What You'll Learn

<CardGroup cols={2}>
  <Card title="Video-Level Defaults" icon="music">
    Set default background music for entire video
  </Card>

  <Card title="Scene-Level Override" icon="sliders">
    Enable or disable music for specific scenes
  </Card>

  <Card title="Selective Audio" icon="toggle-on">
    Create videos with dynamic music control
  </Card>

  <Card title="Audio Strategy" icon="waveform">
    Design effective scene-by-scene audio
  </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
* Understanding of video-level background music configuration
* Basic knowledge of scene structure in Pictory API

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

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

## How Scene-Level Music Control Works

When you configure music at the scene level:

1. **Video-Level Default** - Define default background music settings for entire video
2. **Scene Processing** - Each scene is evaluated for scene-level overrides
3. **Override Detection** - System checks if scene has `backgroundMusic.enabled` setting
4. **Music Application** - Scenes use video-level music unless explicitly overridden
5. **Audio Mixing** - Music is mixed with voice-over and other audio per scene
6. **Transition Handling** - Smooth transitions between scenes with/without music
7. **Video Rendering** - Final video rendered with scene-specific music control

<Note>
  Scene-level control only allows enabling or disabling music. All scenes that have music enabled use the same music track defined at the video level. You cannot use different music tracks for different scenes.
</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";

  const STORY_TEXT_1 =
    "AI is poised to significantly impact educators and course creators on social media.";
  const STORY_TEXT_2 =
    "By automating tasks like content generation, visual design, and video editing.";
  const STORY_TEXT_3 =
    "AI will save time and enhance consistency for content creators everywhere.";

  async function createVideoWithSceneMusicControl() {
    try {
      console.log("Creating video with scene-level music control...");

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

          // VIDEO-LEVEL: Default background music for all scenes
          backgroundMusic: {
            enabled: true,                       // Enable by default
            autoMusic: true,                     // AI-selected music
            volume: 0.3,                         // 30% volume
          },

          scenes: [
            // SCENE 1: Uses video-level music (default)
            {
              story: STORY_TEXT_1,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              // No scene-level override - music plays
            },

            // SCENE 2: Disable music for this specific scene
            {
              story: STORY_TEXT_2,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              backgroundMusic: {
                enabled: false,                  // Override: disable music
              },
            },

            // SCENE 3: Uses video-level music again (default)
            {
              story: STORY_TEXT_3,
              createSceneOnNewLine: false,
              createSceneOnEndOfSentence: false,
              // No scene-level override - music plays
            },
          ],
        },
        {
          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 with scene-level music control 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;
    }
  }

  createVideoWithSceneMusicControl();
  ```

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

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

  STORY_TEXT_1 = (
      "AI is poised to significantly impact educators and course creators on social media."
  )
  STORY_TEXT_2 = (
      "By automating tasks like content generation, visual design, and video editing."
  )
  STORY_TEXT_3 = (
      "AI will save time and enhance consistency for content creators everywhere."
  )

  def create_video_with_scene_music_control():
      try:
          print("Creating video with scene-level music control...")

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

                  # VIDEO-LEVEL: Default background music for all scenes
                  'backgroundMusic': {
                      'enabled': True,                       # Enable by default
                      'autoMusic': True,                     # AI-selected music
                      'volume': 0.3                          # 30% volume
                  },

                  'scenes': [
                      # SCENE 1: Uses video-level music (default)
                      {
                          'story': STORY_TEXT_1,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False
                          # No scene-level override - music plays
                      },

                      # SCENE 2: Disable music for this specific scene
                      {
                          'story': STORY_TEXT_2,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False,
                          'backgroundMusic': {
                              'enabled': False               # Override: disable music
                          }
                      },

                      # SCENE 3: Uses video-level music again (default)
                      {
                          'story': STORY_TEXT_3,
                          'createSceneOnNewLine': False,
                          'createSceneOnEndOfSentence': False
                          # No scene-level override - music plays
                      }
                  ]
              },
              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 with scene-level music control 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}")
          if hasattr(error, 'response') and error.response is not None:
              print(f"Response: {error.response.text}")
          raise

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

## Understanding the Parameters

### Video-Level Background Music

| Parameter                   | Type    | Required | Description                                                        |
| --------------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `backgroundMusic.enabled`   | boolean | Yes      | Set to `true` to enable background music by default for all scenes |
| `backgroundMusic.musicUrl`  | string  | No       | Custom music URL (or use `autoMusic` instead)                      |
| `backgroundMusic.autoMusic` | boolean | No       | Use AI-selected music                                              |
| `backgroundMusic.volume`    | number  | No       | Volume level (0-1). Default: 0.5                                   |

### Scene-Level Override

| Parameter                          | Type    | Required | Description                                                                                                |
| ---------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `scenes[].backgroundMusic.enabled` | boolean | No       | Override video-level setting. `true` = enable music for this scene, `false` = disable music for this scene |

<Warning>
  **Scene-Level Limitations:**

  * Scene-level `backgroundMusic` only accepts the `enabled` parameter (true/false)
  * You cannot change music track, volume, or clips at scene level
  * All scenes with music enabled use the same track from video-level configuration
  * To use different music tracks, create separate videos
</Warning>

## Music Control Patterns

### Pattern 1: Music On Most Scenes, Off for Key Moments

Use music throughout, but disable it for important announcements or dramatic pauses.

```javascript theme={null}
{
  // Video-level: Music enabled by default
  backgroundMusic: {
    enabled: true,
    autoMusic: true,
    volume: 0.3
  },

  scenes: [
    { story: "Welcome to our presentation..." },              // ✓ Music ON
    { story: "Today we'll cover three topics..." },           // ✓ Music ON
    {
      story: "IMPORTANT: Please note this key point...",
      backgroundMusic: { enabled: false }                     // ✗ Music OFF
    },
    { story: "Continuing with our discussion..." },           // ✓ Music ON
    {
      story: "Call to action: Visit our website now!",
      backgroundMusic: { enabled: false }                     // ✗ Music OFF
    }
  ]
}
```

**Result:** Music plays throughout except during critical messages for maximum clarity.

### Pattern 2: Music Only on Specific Scenes

Start with no music by default, enable only for specific scenes.

```javascript theme={null}
{
  // Video-level: Music disabled by default
  backgroundMusic: {
    enabled: false,
    musicUrl: "https://example.com/upbeat-music.mp3",
    volume: 0.5
  },

  scenes: [
    {
      story: "Intro scene with energy!",
      backgroundMusic: { enabled: true }                      // ✓ Music ON
    },
    { story: "Main content without distraction..." },         // ✗ Music OFF
    { story: "Detailed explanation..." },                     // ✗ Music OFF
    { story: "Technical information..." },                    // ✗ Music OFF
    {
      story: "Exciting outro! Subscribe now!",
      backgroundMusic: { enabled: true }                      // ✓ Music ON
    }
  ]
}
```

**Result:** Music plays only during intro and outro, main content is music-free.

### Pattern 3: Alternating Music for Variety

Alternate music on/off to create rhythm and variety.

```javascript theme={null}
{
  backgroundMusic: { enabled: true, autoMusic: true, volume: 0.4 },

  scenes: [
    { story: "First point with music..." },                   // ✓ Music ON
    {
      story: "Second point - focus moment",
      backgroundMusic: { enabled: false }                     // ✗ Music OFF
    },
    { story: "Third point with music..." },                   // ✓ Music ON
    {
      story: "Fourth point - another focus moment",
      backgroundMusic: { enabled: false }                     // ✗ Music OFF
    },
    { story: "Conclusion with music..." }                     // ✓ Music ON
  ]
}
```

**Result:** Creates dynamic pacing with alternating music and silence.

### Pattern 4: Music Only During Transitions

Use music only between content sections for smooth transitions.

```javascript theme={null}
{
  backgroundMusic: { enabled: false, autoMusic: true, volume: 0.3 },

  scenes: [
    { story: "Section 1: Introduction..." },                  // ✗ Music OFF
    {
      story: "",
      background: { type: "image", visualUrl: "transition.png" },
      minimumDuration: 2,
      backgroundMusic: { enabled: true }                      // ✓ Music ON (transition)
    },
    { story: "Section 2: Main content..." },                  // ✗ Music OFF
    {
      story: "",
      background: { type: "image", visualUrl: "transition.png" },
      minimumDuration: 2,
      backgroundMusic: { enabled: true }                      // ✓ Music ON (transition)
    },
    { story: "Section 3: Conclusion..." }                     // ✗ Music OFF
  ]
}
```

**Result:** Music plays only during transition scenes for smooth section changes.

## Common Use Cases

### Educational Videos - Focus on Key Concepts

```javascript theme={null}
{
  backgroundMusic: { enabled: true, autoMusic: true, volume: 0.25 },
  scenes: [
    { story: "Today's lesson is about quantum physics..." },
    {
      story: "Here's the key formula you need to remember...",
      backgroundMusic: { enabled: false }                     // No music for important formula
    },
    { story: "Now let's see how this applies..." },
    {
      story: "This critical concept is the foundation...",
      backgroundMusic: { enabled: false }                     // No music for critical concept
    }
  ]
}
```

**Result:** Subtle background music except during key learning moments for better retention.

### Marketing Videos - Emphasize Call-to-Action

```javascript theme={null}
{
  backgroundMusic: { enabled: true, musicUrl: "upbeat-corporate.mp3", volume: 0.5 },
  scenes: [
    { story: "Introducing our revolutionary new product..." },
    { story: "Features include advanced AI technology..." },
    {
      story: "Limited time offer! Get 50% off today only!",
      backgroundMusic: { enabled: false }                     // Silence for CTA impact
    }
  ]
}
```

**Result:** Energetic music builds excitement, then silence makes CTA stand out.

### Podcast/Interview Clips - Highlight Quotes

```javascript theme={null}
{
  backgroundMusic: { enabled: false },
  scenes: [
    {
      story: "Intro sequence",
      backgroundMusic: { enabled: true }                      // Music for intro
    },
    { story: "Our guest shares their expertise..." },         // No music during talk
    { story: "Interview question and answer..." },            // No music during talk
    {
      story: "Outro and closing remarks",
      backgroundMusic: { enabled: true }                      // Music for outro
    }
  ]
}
```

**Result:** Music bookends the interview, content is clear and uninterrupted.

### Testimonial Videos - Authentic Voice

```javascript theme={null}
{
  backgroundMusic: { enabled: true, autoMusic: true, volume: 0.3 },
  scenes: [
    { story: "Real customers share their experiences..." },
    {
      story: "This product completely changed my business...",
      backgroundMusic: { enabled: false }                     // No music for testimonial
    },
    {
      story: "I saw results within the first week...",
      backgroundMusic: { enabled: false }                     // No music for testimonial
    },
    { story: "Join thousands of satisfied customers today..." }
  ]
}
```

**Result:** Authentic testimonials stand out without music, framing content has music.

## Best Practices

<AccordionGroup>
  <Accordion title="Disable Music for Important Messages">
    Use silence strategically to emphasize critical content:

    * **Key Announcements**: Turn off music for important news or updates
    * **Call-to-Action**: Disable music during CTA for maximum impact
    * **Statistics/Data**: Present numbers and facts without musical distraction
    * **Testimonials**: Let authentic voices speak without background music
    * **Complex Concepts**: Turn off music when explaining difficult topics
    * **Legal/Disclaimers**: Ensure disclaimers are heard clearly without music
  </Accordion>

  <Accordion title="Use Music for Energy and Transitions">
    Enable music strategically to enhance engagement:

    * **Intro/Outro**: Use music to bookend your content professionally
    * **Topic Transitions**: Add music during section changes for smooth flow
    * **Upbeat Moments**: Enable music for exciting or celebratory content
    * **Background Context**: Use subtle music during supporting information
    * **B-Roll Sequences**: Add music during visual-only scenes
    * **Energy Boost**: Turn music on to re-engage viewers during longer content
  </Accordion>

  <Accordion title="Create Dynamic Pacing">
    Alternate music on/off to maintain viewer interest:

    * **Vary Audio Landscape**: Don't use the same pattern throughout
    * **Match Content Mood**: Enable music for lighter topics, disable for serious ones
    * **Prevent Fatigue**: Alternating helps prevent audio monotony
    * **Scene Variety**: Mix music/no-music scenes for dynamic feel
    * **Rhythm Creation**: Establish patterns viewers can anticipate
    * **Strategic Silence**: Use silence as a tool, not just absence of sound
  </Accordion>

  <Accordion title="Consider Voice-Over Interaction">
    Balance music with narration for clarity:

    * **With Heavy Narration**: Consider disabling music for content-heavy scenes
    * **Short Voice-Over**: Music works well with brief narration
    * **Technical Narration**: Disable music when explaining complex procedures
    * **Volume Balance**: Even when music is on, keep it low (0.2-0.3) with voice-over
    * **Speaker Changes**: Consider music changes when speakers change
    * **Emphasis Through Contrast**: Use music/silence to emphasize speaker's words
  </Accordion>

  <Accordion title="Test Your Audio Mix">
    Always preview to ensure proper music control:

    * **Listen Carefully**: Review the full video to check music transitions
    * **Check Transitions**: Ensure smooth audio when music starts/stops
    * **Volume Levels**: Verify music does not overpower when enabled
    * **Scene Timing**: Confirm music changes align with scene boundaries
    * **Viewer Perspective**: Consider if music changes make sense to viewers
    * **Iterate**: Adjust scene-level settings based on preview feedback
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Scene-level override not working">
    **Problem:** Scene still has music even though `enabled: false` was set.

    **Solution:**

    * Verify you set `backgroundMusic: { enabled: false }` at scene level
    * Check JSON syntax is correct (proper nesting and commas)
    * Ensure video-level music is enabled first (nothing to override otherwise)
    * Confirm scene-level setting is within the specific scene object
    * Review API response for any validation errors
    * Test with a simple 2-scene example to isolate the issue
  </Accordion>

  <Accordion title="Cannot change music track per scene">
    **Problem:** Want different music for different scenes, but it is not working.

    **Solution:**

    * Scene-level control only allows enabling/disabling, not changing tracks
    * All scenes with music use the video-level track configuration
    * To use different music tracks:
      * Create separate videos for each music track needed
      * Use video editing software for multi-track music after export
      * Consider using different clips from the same track (video-level clips)
    * This is a current limitation of the scene-level music control feature
  </Accordion>

  <Accordion title="Music transitions are abrupt">
    **Problem:** Music starts/stops suddenly between scenes, sounds jarring.

    **Solution:**

    * This is expected behavior - music transitions align with scene boundaries
    * The API automatically applies subtle fade in/out at scene transitions
    * For smoother transitions, consider:
      * Adjusting scene durations to align with musical phrases
      * Using longer scenes where music stays consistent
      * Choosing background music with gentle instrumentation
    * Very short scenes may have more noticeable transitions
  </Accordion>

  <Accordion title="All scenes have music despite overrides">
    **Problem:** Scene-level `enabled: false` seems to be ignored.

    **Solution:**

    * Verify video-level music is properly configured first
    * Check that scene-level override is `backgroundMusic: { enabled: false }`
    * Ensure you are not just setting `enabled: false` at video level
    * Confirm proper JSON structure and nesting
    * Example correct structure:
      ```javascript theme={null}
      {
        backgroundMusic: { enabled: true, ... },  // Video level
        scenes: [
          { story: "...", backgroundMusic: { enabled: false } }  // Scene level
        ]
      }
      ```
  </Accordion>

  <Accordion title="Cannot enable music for one scene when video-level disabled">
    **Problem:** Set video-level music to disabled, but want to enable for one scene.

    **Solution:**

    * This is supported - set video-level to `enabled: false`
    * Then enable for specific scenes with `backgroundMusic: { enabled: true }`
    * Ensure video-level still has `musicUrl` or `autoMusic` configured
    * Even with `enabled: false` at video level, you need music source defined
    * Example:
      ```javascript theme={null}
      {
        backgroundMusic: { enabled: false, autoMusic: true, volume: 0.3 },
        scenes: [
          { story: "...", backgroundMusic: { enabled: true } }  // Override: ON
        ]
      }
      ```
  </Accordion>

  <Accordion title="Volume cannot be changed per scene">
    **Problem:** Want different volume levels for different scenes.

    **Solution:**

    * Scene-level control does not support volume adjustments
    * Only `enabled` (true/false) can be set at scene level
    * All scenes use the video-level volume setting
    * Workaround options:
      * Use audio editing software post-export for scene-specific volume
      * Choose background music with natural volume variations
      * Create separate videos if drastically different volumes needed
    * This is a current limitation of scene-level music control
  </Accordion>
</AccordionGroup>

## Hierarchy and Override Rules

Understanding how video-level and scene-level settings interact:

### Default Behavior (No Scene Override)

```javascript theme={null}
{
  backgroundMusic: { enabled: true, autoMusic: true, volume: 0.3 },
  scenes: [
    { story: "Scene 1" },    // Uses video-level: Music ON, Volume 0.3
    { story: "Scene 2" },    // Uses video-level: Music ON, Volume 0.3
    { story: "Scene 3" }     // Uses video-level: Music ON, Volume 0.3
  ]
}
```

### With Scene-Level Override

```javascript theme={null}
{
  backgroundMusic: { enabled: true, autoMusic: true, volume: 0.3 },
  scenes: [
    { story: "Scene 1" },                                     // Music ON
    { story: "Scene 2", backgroundMusic: { enabled: false } }, // Music OFF (override)
    { story: "Scene 3" }                                      // Music ON
  ]
}
```

### Video-Level Disabled, Scene-Level Enabled

```javascript theme={null}
{
  backgroundMusic: { enabled: false, autoMusic: true, volume: 0.4 },
  scenes: [
    { story: "Scene 1" },                                     // Music OFF
    { story: "Scene 2", backgroundMusic: { enabled: true } }, // Music ON (override)
    { story: "Scene 3" }                                      // Music OFF
  ]
}
```

## Next Steps

Enhance your scene-level music control with these complementary features:

<CardGroup cols={2}>
  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Learn about video-level background music configuration
  </Card>

  <Card title="AI Voice-Over" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Add narration that works with scene music
  </Card>

  <Card title="Intro/Outro Scenes" icon="clapperboard" href="/guides/advanced-features/intro-outro">
    Combine scene music control with intro/outro
  </Card>

  <Card title="Custom Subtitle Styling" icon="closed-captioning" href="/guides/branding-customization/custom-subtitle-style">
    Style subtitles for scenes with/without music
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

* [Render Storyboard Video](/api-reference/videos/render-storyboard-video) - Full API specification including scene-level configuration
* [Get Job Status](/api-reference/jobs/get-video-render-job-by-id) - Monitor job status and get video URLs