Aliases let you reference one clip from another using a simple naming system. Instead of manually copying timing values between clips, you can define an alias once and reference it wherever needed. This keeps clips synchronized and simplifies template maintenance.

## Common alias patterns

Before diving into how aliases work, here are solutions to common needs:

### Synchronized overlay

Keep a text overlay perfectly aligned with a video clip, even when the video timing changes:

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "rich-text",
                            "text": "Breaking News"
                        },
                        "start": "alias://main-video",
                        "length": "alias://main-video"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "alias": "main-video",
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4"
                        },
                        "start": 0,
                        "length": "auto"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1280,
            "height": 720
        }
    }
}
```

The text overlay automatically inherits both `start` and `length` from the video. If the video source changes and has a different duration, the overlay stays synchronized without manual updates.

### Auto-generated captions

Generate captions automatically from a video's audio track:

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "caption",
                            "src": "alias://speech"
                        },
                        "start": 0,
                        "length": "end"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "alias": "speech",
                        "asset": {
                            "type": "video",
                            "src": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4"
                        },
                        "start": 0,
                        "length": "auto"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1280,
            "height": 720
        }
    }
}
```

Shotstack transcribes the audio from the aliased clip and generates captions automatically.

## Declaring an alias

Add the `alias` property to any clip to give it a referenceable name:

```json
{
    "alias": "background",
    "asset": {
        "type": "video",
        "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4"
    },
    "start": 0,
    "length": 10
}
```

**Alias naming rules:**

- Use letters, numbers, hyphens, and underscores
- Must be unique within your timeline
- Examples: `main-video`, `intro_clip`, `speech1`

## Referencing an alias

Reference an alias using the `alias://` prefix followed by the alias name:

```text
alias://name
```

You can use alias references in these properties:

| Property | Description |
|----------|-------------|
| `start` | Inherit the start time from the referenced clip |
| `length` | Inherit the length from the referenced clip |
| `src` (caption asset) | Generate captions from the referenced clip's audio |

### Referencing start

Use `alias://name` in the `start` property to synchronize when a clip begins:

```json
{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/logos/logo.png"
    },
    "start": "alias://main-video",
    "length": 3
}
```

The image appears at the exact moment the `main-video` clip starts.

### Referencing length

Use `alias://name` in the `length` property to match another clip's duration:

```json
{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/overlay.png"
    },
    "start": 0,
    "length": "alias://background"
}
```

The image stays visible for exactly as long as the `background` clip plays.

### Referencing both

Combine both references to perfectly synchronize two clips:

```json
{
    "asset": {
        "type": "html",
        "html": "<div class='watermark'>PREVIEW</div>"
    },
    "start": "alias://main-video",
    "length": "alias://main-video"
}
```

The watermark appears and disappears with the main video, regardless of when or how long it plays.

### Referencing for captions

Use `alias://name` in a caption asset's `src` property to auto-generate captions:

```json
{
    "asset": {
        "type": "caption",
        "src": "alias://narrator"
    },
    "start": 0,
    "length": "end"
}
```

Shotstack extracts audio from the `narrator` clip, transcribes it, and generates timed captions automatically.

:::info
Auto-captioning works with `audio`, `video`, and `text-to-speech` clips. The language is detected automatically.
:::

## Working with auto and end

Alias references resolve after `auto` and `end` values are calculated. This means you can reference clips that use these keywords:

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "rich-text",
                            "text": "Overlay"
                        },
                        "start": "alias://video",
                        "length": "alias://video"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "alias": "video",
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4"
                        },
                        "start": 0,
                        "length": "auto"
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1280,
            "height": 720
        }
    }
}
```

The video's `auto` length is resolved first (based on its actual duration), then the text overlay inherits that calculated value.

## Dependency chains

Aliases can reference other clips that also use alias references, creating a dependency chain:

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": { "type": "rich-text", "text": "Title" },
                        "start": "alias://overlay",
                        "length": "alias://overlay"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "alias": "overlay",
                        "asset": { "type": "image", "src": "https://shotstack-assets.s3.amazonaws.com/images/woods1.jpg" },
                        "start": "alias://base",
                        "length": "alias://base",
                        "scale": 0.25
                    }
                ]
            },
            {
                "clips": [
                    {
                        "alias": "base",
                        "asset": { "type": "video", "src": "https://shotstack-assets.s3.amazonaws.com/footage/beach.mp4" },
                        "start": 0,
                        "length": 10
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1280,
            "height": 720
        }
    }
}
```

Shotstack resolves these in the correct order: `base` first, then `overlay`, then the text clip.

:::warning
Circular references are not allowed. If clip A references clip B and clip B references clip A, the render will fail with an error.
:::

## Related topics

- [Captions](/docs/guide/architecting-an-application/captions) - Style and customize auto-generated captions
- [Merging data](/docs/guide/architecting-an-application/merging-data) - Use merge fields for dynamic templates