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 try to detect the language used.
Declaring an alias
To assign an alias to a clip, set the alias property like this:
{
"alias": "speech",
"asset": {
"type": "video",
"src": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4"
},
"start": 0,
"length": 25.9
}
Only audio, video and text-to-speech clips allow an alias to be set.
Referencing an alias
You can reference the alias by adding it directly into the src property of your caption asset:
{
"clips": [
{
"asset": {
"type": "caption",
"src": "alias://speech"
},
"start": 0,
"length": "end"
}
]
},
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 margins
You can set the margins of the captions to position them anywhere within the video:
{
"timeline": {
"fonts": [
{
"src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/Montserrat-ExtraBold.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "caption",
"src": "https://shotstack-assets.s3.amazonaws.com/captions/transcript.srt",
"font": {
"color": "#ffffff",
"family": "Montserrat ExtraBold",
"size": 30,
"lineHeight": 0.8
},
"margin": {
"top": 0.25,
"left": 0.05,
"right": 0.45
}
},
"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
}
}
}