Background Video Settings

This guide shows you how to configure background video settings to control audio and looping behavior. Mute background video audio to prevent conflicts with voice-over, and control whether videos loop or play once for professional scene composition.

What You’ll Learn

Mute Control

Control background video audio on/off

Loop Settings

Configure video looping behavior

Audio Management

Prevent audio conflicts in scenes

Playback Control

Fine-tune video playback behavior

Before You Begin

Make sure you have:

A Pictory API key (get one here)
Node.js or Python installed on your machine
Video files for backgrounds (or using stock library)
Understanding of when to use mute/loop settings

npm install axios

How Background Video Settings Work

When you configure background video settings:

Settings Definition - You specify mute and/or loop settings for scene
Background Type Detection - System identifies background type (video/image/color)
Settings Application - Mute and loop are applied to video backgrounds
Audio Processing - Video audio is muted if mute: true
Loop Processing - Video loops or plays once based on loop setting
Duration Matching - Video duration is handled according to loop setting
Scene Rendering - Final scene rendered with configured video behavior

Background video settings only apply to video backgrounds. They are ignored for image backgrounds and color backgrounds, which have no audio or inherent duration.

Complete Example

import axios from "axios";

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

const STORY_TEXT =
  "AI is poised to significantly impact educators and course creators on social media.";

async function createVideoWithBackgroundSettings() {
  try {
    console.log("Creating video with background video settings...");

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

        scenes: [
          {
            story: STORY_TEXT,
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,

            // Background video settings
            background: {
              settings: {
                mute: true,        // Mute background video audio
                loop: false        // Don't loop video, play once
              }
            }
          }
        ]
      },
      {
        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 background settings 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;
  }
}

createVideoWithBackgroundSettings();

Understanding the Parameters

Background Video Settings

Parameter	Type	Default	Description
`background.settings.mute`	boolean	`true`	When `true`, mutes background video audio. When `false`, includes video’s original audio.
`background.settings.loop`	boolean	`true`	When `true`, loops video if shorter than scene duration. When `false`, video plays once and freezes on last frame.

Settings Application by Background Type

Background Type	Mute Applies?	Loop Applies?	Notes
Video	✓ Yes	✓ Yes	Both settings are applied to video playback
Image	✗ No	✗ No	Images have no audio or duration, settings ignored
Color	✗ No	✗ No	Color backgrounds have no audio or duration

Important: If loop is set to false and the background video is shorter than the scene duration, the video will freeze on its last frame for the remaining scene duration.

Mute Setting Explained

Mute: true (Default - Recommended)

{
  background: {
    settings: {
      mute: true    // Background video audio is muted
    }
  }
}

When to use:

You have voice-over narration
Using background music separately
Want only visual elements from video
Prevent audio conflicts or distraction
Most common use case for background videos

Result: Video plays visually but without its original audio.

Mute: false

{
  background: {
    settings: {
      mute: false   // Background video audio plays
    }
  }
}

When to use:

Background video has desired ambient sound
No voice-over or competing audio
Video audio adds value to the scene
Creating atmospheric soundscapes

Result: Video plays with its original audio track.

Best Practice: Always set mute: true when using voice-over or background music to prevent audio conflicts. Set mute: false only when the background video’s audio is intentionally part of your audio design.

Loop Setting Explained

Loop: true (Default)

{
  background: {
    settings: {
      loop: true    // Video repeats if shorter than scene
    }
  }
}

When to use:

Background video is shorter than scene duration
Want continuous motion throughout scene
Using short clips as repeating backgrounds
Creating seamless visual atmosphere

Result: Video loops continuously until scene ends. Example: 5-second video in 15-second scene plays 3 times.

Loop: false

{
  background: {
    settings: {
      loop: false   // Video plays once, then freezes
    }
  }
}

When to use:

Intro/outro videos that should play once
Video has specific timeline or narrative
Video length matches or exceeds scene duration
Don’t want repetitive motion

Result: Video plays once, then displays last frame. Example: 5-second video in 15-second scene plays once, freezes last frame for 10 seconds.

Configuration Combinations

Combination 1: Muted Looping (Most Common)

{
  background: {
    settings: {
      mute: true,      // No background video audio
      loop: true       // Repeat video throughout scene
    }
  }
}

Use Case: Standard scenes with voice-over and repeating visual background.

Combination 2: Muted Non-Looping

{
  background: {
    settings: {
      mute: true,      // No background video audio
      loop: false      // Play once and freeze
    }
  }
}

Use Case: Intro/outro videos with voice-over, video plays once.

Combination 3: Audio with Looping

{
  background: {
    settings: {
      mute: false,     // Include video audio
      loop: true       // Repeat video and audio
    }
  }
}

Use Case: Atmospheric background with ambient sounds, no voice-over.

Combination 4: Audio Without Looping

{
  background: {
    settings: {
      mute: false,     // Include video audio
      loop: false      // Play once, then freeze
    }
  }
}

Use Case: Video with narrative or specific audio timeline.

Common Use Cases

Educational Video with Voice-Over

{
  scenes: [
    {
      story: "Today we'll learn about marine ecosystems...",
      background: {
        type: "video",
        visualUrl: "https://example.com/ocean-background.mp4",
        settings: {
          mute: true,       // Mute so voice-over is clear
          loop: true        // Loop ocean footage throughout
        }
      }
    }
  ],
  voiceOver: {
    enabled: true,
    aiVoices: [{ speaker: "Emma" }]
  }
}

Result: Clear voice-over with looping ocean visuals, no audio conflicts.

Branded Intro Sequence

{
  scenes: [
    {
      background: {
        type: "video",
        visualUrl: "https://example.com/brand-intro.mp4",
        settings: {
          mute: true,       // Mute intro video
          loop: false       // Play intro once, don't repeat
        }
      },
      minimumDuration: 5
    }
  ]
}

Result: Brand intro plays once without looping, muted for clean presentation.

Ambient Scene with Natural Sounds

{
  scenes: [
    {
      story: "Experience the tranquility of nature...",
      background: {
        type: "video",
        visualUrl: "https://example.com/forest-with-birds.mp4",
        settings: {
          mute: false,      // Include natural forest sounds
          loop: true        // Loop ambient video and sounds
        }
      }
    }
  ]
  // No voice-over - letting ambient audio create atmosphere
}

Result: Video with forest sounds playing, creating immersive atmosphere.

Product Demo Without Audio Distraction

{
  scenes: [
    {
      story: "Our product features cutting-edge technology...",
      background: {
        type: "video",
        visualUrl: "https://example.com/product-demo.mp4",
        settings: {
          mute: true,       // Mute product demo audio
          loop: false       // Show demo once completely
        }
      }
    }
  ],
  backgroundMusic: {
    enabled: true,
    musicUrl: "https://example.com/background-music.mp3",
    volume: 0.3
  }
}

Result: Product demo visual with background music instead of original demo audio.

Best Practices

Always Mute When Using Voice-Over

Prevent audio conflicts in narrated videos:

Default to Mute: Set mute: true for all narrated content
Audio Clarity: Ensures voice-over is clearly heard
No Distraction: Background video audio can distract from message
Professional Sound: Clean audio mix sounds more professional
Predictable Output: Eliminates unexpected background audio
Test Exception: Only use mute: false intentionally for specific effect

Use Loop for Short Background Clips

Ensure continuous motion in scenes:

Short Clips: Loop 3-10 second clips for longer scenes
Seamless Loops: Choose videos designed to loop seamlessly
Visual Continuity: Maintains motion throughout scene
Stock Library: Many stock videos are designed for looping
Test Loops: Preview to ensure loop points don’t jar
Duration Matching: If video length ≥ scene, loop is automatic

Disable Loop for Narrative Videos

Play specific sequences once:

Intro/Outro: Set loop: false for branded intro/outro sequences
Specific Timeline: Use for videos with beginning/middle/end
One-Time Events: Actions that shouldn’t repeat (explosions, reveals)
Timed Sequences: When video timing is crucial to message
Duration Match: Ensure video length matches or exceeds scene duration
Freeze Planning: Consider if final frame makes sense frozen

Combine with Background Music Carefully

Manage audio layers properly:

Mute Video: Always mute: true when using background music
One Audio Source: Don’t mix background video audio + music
Layering: Voice-over + music works; voice-over + video audio + music doesn’t
Volume Balance: If using video audio, omit background music
Audio Design: Plan overall audio strategy before settings
Professional Mix: Fewer audio layers = cleaner sound

Test Different Settings for Scene Type

Optimize settings per scene purpose:

Intro Scenes: Typically mute: true, loop: false
Content Scenes: Typically mute: true, loop: true
Outro Scenes: Typically mute: true, loop: false
Ambient Scenes: May use mute: false for atmosphere
Preview First: Test settings with actual content before finalizing
Document Patterns: Record which settings work for different scene types

Troubleshooting

Settings not affecting output

Problem: Background video settings don’t seem to apply.Solution:

Verify you’re using a video background (not image or color)
Check settings are in background.settings, not elsewhere
Ensure JSON structure is correct with proper nesting
Settings only apply to video backgrounds, ignored for images
Test with known video URL to isolate issue
Review API response for any validation errors

Video audio still playing when muted

Problem: Background video audio plays despite mute: true.Solution:

Verify mute: true is set in background.settings
Check audio isn’t from voice-over or background music instead
Ensure you’re testing the correct video output
Try explicitly setting mute: true (don’t rely on default)
Test with different video to rule out video-specific issue
Check if audio is from a different layer in your composition

Video loops unexpectedly

Problem: Video keeps looping when you want it to play once.Solution:

Set loop: false explicitly in background.settings
Default behavior is loop: true, must override
Verify setting is within the scene’s background configuration
Check that video length is actually shorter than scene duration
If video ≥ scene duration, looping won’t be noticeable anyway
Preview output to confirm loop behavior

Video doesn't loop when expected

Problem: Short video doesn’t loop, plays once and stops/freezes.Solution:

Check if loop: false is accidentally set
Default is loop: true, so check for overrides
Verify video length is actually shorter than scene
If video matches scene length, no loop needed
Check minimumDuration vs actual video duration
Test with explicitly set loop: true

Video freezes on last frame

Problem: Video plays once and freezes, but want different behavior.Solution:

This happens when loop: false and video < scene duration
Set loop: true to repeat video instead of freezing
Or adjust scene duration to match video length
Or use longer video that fills entire scene
This is expected behavior with loop: false
Plan scenes knowing non-looping videos will freeze

Cannot control specific audio elements

Problem: Want to control music vs effects in background video.Solution:

mute setting is all-or-nothing for video audio
Cannot selectively mute parts of video’s audio track
Options:
- Use video editing software to remove audio before upload
- Choose background videos without audio
- Use mute: true and add background music separately
Cannot isolate or control individual audio elements
This is a limitation of background video audio control

Settings with Custom Video URLs

When using custom video URLs with background settings:

{
  background: {
    type: "video",
    visualUrl: "https://example.com/your-video.mp4",
    settings: {
      mute: true,
      loop: false
    }
  }
}

Considerations:

Ensure video URL is publicly accessible
Video format should be MP4 for best compatibility
Test video plays correctly before applying settings
Settings apply regardless of video source (custom or stock)

Default Behavior

When no settings are specified:

{
  background: {
    type: "video",
    visualUrl: "https://example.com/video.mp4"
    // No settings specified
  }
}

Default Values:

mute: true (background video audio is muted by default)
loop: true (video loops by default if shorter than scene)

This default behavior works well for most use cases with voice-over.

Next Steps

Enhance your background video control with these complementary features:

Video Intro and Outro

Add video-based intro and outro sequences

Background Music

Add audio layers to your videos

Custom Visual Filters

Control which videos are selected

Scene Transitions

Add transitions between background videos

API Reference

For complete technical details, see:

Render Storyboard Video - Full API specification including background settings
Get Job Status - Monitor job status and get video URLs

Getting started

Text to Video

Article to Video

Presentation to Video

Audio to Video

Video to Shorts

Video Story CoPilot

Smart Layouts and Subtitles

Branding & Customization

Advanced Features

​What You’ll Learn

Mute Control

Loop Settings

Audio Management

Playback Control

​Before You Begin

​How Background Video Settings Work

​Complete Example

​Understanding the Parameters

​Background Video Settings

​Settings Application by Background Type

​Mute Setting Explained

​Mute: true (Default - Recommended)

​Mute: false

​Loop Setting Explained

​Loop: true (Default)

​Loop: false

​Configuration Combinations

​Combination 1: Muted Looping (Most Common)

​Combination 2: Muted Non-Looping

​Combination 3: Audio with Looping

​Combination 4: Audio Without Looping

​Common Use Cases

​Educational Video with Voice-Over

​Branded Intro Sequence

​Ambient Scene with Natural Sounds

​Product Demo Without Audio Distraction

​Best Practices

​Troubleshooting

​Settings with Custom Video URLs

​Default Behavior

​Next Steps

Video Intro and Outro

Background Music

Custom Visual Filters

Scene Transitions

​API Reference

What You’ll Learn

Before You Begin

How Background Video Settings Work

Complete Example

Understanding the Parameters

Background Video Settings

Settings Application by Background Type

Mute Setting Explained

Mute: true (Default - Recommended)

Mute: false

Loop Setting Explained

Loop: true (Default)

Loop: false

Configuration Combinations

Combination 1: Muted Looping (Most Common)

Combination 2: Muted Non-Looping

Combination 3: Audio with Looping

Combination 4: Audio Without Looping

Common Use Cases

Educational Video with Voice-Over

Branded Intro Sequence

Ambient Scene with Natural Sounds

Product Demo Without Audio Distraction

Best Practices

Troubleshooting

Settings with Custom Video URLs

Default Behavior

Next Steps

API Reference