Aliases
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:
{
"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:
{
"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:
{
"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:
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:
{
"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:
{
"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:
{
"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:
{
"asset": {
"type": "caption",
"src": "alias://narrator"
},
"start": 0,
"length": "end"
}
Shotstack extracts audio from the narrator clip, transcribes it, and generates timed captions automatically.
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:
{
"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:
{
"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.
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 - Style and customize auto-generated captions
- Merging data - Use merge fields for dynamic templates