Captions
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:
{
"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. 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:
{
"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
}
}
}
See 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:
{
"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:
{
"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:
{
"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.
{
"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
}
}
}