Scene-Level Music

This guide shows you how to control background music scene by scene. A scene can play its own track at its own volume, keep the video’s music, or have no music at all, so the opening, the problem and the close of a video can each sound the way they should.

What You’ll Learn

A Track per Scene

Give a scene its own music with musicUrl

Volume per Scene

Set how loud each scene’s music plays

Mixing with Video Music

Combine scene tracks with one track for the rest of the video

Music On and Off

Turn music off on the scenes that need silence

Before You Begin

Make sure you have:

A Pictory API key
Node.js or Python installed on your machine
Familiarity with video-level background music

npm install axios

pip install requests

How Scene-Level Music Works

Each scene can have its own backgroundMusic object. What the scene plays depends on what you set:

You set on the scene	The scene plays
Nothing	The video’s music. If the video sets no track, the template’s music, if it has any. No music if `backgroundMusic.enabled` is `false`.
`musicUrl`	Its own music, at its own `volume`. Without a `volume`, it uses the video’s music volume.
`enabled: false`	No music.
`musicUrl` and `enabled: false`	No music. The track still moves on in time, so the scenes around it that use the same track stay in step.

Pictory joins all the scene music into one soundtrack for the video, following these rules:

Same track, no restart. If scenes next to each other use the same musicUrl, the music keeps playing without starting over, even if their volumes differ.
The video’s music picks up where it would have been. After scenes with their own music, the video’s music comes back as if it had played the whole time, not from the start.
Short tracks repeat. A track shorter than its scenes plays again until they end.
Changes fade. When one track changes to another, or to a scene with no music, the music fades over half a second or less. A scene turned off with enabled: false goes quiet without a fade.
Silence needs the video’s music off. Set backgroundMusic.enabled to false to keep scenes without a musicUrl silent. Otherwise, if you set no video music, those scenes play the template’s music, if it has any.

Complete Example

This video opens on the video-level track, switches to a calmer track for two scenes at different volumes, keeps one scene silent, and returns to the video-level track for the close.

import axios from "axios";

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

// audioUrl values from Search Music Tracks, passed exactly as returned.
const OPENING_TRACK = "https://tracks.melod.ie/track_versions/34767/MEL804_03_1_Between_Aisles_%28Full%29_Paolo_Argento_stream.mp3?1727770833";
const CALM_TRACK = "https://tracks.melod.ie/track_versions/12627/MEL409_10_1_Dark_Imaginings_%28Full%29_H_Robertson_stream.mp3?1722557449";

async function createVideoWithSceneMusic() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "video_with_scene_music",

      // VIDEO-LEVEL: plays on every scene that has no track of its own.
      backgroundMusic: {
        enabled: true,
        musicUrl: OPENING_TRACK,
        volume: 0.3,
      },

      scenes: [
        // SCENE 1: video-level track at 0.3
        { story: "Every morning starts with a rush." },

        // SCENES 2-3: their own track, continued across both scenes, quieter in scene 3
        {
          story: "But what if the morning could feel different?",
          backgroundMusic: { musicUrl: CALM_TRACK, volume: 0.4 },
        },
        {
          story: "Take a moment. Breathe. Plan the day ahead.",
          backgroundMusic: { musicUrl: CALM_TRACK, volume: 0.2 },
        },

        // SCENE 4: no music while the key message is read
        {
          story: "Our planner gives you back thirty minutes a day.",
          backgroundMusic: { enabled: false },
        },

        // SCENE 5: the video-level track resumes where it would have been
        { story: "Try it free today." },
      ],
    },
    {
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
    }
  );

  const jobId = response.data.data.jobId;
  console.log("Job ID:", jobId);

  while (true) {
    await new Promise(resolve => setTimeout(resolve, 15000));
    const statusResponse = await axios.get(`${API_BASE_URL}/v1/jobs/${jobId}`, {
      headers: { Authorization: API_KEY },
    });
    const job = statusResponse.data;

    if (job.success === false) {
      throw new Error(`${job.data.error_code}: ${job.data.error_message}`);
    }
    if (job.data.status === "completed") {
      console.log("Video URL:", job.data.videoURL);
      return job;
    }
    console.log("Status:", job.data.status);
  }
}

createVideoWithSceneMusic().catch(error => {
  console.error("Error:", error.response?.data || error.message);
});

import time
import requests

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

# audioUrl values from Search Music Tracks, passed exactly as returned.
OPENING_TRACK = "https://tracks.melod.ie/track_versions/34767/MEL804_03_1_Between_Aisles_%28Full%29_Paolo_Argento_stream.mp3?1727770833"
CALM_TRACK = "https://tracks.melod.ie/track_versions/12627/MEL409_10_1_Dark_Imaginings_%28Full%29_H_Robertson_stream.mp3?1722557449"


def create_video_with_scene_music():
    response = requests.post(
        f"{API_BASE_URL}/v2/video/storyboard/render",
        json={
            "videoName": "video_with_scene_music",
            # VIDEO-LEVEL: plays on every scene that has no track of its own.
            "backgroundMusic": {"enabled": True, "musicUrl": OPENING_TRACK, "volume": 0.3},
            "scenes": [
                # SCENE 1: video-level track at 0.3
                {"story": "Every morning starts with a rush."},
                # SCENES 2-3: their own track, continued across both scenes, quieter in scene 3
                {
                    "story": "But what if the morning could feel different?",
                    "backgroundMusic": {"musicUrl": CALM_TRACK, "volume": 0.4},
                },
                {
                    "story": "Take a moment. Breathe. Plan the day ahead.",
                    "backgroundMusic": {"musicUrl": CALM_TRACK, "volume": 0.2},
                },
                # SCENE 4: no music while the key message is read
                {
                    "story": "Our planner gives you back thirty minutes a day.",
                    "backgroundMusic": {"enabled": False},
                },
                # SCENE 5: the video-level track resumes where it would have been
                {"story": "Try it free today."},
            ],
        },
        headers={"Content-Type": "application/json", "Authorization": API_KEY},
    )
    response.raise_for_status()
    job_id = response.json()["data"]["jobId"]
    print(f"Job ID: {job_id}")

    while True:
        time.sleep(15)
        job = requests.get(
            f"{API_BASE_URL}/v1/jobs/{job_id}", headers={"Authorization": API_KEY}
        ).json()
        if job.get("success") is False:
            raise Exception(f"{job['data']['error_code']}: {job['data']['error_message']}")
        if job["data"]["status"] == "completed":
            print(f"Video URL: {job['data']['videoURL']}")
            return job
        print(f"Status: {job['data']['status']}")


if __name__ == "__main__":
    create_video_with_scene_music()

Understanding the Parameters

Video-Level Background Music

Parameter	Type	Required	Description
`backgroundMusic.enabled`	boolean	Yes	Set to `true` for music in the video. Scenes without their own music play it
`backgroundMusic.musicUrl`	string	No	The music for the whole video. A public link to an audio file, or an `audioUrl` from Search Music Tracks. Cannot be used with `autoMusic`
`backgroundMusic.autoMusic`	boolean	No	Set to `true` to let Pictory choose a track that suits the video
`backgroundMusic.volume`	number	No	Volume from 0 to 1. Scene tracks without their own `volume` use this value

Parameter	Type	Required	Description
`scenes[].backgroundMusic.musicUrl`	string	No	The music for this scene. A public link to an audio file, or an `audioUrl` from Search Music Tracks copied exactly as returned
`scenes[].backgroundMusic.volume`	number	No	How loud this scene’s music is, from 0 to 1. Use it only with `musicUrl`. If left out, the scene uses the video’s music volume
`scenes[].backgroundMusic.enabled`	boolean	When `musicUrl` is not set	Set to `false` for no music in this scene. It is `true` when you set `musicUrl`

If neither the scene nor the video sets a volume, and the video has no music of its own, the scene’s music plays at full volume.

Licensed tracks. Tracks from Search Music Tracks are licensed for you, for the whole video and for single scenes. If a video uses more than one of them, the youtubeClearanceCode on the render job covers the one that plays the longest.

Music Patterns

Pattern 1: A Different Track for Each Part of the Story

Give each part of the video its own track. Scenes in a row that share a track continue it. The top-level volume sets the level of every scene track.

{
  "backgroundMusic": { "enabled": false, "volume": 0.3 },
  "scenes": [
    { "story": "The problem...",      "backgroundMusic": { "musicUrl": "TENSE_TRACK" } },
    { "story": "Why it matters...",   "backgroundMusic": { "musicUrl": "TENSE_TRACK" } },  // continues
    { "story": "The solution...",     "backgroundMusic": { "musicUrl": "UPLIFTING_TRACK" } },
    { "story": "Get started today.",  "backgroundMusic": { "musicUrl": "UPLIFTING_TRACK" } }  // continues
  ]
}

Result: Two tracks, each carried through its part of the story, with a short fade where they meet.

Pattern 2: Music Only on Specific Scenes

With video-level music off, only the scenes with a musicUrl have music.

{
  "backgroundMusic": { "enabled": false, "volume": 0.3 },
  "scenes": [
    { "story": "Intro scene with energy!",       "backgroundMusic": { "musicUrl": "UPBEAT_TRACK" } },  // music
    { "story": "Main content without distraction..." },                                              // silent
    { "story": "Detailed explanation..." },                                                          // silent
    { "story": "Exciting outro! Subscribe now!", "backgroundMusic": { "musicUrl": "UPBEAT_TRACK" } }   // music
  ]
}

Result: Music during the intro and outro only. The outro does not continue the intro’s track, because silent scenes sit between them, so the track starts again.

Pattern 3: One Track with a Different Moment

Keep one track for the video and swap it out for a single scene.

{
  "backgroundMusic": { "enabled": true, "musicUrl": "MAIN_TRACK", "volume": 0.3 },
  "scenes": [
    { "story": "Welcome..." },                                                              // MAIN_TRACK
    { "story": "A customer's story...", "backgroundMusic": { "musicUrl": "SOFT_PIANO" } },  // SOFT_PIANO at 0.3
    { "story": "Back to the product..." }                                                   // MAIN_TRACK resumes
  ]
}

Result: The main track plays throughout, gives way to soft piano for the testimonial, and comes back where it would have been.

Pattern 4: Silence for Key Moments

Turn music off where a message must be heard on its own.

{
  "backgroundMusic": { "enabled": true, "autoMusic": true, "volume": 0.3 },
  "scenes": [
    { "story": "Welcome to our presentation..." },                                        // music
    { "story": "IMPORTANT: Please note this key point...", "backgroundMusic": { "enabled": false } },  // silent
    { "story": "Continuing with our discussion..." }                                      // music
  ]
}

Result: Music throughout, except during the critical message.

In Previews, Renders and Saved Projects

All the scene music is joined into one soundtrack, so:

The storyboard has one music track. In the preview, the music is one audio element that plays the whole soundtrack. Each scene’s volume is already in the soundtrack.
You can change the whole soundtrack, not one scene. With Update Storyboard Elements, you can replace the soundtrack or make it quieter. You cannot change the music of one scene, or make the soundtrack louder than you designed it. To change one scene’s music, create the storyboard again.
A saved project keeps the soundtrack. With saveProject: true, the project in your Pictory account uses the soundtrack as one custom music track.

Best Practices

Match Tracks to the Story

Choose each track for the part of the story it plays under. Group neighboring scenes that share a mood (an opening, the problem, the turn, the close) and give each group one track, so the music changes when the story does rather than on every scene.

Keep Music Under the Narration

With a voice-over, keep music volumes low, around 0.1–0.3. A scene track without its own volume uses backgroundMusic.volume, so setting that once keeps every scene at the same level.

Use Silence on Purpose

Turn music off for calls to action, statistics, testimonials or disclaimers that must be heard clearly. Silence stands out most when the scenes around it have music.

Preview Before Rendering

Build a storyboard preview first and listen to where the music changes. Changes land on scene boundaries, so adjust scene lengths if a change falls in an awkward place.

Troubleshooting

Request Rejected for Scene Music

Cause: The scene sets volume without musicUrl, a volume outside 0–1, a musicUrl that is not a valid URL, or a backgroundMusic object with neither musicUrl nor enabled.Resolution:

Add the scene’s musicUrl, or remove the scene volume to use the video-level volume.
Keep volumes between 0 and 1.
Use a complete https:// URL for musicUrl.

Job Fails with MUSIC_URL_UNREADABLE

Cause: A musicUrl could not be read as audio, for example because it needs a sign-in, has expired, or does not point to an audio file.Resolution:

Open the URL in a private browser window and confirm it plays.
Use a public URL to an MP3 or another common audio format.
For library music, pass the audioUrl from Search Music Tracks exactly as returned.

Job Fails with MUSIC_LICENSE_FAILED

Cause: A track from Pictory’s music library could not be licensed.Resolution:

Run the request again; the failure is usually temporary.
If it fails again, search for the track once more and use the new audioUrl, or choose another track.

Job Fails with SCENE_MUSIC_BUILD_FAILED

Cause: The scene tracks could not be joined into one soundtrack.Resolution:

Check that every musicUrl plays on its own.
Run the request again. If it keeps failing, contact support with the job ID.

A Scene Without a Track Has No Music

Cause: Video-level music is off (backgroundMusic.enabled is false), or it is on without a track and the template has no music of its own.Resolution:

Set enabled: true with a video-level musicUrl or autoMusic: true to play music under the scenes without a track of their own.
Or give the scene its own musicUrl.

A Track Starts Again Instead of Continuing

Cause: A track continues only across scenes in a row that use exactly the same musicUrl. A scene in between with other music, or none, ends the run.Resolution:

Use the identical URL on each scene, copied exactly, including any query string.
Keep the scenes that share a track next to each other.

Next Steps

Background Music

Configure music for the whole video

Search Music Tracks

Find licensed tracks by mood, genre and length

AI Voice-Over

Add narration that sits over the music

Update Storyboard Elements

Change a preview before rendering it

API Reference

Create Storyboard Preview: the scenes[].backgroundMusic object
Render Storyboard Video: render with the same request
Get Video Render Job: job status, errors and the YouTube clearance code

​What You’ll Learn

A Track per Scene

Volume per Scene

Mixing with Video Music

Music On and Off

​Before You Begin

​How Scene-Level Music Works

​Complete Example

​Understanding the Parameters

​Video-Level Background Music