Scene-Level Music Control

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

Video-Level Defaults

Set default background music for entire video

Scene-Level Override

Enable or disable music for specific scenes

Selective Audio

Create videos with dynamic music control

Audio Strategy

Design effective scene-by-scene audio

Before You Begin

Make sure you have:

A Pictory API key
Node.js or Python installed on your machine
Understanding of video-level background music configuration
Basic knowledge of scene structure in Pictory API

npm install axios

pip install requests

How Scene-Level Music Control Works

When you configure music at the scene level:

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

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.

Complete Example

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();

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()

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

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

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.

{
  // 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.

{
  // 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.

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

{
  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

{
  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

{
  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

{
  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

{
  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

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

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

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

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

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

Troubleshooting

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

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

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

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:

{
  backgroundMusic: { enabled: true, ... },  // Video level
  scenes: [
    { story: "...", backgroundMusic: { enabled: false } }  // Scene level
  ]
}

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:

{
  backgroundMusic: { enabled: false, autoMusic: true, volume: 0.3 },
  scenes: [
    { story: "...", backgroundMusic: { enabled: true } }  // Override: ON
  ]
}

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

Hierarchy and Override Rules

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

Default Behavior (No Scene Override)

{
  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

{
  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

{
  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:

Background Music

Learn about video-level background music configuration

AI Voice-Over

Add narration that works with scene music

Intro/Outro Scenes

Combine scene music control with intro/outro

Custom Subtitle Styling

Style subtitles for scenes with/without music

API Reference

For complete technical details, see:

Render Storyboard Video - Full API specification including scene-level configuration
Get Job Status - Monitor job status and get video URLs

​What You’ll Learn

Video-Level Defaults

Scene-Level Override

Selective Audio

Audio Strategy

​Before You Begin

​How Scene-Level Music Control Works

​Complete Example

​Understanding the Parameters

​Video-Level Background Music

​Scene-Level Override

​Music Control Patterns

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

​Pattern 2: Music Only on Specific Scenes

​Pattern 3: Alternating Music for Variety

​Pattern 4: Music Only During Transitions

​Common Use Cases

​Educational Videos - Focus on Key Concepts

​Marketing Videos - Emphasize Call-to-Action

​Podcast/Interview Clips - Highlight Quotes

​Testimonial Videos - Authentic Voice

​Best Practices

​Troubleshooting

​Hierarchy and Override Rules

​Default Behavior (No Scene Override)

​With Scene-Level Override

​Video-Level Disabled, Scene-Level Enabled

​Next Steps

Background Music

AI Voice-Over

Intro/Outro Scenes

Custom Subtitle Styling

​API Reference

What You’ll Learn

Before You Begin

How Scene-Level Music Control Works

Complete Example

Understanding the Parameters

Video-Level Background Music

Scene-Level Override

Music Control Patterns

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

Pattern 2: Music Only on Specific Scenes

Pattern 3: Alternating Music for Variety

Pattern 4: Music Only During Transitions

Common Use Cases

Educational Videos - Focus on Key Concepts

Marketing Videos - Emphasize Call-to-Action

Podcast/Interview Clips - Highlight Quotes

Testimonial Videos - Authentic Voice

Best Practices

Troubleshooting

Hierarchy and Override Rules

Default Behavior (No Scene Override)

With Scene-Level Override

Video-Level Disabled, Scene-Level Enabled

Next Steps

API Reference