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

> Dynamically adjust avatar appearance and behavior for each scene

<Note>
  **🎉 New Feature!** Customize avatar appearance per scene for dynamic, professional videos.
</Note>

## Overview

Scene-level avatar customization allows you to adapt your avatar's appearance, position, and visibility for each individual scene. This creates dynamic, professional videos that respond to changing content and backgrounds.

<Note>
  Scene-level settings override global avatar configuration. Any property not specified at the scene level inherits from the global avatar settings.
</Note>

***

## How It Works

### Global vs Scene-Level Configuration

```javascript theme={null}
{
  // Global avatar configuration (applies to all scenes)
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%",
    "backgroundColor": "rgba(255,255,255,1)"
  },

  "scenes": [
    {
      // Scene 1: Uses global avatar settings
      "story": "Introduction scene"
    },
    {
      // Scene 2: Overrides position and background color
      "story": "Demo scene with custom layout",
      "avatar": {
        "top": "10%",
        "left": "5%",
        "backgroundColor": "rgba(244,241,246,1)"
      }
    },
    {
      // Scene 3: Hides avatar completely
      "story": "Focus on content without avatar",
      "avatar": {
        "hide": true
      }
    }
  ]
}
```

<Tip>
  **Pro Tip:** Define your default avatar configuration globally, then only override specific properties in scenes where you need different behavior.
</Tip>

***

## Common Use Cases

### Use Case 1: Hide Avatar for Specific Scenes

Hide the avatar to focus attention on content:

```javascript theme={null}
{
  "avatar": {
    "avatarId": "Annie_expressive12_public",
    "position": "bottom-right",
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Welcome to our product demo. I will guide you through the features.",
      // Avatar visible (uses global config)
    },
    {
      "story": "Here is our product interface.",
      "background": {
        "visualUrl": "https://example.com/product-screenshot.jpg",
        "type": "image"
      },
      // Hide avatar to show full interface
      "avatar": {
        "hide": true
      }
    },
    {
      "story": "Now let me explain how it works.",
      // Avatar returns (uses global config again)
    }
  ]
}
```

**When to hide avatar:**

* Showing detailed interfaces or dashboards
* Displaying full-screen graphics
* Focusing on text-heavy content
* Transition scenes or title cards

***

### Use Case 2: Reposition for Background Content

Move avatar to avoid covering important content:

```javascript theme={null}
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",  // Default position
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Let me show you our dashboard.",
      "background": {
        "visualUrl": "https://example.com/dashboard-right-panel.jpg",
        "type": "image"
      },
      // Move to left since important content is on right
      "avatar": {
        "position": "bottom-left"
      }
    },
    {
      "story": "Here are the analytics charts.",
      "background": {
        "visualUrl": "https://example.com/charts-left-side.jpg",
        "type": "image"
      },
      // Move to right since charts are on left
      "avatar": {
        "position": "bottom-right"
      }
    }
  ]
}
```

***

### Use Case 3: Adjust Size for Emphasis

Vary avatar size based on scene importance:

```javascript theme={null}
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%"  // Standard size
  },

  "scenes": [
    {
      "story": "Welcome! I am excited to share this with you.",
      // Larger avatar for personal introduction
      "avatar": {
        "width": "28%",
        "position": "center-right"
      }
    },
    {
      "story": "Here are the technical details and specifications.",
      // Smaller avatar to focus on content
      "avatar": {
        "width": "15%"
      }
    },
    {
      "story": "Thank you for watching! Remember to subscribe.",
      // Larger avatar for closing statement
      "avatar": {
        "width": "25%"
      }
    }
  ]
}
```

***

### Use Case 4: Change Background Color by Scene

Adapt avatar background for different video backgrounds:

```javascript theme={null}
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%",
    "backgroundColor": "rgba(255,255,255,1)"  // White by default
  },

  "scenes": [
    {
      "story": "This is our light-themed interface.",
      "background": {
        "color": "rgba(245,245,245,1)"  // Light gray background
      }
      // Uses default white avatar background
    },
    {
      "story": "And here is our dark mode.",
      "background": {
        "color": "rgba(30,30,30,1)"  // Dark background
      },
      // Dark avatar background for contrast
      "avatar": {
        "backgroundColor": "rgba(50,50,50,0.9)"
      }
    }
  ]
}
```

***

### Use Case 5: Custom Positioning for Complex Layouts

Use precise positioning for specific scene requirements:

```javascript theme={null}
{
  "avatar": {
    "avatarId": "...",
    "position": "bottom-right",
    "width": "20%"
  },

  "scenes": [
    {
      "story": "Standard introduction scene."
      // Uses preset position
    },
    {
      "story": "Special layout scene.",
      "background": {
        "visualUrl": "https://example.com/complex-layout.jpg",
        "type": "image"
      },
      // Fine-tuned positioning
      "avatar": {
        "top": "18%",
        "left": "76%",
        "width": "22%"
      }
    }
  ]
}
```

***

## Scene-Level Properties

All avatar properties can be overridden at scene level:

<ParamField body="avatar.position" type="string">
  Override preset position: `top-left`, `top-center`, `top-right`, `center-left`, `center-center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`
</ParamField>

<ParamField body="avatar.top" type="string">
  Custom top position as percentage (e.g., "10%", "25%")
</ParamField>

<ParamField body="avatar.left" type="string">
  Custom left position as percentage (e.g., "5%", "80%")
</ParamField>

<ParamField body="avatar.width" type="string">
  Avatar width as percentage (e.g., "15%", "20%", "30%")
</ParamField>

<ParamField body="avatar.borderRadius" type="string">
  Corner rounding: `"0"`, `"50"`, `"100"`
</ParamField>

<ParamField body="avatar.borderColor" type="string">
  Border color in RGBA format (e.g., "rgba(255,255,255,1)", "rgba(132,44,254,1)")
</ParamField>

<ParamField body="avatar.borderThickness" type="number">
  Border width in pixels (0, 2, 4, 6, 8)
</ParamField>

<ParamField body="avatar.backgroundColor" type="string">
  Background color in RGBA (e.g., "rgba(255,255,255,1)")
</ParamField>

<ParamField body="avatar.hide" type="boolean">
  Hide avatar for this scene (`true` or `false`)
</ParamField>

<Warning>
  **Important:** You cannot change `avatarId` at the scene level. The same avatar must be used throughout the video. You can only override styling and positioning properties.
</Warning>

***

## Advanced Patterns

### Pattern 1: Progressive Avatar Presence

Start subtle, become more prominent, then fade out:

```javascript theme={null}
{
  "scenes": [
    {
      "story": "Opening title sequence.",
      "avatar": { "hide": true }
    },
    {
      "story": "Hello, welcome to the presentation.",
      "avatar": { "width": "18%", "position": "bottom-right" }
    },
    {
      "story": "Let me explain the key concepts in detail.",
      "avatar": { "width": "22%", "position": "center-right" }
    },
    {
      "story": "Here are the detailed specifications.",
      "avatar": { "hide": true }
    },
    {
      "story": "Thank you for watching!",
      "avatar": { "width": "25%", "position": "center-center" }
    },
    {
      "story": "Closing credits.",
      "avatar": { "hide": true }
    }
  ]
}
```

***

### Pattern 2: Split-Screen Effect

Position avatar on alternating sides for visual variety:

```javascript theme={null}
{
  "scenes": [
    {
      "story": "First point about product benefits.",
      "avatar": { "position": "center-left", "width": "25%" }
    },
    {
      "story": "Second point about ease of use.",
      "avatar": { "position": "center-right", "width": "25%" }
    },
    {
      "story": "Third point about pricing.",
      "avatar": { "position": "center-left", "width": "25%" }
    },
    {
      "story": "Fourth point about support.",
      "avatar": { "position": "center-right", "width": "25%" }
    }
  ]
}
```

***

### Pattern 3: Background-Adaptive Positioning

Automatically adjust based on background content:

```javascript theme={null}
const createSceneWithAdaptiveAvatar = (story, backgroundUrl, contentPosition) => {
  const avatarPosition = {
    left: 'bottom-right',
    right: 'bottom-left',
    center: 'top-center',
    top: 'bottom-center',
    bottom: 'top-center'
  };

  return {
    story,
    background: {
      visualUrl: backgroundUrl,
      type: 'image',
      settings: { mute: true, loop: true }
    },
    avatar: {
      position: avatarPosition[contentPosition]
    }
  };
};

const scenes = [
  createSceneWithAdaptiveAvatar(
    'Content on left side',
    'https://example.com/left-content.jpg',
    'left'
  ),
  createSceneWithAdaptiveAvatar(
    'Content on right side',
    'https://example.com/right-content.jpg',
    'right'
  )
];
```

***

### Pattern 4: Themed Scenes with Matching Avatar Style

Coordinate avatar styling with scene themes:

```javascript theme={null}
{
  "scenes": [
    {
      "story": "Welcome to our professional services overview.",
      // Professional theme: subtle, neutral
      "background": { "color": "rgba(240,240,245,1)" },
      "avatar": {
        "backgroundColor": "rgba(255,255,255,1)",
        "borderColor": "rgba(204,204,204,1)",
        "borderThickness": 2,
        "borderRadius": "50"
      }
    },
    {
      "story": "Now for our creative solutions!",
      // Creative theme: colorful, bold
      "background": { "color": "rgba(255,235,245,1)" },
      "avatar": {
        "backgroundColor": "rgba(132,44,254,0.15)",
        "borderColor": "rgba(132,44,254,1)",
        "borderThickness": 4,
        "borderRadius": "100"
      }
    }
  ]
}
```

***

## Complete Example

Here's a full video demonstrating multiple customization techniques:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pictory.ai/pictoryapis/v2/video/storyboard', {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      videoName: 'dynamic_avatar_demo',
      language: 'en',
      videoWidth: 1920,
      videoHeight: 1080,
      saveProject: true,

      voiceOver: {
        enabled: true,
        aiVoices: [{
          speaker: 'Matthew',
          speed: 100
        }]
      },

      backgroundMusic: {
        enabled: true,
        autoMusic: true,
        volume: 0.15
      },

      // Global avatar configuration
      avatar: {
        avatarId: 'Annie_expressive12_public',
        position: 'bottom-right',
        width: '20%',
        borderRadius: '100',
        borderColor: 'rgba(185,185,186,1)',
        borderThickness: 4,
        backgroundColor: 'rgba(255,255,255,1)'
      },

      scenes: [
        {
          story: 'Welcome to our product demonstration. I will guide you through all the features.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4
          // Uses global avatar settings
        },
        {
          story: 'First, let me show you the main dashboard interface.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4,
          background: {
            type: 'image',
            visualUrl: 'https://example.com/dashboard.jpg',
            settings: { mute: true }
          },
          // Hide avatar to show full interface
          avatar: {
            hide: true
          }
        },
        {
          story: 'The dashboard provides real-time analytics and insights.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4
          // Avatar returns with global settings
        },
        {
          story: 'Now let us look at the settings panel on the right side.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4,
          background: {
            type: 'image',
            visualUrl: 'https://example.com/settings-right.jpg',
            settings: { mute: true }
          },
          // Move avatar to left to avoid covering settings
          avatar: {
            position: 'bottom-left',
            width: '18%'
          }
        },
        {
          story: 'Thank you for watching! Visit our website to learn more.',
          createSceneOnEndOfSentence: true,
          minimumDuration: 4,
          // Larger, centered avatar for closing
          avatar: {
            position: 'center-center',
            width: '28%'
          }
        }
      ]
    })
  });

  const result = await response.json();
  console.log('Job ID:', result.data.jobId);
  ```

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

  response = requests.post(
      'https://api.pictory.ai/pictoryapis/v2/video/storyboard',
      headers={
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'videoName': 'dynamic_avatar_demo',
          'language': 'en',
          'videoWidth': 1920,
          'videoHeight': 1080,
          'saveProject': True,

          'voiceOver': {
              'enabled': True,
              'aiVoices': [{
                  'speaker': 'Matthew',
                  'speed': 100
              }]
          },

          'backgroundMusic': {
              'enabled': True,
              'autoMusic': True,
              'volume': 0.15
          },

          # Global avatar configuration
          'avatar': {
              'avatarId': 'Annie_expressive12_public',
              'position': 'bottom-right',
              'width': '20%',
              'borderRadius': '100',
              'borderColor': 'rgba(185,185,186,1)',
              'borderThickness': 4,
              'backgroundColor': 'rgba(255,255,255,1)'
          },

          'scenes': [
              {
                  'story': 'Welcome to our product demonstration. I will guide you through all the features.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4
                  # Uses global avatar settings
              },
              {
                  'story': 'First, let me show you the main dashboard interface.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4,
                  'background': {
                      'type': 'image',
                      'visualUrl': 'https://example.com/dashboard.jpg',
                      'settings': {'mute': True}
                  },
                  # Hide avatar to show full interface
                  'avatar': {
                      'hide': True
                  }
              },
              {
                  'story': 'Now let us look at the settings panel on the right side.',
                  'createSceneOnEndOfSentence': True,
                  'minimumDuration': 4,
                  'background': {
                      'type': 'image',
                      'visualUrl': 'https://example.com/settings-right.jpg',
                      'settings': {'mute': True}
                  },
                  # Move avatar to left
                  'avatar': {
                      'position': 'bottom-left',
                      'width': '18%'
                  }
              }
          ]
      }
  )

  result = response.json()
  print(f"Job ID: {result['data']['jobId']}")
  ```
</CodeGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Plan Your Scene Flow">
    **Before coding:**

    * Sketch your video flow
    * Identify scenes where avatar should hide
    * Mark scenes needing position changes
    * Note background content locations

    **Benefits:**

    * Smoother visual transitions
    * Better content presentation
    * Fewer adjustments needed
  </Accordion>

  <Accordion title="Maintain Visual Consistency">
    **Guidelines:**

    * Keep avatar size consistent (±5% variation max)
    * Use the same styling throughout
    * Make position changes purposeful, not random
    * Return to default position when possible

    **Exception:**

    * Intro/outro scenes can have different sizes
  </Accordion>

  <Accordion title="Test Scene Transitions">
    **Check for:**

    * Jarring position jumps
    * Sudden size changes
    * Style inconsistencies
    * Background color clashes

    **Fix with:**

    * Gradual position shifts
    * Smoother size transitions
    * Consistent styling
    * Scene-appropriate colors
  </Accordion>

  <Accordion title="Hide Avatar Strategically">
    **Good reasons to hide:**

    * Full-screen demonstrations
    * Complex visual content
    * Title cards or transitions
    * Text-heavy information

    **Avoid hiding:**

    * For more than 2-3 consecutive scenes
    * Without clear visual benefit
    * Randomly throughout video
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Scene Override Not Working">
    **Problem:** Scene-level settings not applying

    **Check:**

    * Property names match exactly (case-sensitive)
    * RGBA format is correct for colors
    * Percentage values include "%" symbol
    * Not trying to override avatarId (identity field cannot be changed at scene level)

    **Solution:**

    ```javascript theme={null}
    // Correct
    avatar: {
      "backgroundColor": "rgba(255,255,255,1)",
      "width": "20%"
    }

    // Incorrect
    avatar: {
      "background-color": "rgb(255,255,255)",  // Wrong format
      "width": 20  // Missing %
    }
    ```
  </Accordion>

  <Accordion title="Avatar Jumps Between Scenes">
    **Problem:** Avatar position changes too abruptly

    **Solutions:**

    1. Use adjacent positions (e.g., bottom-right → bottom-center → bottom-left)
    2. Add transition scene between major position changes
    3. Keep position consistent for related content
    4. Test preview to verify smoothness
  </Accordion>

  <Accordion title="Inconsistent Avatar Appearance">
    **Problem:** Avatar looks different across scenes

    **Check:**

    * Border settings are consistent
    * Background colors have proper contrast
    * Size variations are intentional
    * All scenes inherit global settings properly

    **Fix:**

    * Set global defaults for consistency
    * Only override when necessary
    * Document your overrides
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### Scene Avatar Override Template

```javascript theme={null}
// Copy this template for scene-level customization
{
  "story": "Your scene text here",
  "createSceneOnEndOfSentence": true,
  "minimumDuration": 4,
  "avatar": {
    // Position (choose one method)
    "position": "bottom-right",        // OR
    "top": "10%", "left": "80%",       // Custom position

    // Size
    "width": "20%",

    // Styling
    "borderRadius": "100",
    "borderColor": "rgba(185,185,186,1)",
    "borderThickness": 4,
    "backgroundColor": "rgba(255,255,255,1)",

    // Visibility
    "hide": false
  }
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Avatar Positioning" icon="location-dot" href="/guides/video-with-avatar/avatar-positioning">
    Master positioning techniques and best practices
  </Card>

  <Card title="Create Avatar Video" icon="video" href="/guides/video-with-avatar/create-avatar-video">
    Complete guide to creating avatar videos
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/videos/create-storyboard-preview">
    Full technical API documentation
  </Card>

  <Card title="Background Settings" icon="image" href="/guides/advanced-features/background-video-settings">
    Configure background media settings
  </Card>
</CardGroup>