:::info
The [Rich Captions](/docs/guide/architecting-an-application/rich-captions) asset is the successor to the caption asset, adding word-level animations (karaoke, bounce, pop, and more), active word highlighting, and the full set of rich-text styling options.
:::

You can add captions to your video using the caption asset. Captions can can be created automatically or included manually
by referencing a link to an SRT or VTT file. The caption asset provides for a range of styling options.

### Manual Captions

You can add captions with simple styling to your video by referencing an `srt` or `vtt` file:

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

### Automatic Captions

You can automatically generate captions based on audio clips used elsewhere in your edit by referencing the clip through its [alias](/docs/guide/architecting-an-application/aliases). Shotstack will automatically detect the language.

To auto-generate captions, assign an `alias` to your audio or video clip, then reference it in the caption's `src` property using the `alias://` prefix:

```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
        }
    }
}
```

:::info
See [Aliases](/docs/guide/architecting-an-application/aliases) for more details on declaring and referencing aliases.
:::

### Caption Styling

You can customize your captions with various styling options, including custom fonts, positioning, and text formatting. 
These options allow you to create captions that match your video’s design and give them a distinctive look.

#### Using a custom font

You can use a custom font by referencing it in the `family` attribute of the `font` property. You can further style
the caption by adjusting the `color`, `size` and `lineHeight` attribute:

<video playsinline controls width="75%">
    <source src="https://d1uej6xx5jo4cd.cloudfront.net/docs-captions/captions-custom-font.mp4" type="video/mp4" />
</video>

```json
{
    "timeline": {
        "fonts": [
            {
                "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/LilitaOne-Regular.ttf"
            }
        ],
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "caption",
                            "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
                            "font": {
                                "color": "#c0392b",
                                "family": "Lilita One",
                                "lineHeight": 1,
                                "size": 20
                            }
                        },
                        "start": 0,
                        "length": "end"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "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
        }
    }
}
```

#### Adding stroke

You can add a stroke to your captions by adding the `stroke` and `strokeWidth` to the `font` property:

<video playsinline controls width="75%">
    <source src="https://d1uej6xx5jo4cd.cloudfront.net/docs-captions/captions-stroke.mp4" type="video/mp4" />
</video>

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "caption",
                            "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
                            "font": {
                                "stroke": "#000000",
                                "strokeWidth": 0.5
                            }
                        },
                        "start": 0,
                        "length": "end"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "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
        }
    }
}
```

#### Add a background

You can add a background to your captions and set the padding, border radius, color, and opacity:

<video playsinline controls width="75%">
    <source src="https://d1uej6xx5jo4cd.cloudfront.net/docs-captions/captions-background.mp4" type="video/mp4" />
</video>

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "caption",
                            "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
                            "background": {
                                "color": "#000000",
                                "padding": 20,
                                "borderRadius": 18,
                                "opacity": 0.6
                            }
                        },
                        "start": 0,
                        "length": "end"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "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
        }
    }
}
```

#### Using custom positioning and dimensions

You can set the position of the captions within the video using the `offset` and `position` property, and use `width` and `height`
to change the dimensions of container holding the captions.

<video playsinline controls width="75%">
    <source src="https://d1uej6xx5jo4cd.cloudfront.net/docs-captions/captions-position-dimensions.mp4" type="video/mp4" />
</video>

```json
{
    "timeline": {
        "background": "#FFFFFF",
        "tracks": [
            {
                "clips": [
                    {
                        "length": "end",
                        "asset": {
                            "type": "caption",
                            "src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
                            "width": 500,
                            "font": {
                                "family": "Montserrat ExtraBold",
                                "size": "50",
                                "lineHeight": 1
                            },
                            "alignment": {
                                "horizontal": "left"
                            }
                        },
                        "offset": {
                            "x": 0.1,
                            "y": 0.1
                        },
                        "start": 0,
                        "position": "left"
                    }
                ]
            },
            {
                "clips": [
                    {
                        "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
        }
    }
}
```