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

# Background Video Settings

> Control background video behavior with mute and loop settings for precise audio and playback control

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

<CardGroup cols={2}>
  <Card title="Mute Control" icon="volume-xmark">
    Control background video audio on/off
  </Card>

  <Card title="Loop Settings" icon="repeat">
    Configure video looping behavior
  </Card>

  <Card title="Audio Management" icon="waveform">
    Prevent audio conflicts in scenes
  </Card>

  <Card title="Playback Control" icon="play">
    Fine-tune video playback behavior
  </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
* Video files for backgrounds (or using stock library)
* Understanding of when to use mute/loop settings

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

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

## How Background Video Settings Work

When you configure background video settings:

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

<Note>
  Background video settings only apply to video backgrounds. They are ignored for image backgrounds and color backgrounds, which have no audio or inherent duration.
</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 =
    "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();
  ```

  ```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 = (
      "AI is poised to significantly impact educators and course creators on social media."
  )

  def create_video_with_background_settings():
      try:
          print("Creating video with background video settings...")

          response = requests.post(
              f'{API_BASE_URL}/v2/video/storyboard/render',
              json={
                  '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
              }
          )
          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 background settings 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_background_settings()
  ```
</CodeGroup>

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

<Warning>
  **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.
</Warning>

## Mute Setting Explained

### Mute: true (Default - Recommended)

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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.

<Tip>
  **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.
</Tip>

## Loop Setting Explained

### Loop: true (Default)

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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)

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

```javascript theme={null}
{
  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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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 do not jar
    * **Duration Matching**: If video length ≥ scene, loop is automatic
  </Accordion>

  <Accordion title="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 should not 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
  </Accordion>

  <Accordion title="Combine with Background Music Carefully">
    Manage audio layers properly:

    * **Mute Video**: Always `mute: true` when using background music
    * **One Audio Source**: Do not mix background video audio + music
    * **Layering**: Voice-over + music works; voice-over + video audio + music does not
    * **Volume Balance**: If using video audio, omit background music
    * **Audio Design**: Plan overall audio strategy before settings
    * **Professional Mix**: Fewer audio layers = cleaner sound
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Settings not affecting output">
    **Problem:** Background video settings do not seem to apply.

    **Solution:**

    * Verify you are 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
  </Accordion>

  <Accordion title="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 is not from voice-over or background music instead
    * Ensure you are testing the correct video output
    * Try explicitly setting `mute: true` (do not rely on default)
    * Test with different video to rule out video-specific issue
    * Check if audio is from a different layer in your composition
  </Accordion>

  <Accordion title="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 will not be noticeable anyway
    * Preview output to confirm loop behavior
  </Accordion>

  <Accordion title="Video Does Not Loop When Expected">
    **Problem:** Short video does not 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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Settings with Custom Video URLs

When using custom video URLs with background settings:

```javascript theme={null}
{
  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:

```javascript theme={null}
{
  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:

<CardGroup cols={2}>
  <Card title="Video Intro and Outro" icon="clapperboard" href="/guides/advanced-features/intro-outro-video">
    Add video-based intro and outro sequences
  </Card>

  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add audio layers to your videos
  </Card>

  <Card title="Custom Visual Filters" icon="filter" href="/guides/advanced-features/visual-search-filters">
    Control which videos are selected
  </Card>

  <Card title="Scene Transitions" icon="right-left" href="/guides/advanced-features/transitions">
    Add transitions between background videos
  </Card>
</CardGroup>

## API Reference

For complete technical details, see:

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