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

# Avatar Positioning

> Master avatar placement and styling for professional-looking videos

<Note>
  **🎉 New Feature!** Learn how to position and style AI avatars in your videos for maximum impact.
</Note>

## Overview

Strategic avatar positioning ensures your avatar complements rather than competes with your video content. This guide covers positioning techniques, styling options, and best practices for different video formats.

***

## Positioning Methods

There are two ways to position your avatar:

### 1. Preset Positions (Recommended for Quick Setup)

Use the `position` parameter with predefined locations:

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

**Available Positions:**

<CardGroup cols={3}>
  <Card title="top-left" icon="arrow-up-left">
    Upper left corner
  </Card>

  <Card title="top-center" icon="arrow-up">
    Top center
  </Card>

  <Card title="top-right" icon="arrow-up-right">
    Upper right corner
  </Card>

  <Card title="center-left" icon="arrow-left">
    Middle left
  </Card>

  <Card title="center-center" icon="circle-dot">
    Center screen
  </Card>

  <Card title="center-right" icon="arrow-right">
    Middle right
  </Card>

  <Card title="bottom-left" icon="arrow-down-left">
    Lower left corner
  </Card>

  <Card title="bottom-center" icon="arrow-down">
    Bottom center
  </Card>

  <Card title="bottom-right" icon="arrow-down-right">
    Lower right corner
  </Card>
</CardGroup>

***

### 2. Custom Positioning (Scene-Level Only)

Use `top` and `left` parameters for pixel-perfect placement. These are only available as **scene-level avatar overrides**, not at the global avatar level.

```json theme={null}
{
  "scenes": [
    {
      "story": "Scene with custom avatar placement.",
      "avatar": {
        "top": "18%",
        "left": "76%",
        "width": "20%"
      }
    }
  ]
}
```

<ParamField body="top" type="string">
  Distance from top edge as percentage (e.g., "10%", "25%", "50%"). Integer percentages only (0%-100%).
</ParamField>

<ParamField body="left" type="string">
  Distance from left edge as percentage (e.g., "5%", "50%", "80%"). Integer percentages only (0%-100%).
</ParamField>

<Warning>
  **Important:** `top`/`left` are only available at the scene level. Cannot use both `position` and `top`/`left` together in the same scene override.
</Warning>

***

## Avatar Sizing

Control avatar size with the `width` parameter:

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

### Recommended Sizes by Video Type

| Video Type | Recommended Width  | Use Case                                      |
| ---------- | ------------------ | --------------------------------------------- |
| **15-18%** | Subtle presence    | Background-focused videos, product demos      |
| **20-25%** | Balanced presence  | Most use cases, tutorials, training           |
| **25-30%** | Prominent presence | Presenter-style, talking head, announcements  |
| **30%+**   | Dominant presence  | Interview-style, personal vlogs, testimonials |

<Tip>
  **Pro Tip:** Start with 20% width and adjust based on your background content density. Busier backgrounds work better with smaller avatars.
</Tip>

***

## Styling Options

### Border Radius

Control the avatar container shape:

```json theme={null}
{
  "avatar": {
    "borderRadius": "100"
  }
}
```

| Value   | Shape            | Best For                       |
| ------- | ---------------- | ------------------------------ |
| `"0"`   | Square corners   | Modern, technical content      |
| `"10"`  | Slightly rounded | Soft professional look         |
| `"50"`  | Rounded corners  | Friendly, approachable style   |
| `"100"` | Circular         | Most popular, clean appearance |

***

### Border Styling

Add visual separation with borders:

```json theme={null}
{
  "avatar": {
    "borderColor": "rgba(185,185,186,1)",
    "borderThickness": 4
  }
}
```

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

<ParamField body="borderThickness" type="number">
  Border width in pixels. Minimum: 0, no maximum limit.

  Recommended: 2-4 pixels
</ParamField>

***

### Background Color

Add a background behind your avatar for better visibility:

```json theme={null}
{
  "avatar": {
    "backgroundColor": "rgba(255,255,255,1)"
  }
}
```

**Color Format:** RGBA - `rgba(red, green, blue, alpha)`

* Red, Green, Blue: 0-255
* Alpha (opacity): 0-1

**Common Background Colors:**

```json theme={null}
// Pure white (opaque)
"backgroundColor": "rgba(255,255,255,1)"

// Light gray
"backgroundColor": "rgba(244,241,246,1)"

// Semi-transparent white
"backgroundColor": "rgba(255,255,255,0.9)"

// Pure black (opaque)
"backgroundColor": "rgba(0,0,0,1)"

// Semi-transparent black
"backgroundColor": "rgba(0,0,0,0.8)"
```

<Tip>
  **Contrast Tip:** Use light backgrounds for dark video backgrounds and vice versa to ensure avatar visibility.
</Tip>

***

## Position Examples

### Example 1: Bottom-Right Corner (Default)

**Best for:** Most videos, non-intrusive placement

```json theme={null}
{
  "avatar": {
    "position": "bottom-right",
    "width": "20%",
    "borderRadius": "100",
    "backgroundColor": "rgba(255,255,255,1)"
  }
}
```

**Use when:**

* Subtitles are at the bottom center
* Background has important left-side content
* You want minimal distraction

***

### Example 2: Center-Left (Presenter Style)

**Best for:** Training videos, professional presentations

```json theme={null}
{
  "avatar": {
    "position": "center-left",
    "width": "25%",
    "borderRadius": "50",
    "backgroundColor": "rgba(244,241,246,1)"
  }
}
```

**Use when:**

* Background content is on the right
* Presenter-focused content
* Formal training or education

***

### Example 3: Custom Top-Right Position (Scene-Level)

**Best for:** Unique layouts, specific design requirements

```json theme={null}
{
  "scenes": [
    {
      "story": "Scene with custom avatar placement.",
      "avatar": {
        "top": "10%",
        "left": "75%",
        "width": "22%",
        "borderRadius": "100",
        "backgroundColor": "rgba(255,255,255,0.95)"
      }
    }
  ]
}
```

**Use when:**

* You need precise alignment per scene
* Matching specific brand guidelines
* Complex multi-element layouts

<Note>
  Custom `top`/`left` positioning is only available at the scene level. For global positioning, use the preset `position` parameter.
</Note>

***

### Example 4: Circular Avatar with Colored Border

**Best for:** Branded content, modern style

```json theme={null}
{
  "avatar": {
    "position": "bottom-left",
    "width": "18%",
    "borderRadius": "100",
    "borderColor": "rgba(132,44,254,1)",
    "borderThickness": 6,
    "backgroundColor": "rgba(255,255,255,1)"
  }
}
```

**Use when:**

* Incorporating brand colors
* Need visual accent
* Premium, polished appearance

***

## Position by Video Format

### 16:9 (Landscape / YouTube)

**Recommended Positions:**

* `bottom-right` or `bottom-left` (20-22% width)
* `center-right` or `center-left` (22-25% width)

**Avoid:**

* `bottom-center` (conflicts with subtitles)

```json theme={null}
{
  "videoWidth": 1920,
  "videoHeight": 1080,
  "avatar": {
    "position": "bottom-right",
    "width": "20%"
  }
}
```

***

### 9:16 (Vertical / TikTok, Instagram Reels)

**Recommended Positions:**

* `top-center` (25-30% width)
* `bottom-center` (20-25% width, if no subtitles)
* `center-center` (30%+ width for presenter style)

**Avoid:**

* Side positions (wasted space in vertical format)

```json theme={null}
{
  "videoWidth": 1080,
  "videoHeight": 1920,
  "avatar": {
    "position": "top-center",
    "width": "28%"
  }
}
```

***

### 1:1 (Square / Instagram Feed)

**Recommended Positions:**

* `bottom-right` or `bottom-left` (20-25% width)
* `top-right` or `top-left` (20-25% width)

**Avoid:**

* Center positions (takes too much space)

```json theme={null}
{
  "videoWidth": 1080,
  "videoHeight": 1080,
  "avatar": {
    "position": "bottom-right",
    "width": "22%"
  }
}
```

***

## Avoiding Common Mistakes

<AccordionGroup>
  <Accordion title="Overlapping Subtitles">
    **Problem:** Avatar covers important subtitle text

    **Solution:**

    * Place avatar in corners, not bottom-center
    * Use `top` positioning to avoid subtitle area
    * Reduce avatar size if necessary
    * Consider scene-level positioning adjustments

    ```json theme={null}
    // Good: Avatar in corner, subtitles in center
    {
      "avatar": { "position": "bottom-right", "width": "20%" }
    }

    // Bad: Avatar in center where subtitles appear
    {
      "avatar": { "position": "bottom-center", "width": "30%" }
    }
    ```
  </Accordion>

  <Accordion title="Poor Contrast">
    **Problem:** Avatar blends into background

    **Solution:**

    * Add background color with good contrast
    * Use border for separation
    * Adjust avatar position to clearer area
    * Consider semi-transparent backgrounds

    ```json theme={null}
    // Good: White background on dark video
    {
      "avatar": {
        "backgroundColor": "rgba(255,255,255,0.95)",
        "borderColor": "rgba(204,204,204,1)",
        "borderThickness": 2
      }
    }
    ```
  </Accordion>

  <Accordion title="Inconsistent Positioning">
    **Problem:** Avatar jumps around between scenes

    **Solution:**

    * Use global avatar config for consistency
    * Only override position when truly needed
    * Keep width consistent across scenes
    * Plan position changes deliberately

    ```json theme={null}
    // Good: Consistent global position
    {
      "avatar": { "position": "bottom-right", "width": "20%" },
      "scenes": [
        { "story": "Scene 1..." },
        { "story": "Scene 2..." }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Avatar Too Large">
    **Problem:** Avatar dominates the frame

    **Solution:**

    * Reduce width to 15-25% for most content
    * Only use 30%+ for presenter-focused videos
    * Consider background importance
    * Test different sizes

    ```json theme={null}
    // Balanced for most content
    { "width": "20%" }

    // Presenter-focused
    { "width": "30%" }
    ```
  </Accordion>
</AccordionGroup>

***

## Advanced Positioning Techniques

### Technique 1: Responsive Positioning by Scene

Adapt avatar position based on background content. Use scene-level `top`/`left` overrides to avoid covering important UI elements:

```javascript theme={null}
const scenes = [
  {
    story: 'Welcome to our product demo.',
    // Uses global avatar position (e.g., bottom-right)
  },
  {
    story: 'Here is the product interface.',
    background: {
      visualUrl: 'https://example.com/interface.jpg',
      type: 'image'
    },
    // Scene-level override: move avatar to avoid covering UI
    avatar: {
      top: '10%',
      left: '5%',
      width: '18%'
    }
  },
  {
    story: 'Now let us look at the features.',
    // Returns to global avatar position
  }
];
```

***

### Technique 2: Brand-Matched Styling

Align avatar styling with brand colors:

```javascript theme={null}
const brandedAvatar = {
  avatar: {
    position: 'bottom-right',
    width: '20%',
    borderRadius: '50',
    borderColor: 'rgba(132,44,254,1)',  // Brand purple
    borderThickness: 4,
    backgroundColor: 'rgba(132,44,254,0.1)'  // Light purple tint
  }
};
```

***

### Technique 3: Dynamic Positioning for Multi-Avatar Effect

Create variety while maintaining consistency:

```javascript theme={null}
const scenes = [
  {
    story: 'Introduction to topic A.',
    avatar: { position: 'bottom-right', width: '20%' }
  },
  {
    story: 'Now for topic B.',
    avatar: { position: 'bottom-left', width: '20%' }
  },
  {
    story: 'Finally, topic C.',
    avatar: { position: 'bottom-right', width: '20%' }
  }
];
```

***

## Quick Reference

### Preset Position Cheat Sheet

```javascript theme={null}
// Most popular positions
const popularPositions = {
  general: { position: 'bottom-right', width: '20%' },
  presenter: { position: 'center-left', width: '25%' },
  vertical: { position: 'top-center', width: '28%' },
  discreet: { position: 'bottom-left', width: '15%' }
};
```

***

### Styling Template

```javascript theme={null}
const stylingTemplate = {
  // Clean, professional
  professional: {
    borderRadius: '100',
    borderColor: 'rgba(185,185,186,1)',
    borderThickness: 2,
    backgroundColor: 'rgba(255,255,255,1)'
  },

  // Modern, colorful
  modern: {
    borderRadius: '50',
    borderColor: 'rgba(132,44,254,1)',
    borderThickness: 4,
    backgroundColor: 'rgba(244,241,246,1)'
  },

  // Minimal, transparent
  minimal: {
    borderRadius: '100',
    borderThickness: 0,
    backgroundColor: 'rgba(255,255,255,0.85)'
  }
};
```

***

## Testing Your Positioning

<Steps>
  <Step title="Create Test Video">
    Generate a short test video with your chosen position
  </Step>

  <Step title="Review on Target Platform">
    View on actual devices (mobile, desktop, TV) where your audience will watch
  </Step>

  <Step title="Check Different Backgrounds">
    Test with various background types (dark, light, busy, simple)
  </Step>

  <Step title="Verify Subtitle Clearance">
    Ensure subtitles do not overlap avatar
  </Step>

  <Step title="Adjust and Iterate">
    Fine-tune position, size, and styling based on results
  </Step>
</Steps>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Scene-Level Customization" icon="sliders" href="/guides/video-with-avatar/scene-level-customization">
    Learn to customize avatars per scene
  </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 documentation
  </Card>

  <Card title="Subtitle Styles" icon="closed-captioning" href="/guides/branding-customization/subtitle-styles">
    Customize subtitle positioning and styling
  </Card>
</CardGroup>