Contents
Open captions are part of the picture. Closed captions are a separate text file that the player shows on top of the video. The words are the same in both, but where the words live changes who can read them and how you fix a mistake.
This guide explains open captions vs closed captions, when to use each, and how to make both from a single transcript. The script uses Python and Shotstack’s video editing API. It transcribes a video once, saves a caption file, and renders a second video with the same captions burned in.
TL;DR
- Open captions are drawn into the video frames. Every viewer sees them, on every player, and they can’t be turned off.
- Closed captions are a separate file, usually SRT or VTT. The viewer turns them on or off, and the player decides how they look.
- You don’t have to choose. One transcript can give you both.
- The script below made an 11 cue VTT file and a 26 second video with those captions burned in, from one source video.
- Fix names and spelling in the caption file first, then burn that file into the video.
What is the difference between open and closed captions?
The W3C’s guide to captions and subtitles describes the two kinds in one line each. Closed captions “can be hidden or shown by people watching the video.” Open captions “are always displayed and cannot be turned off.”
Open captions are also called burned-in or hardcoded captions, because the text becomes pixels in the video.
| Open captions | Closed captions | |
|---|---|---|
| Where the text lives | In the video frames | In a separate file next to the video |
| Who controls them | You do. They are always on | The viewer turns them on or off |
| Where they work | Anywhere the video plays | In players and platforms that read caption files |
| How they look | Your font, size, color and position | The player’s caption style |
| How you fix a typo | Edit the text and render the video again | Edit the text file |
Captions vs subtitles
The two words are often used for the same thing. The W3C guide separates them this way: “Captions for the same language as the spoken audio” and “Subtitles for spoken audio translated into another language.”
Either one can be open or closed. This guide says captions for both.
When to use open or closed captions
In a Preply survey of more than 1,200 Americans, 50% said they watch content with subtitles most of the time.
Use open captions when:
- The video plays where you can’t attach a file. Some places play the video file and nothing else, such as messaging apps and digital signs.
- Viewers start with the sound off. Burned-in text shows without anyone pressing a button.
- The look of the text is part of the design. You choose the font, the size and the position.
Use closed captions when:
- Viewers should have the choice. They can turn the text on or off in the player.
- The text may change. You can correct a caption file without touching the video.
- You publish in several languages. One video can carry a caption file for each language.
You may need both: a clean video with a caption file for your own site, and a burned-in copy for social posts.
Make open and closed captions with Python
The script below does both jobs for one video:
- It sends the video’s URL to the Ingest API, which transcribes the speech and returns a caption file. That file is your closed captions.
- It sends the video and the caption file to the Edit API, which draws the captions onto the video. That render is your open captions.
The source is a 26 second clip of a person talking to the camera, hosted by Shotstack.
The script uses only the Python standard library. Set SHOTSTACK_API_KEY to the API key from your Shotstack dashboard, then run it with Python 3. Each render uses credits from your plan, as listed on the pricing page.
import json
import os
import sys
import time
import urllib.error
import urllib.request
EDIT = "https://api.shotstack.io/edit/v1"
INGEST = "https://api.shotstack.io/ingest/v1"
SOURCE = "https://shotstack-assets.s3.amazonaws.com/footage/scott-ko.mp4"
CAPTION_FORMAT = "vtt" # "vtt" or "srt"
def call(url, body=None):
data = json.dumps(body).encode() if body is not None else None
headers = {
"x-api-key": os.environ["SHOTSTACK_API_KEY"],
"Content-Type": "application/json",
}
try:
request = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(request) as response:
return json.load(response)
except urllib.error.HTTPError as error:
sys.exit(f"HTTP {error.code}: {' '.join(error.read().decode().split())[:300]}")
def transcribe(video_url):
"""Closed captions: ask the Ingest API for a caption file and return its URL."""
body = {"url": video_url, "outputs": {"transcription": {"format": CAPTION_FORMAT}}}
source_id = call(f"{INGEST}/sources", body)["data"]["id"]
print("Transcription queued:", source_id)
while True:
time.sleep(5)
source = call(f"{INGEST}/sources/{source_id}")["data"]["attributes"]
transcription = source["outputs"]["transcription"]
if transcription["status"] == "ready":
return transcription["url"]
if "failed" in (source["status"], transcription["status"]):
sys.exit(f"Transcription failed for source {source_id}")
def build_edit(video_url, caption_url):
"""Open captions: draw the caption file on top of the video."""
captions = {
"type": "rich-caption",
"src": caption_url,
"font": {"family": "Roboto", "size": 44, "color": "#ffffff"},
"stroke": {"width": 3, "color": "#000000"},
"align": {"vertical": "bottom"},
}
caption_clip = {
"asset": captions,
"start": 0,
"length": "end",
"width": 1000,
"height": 160,
"position": "bottom",
"offset": {"y": 0.06},
}
video_clip = {
"asset": {"type": "video", "src": video_url},
"start": 0,
"length": "auto",
}
return {
"timeline": {"tracks": [{"clips": [caption_clip]}, {"clips": [video_clip]}]},
"output": {"format": "mp4", "resolution": "hd"},
}
def render(edit):
render_id = call(f"{EDIT}/render", edit)["response"]["id"]
print("Render queued:", render_id)
while True:
time.sleep(5)
status = call(f"{EDIT}/render/{render_id}")["response"]
if status["status"] == "done":
return status["url"]
if status["status"] == "failed":
sys.exit(f"Render failed: {status.get('error')}")
if __name__ == "__main__":
if not os.environ.get("SHOTSTACK_API_KEY"):
sys.exit("Set SHOTSTACK_API_KEY first.")
caption_url = transcribe(SOURCE)
filename = f"captions.{CAPTION_FORMAT}"
urllib.request.urlretrieve(caption_url, filename)
with open(filename, encoding="utf-8") as file:
cues = file.read().count("-->")
print(f"Closed captions: {filename}, {cues} cues")
print("Open captions:", render(build_edit(SOURCE, caption_url)))Run python captions.py. It saves the caption file in the current folder and prints the URL of the captioned video:
Transcription queued: zzz01m7g-skmfx-kg936-fgv1m-b14dpe
Closed captions: captions.vtt, 11 cues
Render queued: 76529210-404e-4193-93a1-ff570a4e2a0e
Open captions: https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/76529210-404e-4193-93a1-ff570a4e2a0e.mp4This is the start of captions.vtt:
WEBVTT
1
00:00:00.630 --> 00:00:00.900
Hi,
2
00:00:00.990 --> 00:00:02.009
my name's Scott Coe.
3
00:00:02.310 --> 00:00:03.110
As an entrepreneur,And this is the video with the same captions burned in:
How the script works
transcribe()posts the video’s URL to the Ingest API and asks for atranscriptionoutput in the format set byCAPTION_FORMAT. It checks the source every five seconds until the transcription isready, then returns the URL of the caption file.- The main block downloads that file as
captions.vttand counts its cues. build_edit()makes a two track edit. The top track holds arich-captionasset whosesrcis the caption file. The bottom track holds the video.- The caption clip is a box 1,000 pixels wide and 160 pixels high.
positionandoffsetplace it near the bottom of the frame. "length": "auto"makes the video clip as long as the source file."length": "end"keeps the captions on screen until the end of the timeline.render()posts the edit and checks the render every five seconds until it is done.
Set CAPTION_FORMAT to "srt" to get an SRT file. We ran the script both ways. Each file had 11 cues, and both renders showed the same captions in the same place.
Use the caption file as closed captions
On your own web page, the browser’s video player reads the caption file through a <track> element:
<video controls src="video.mp4">
<track kind="captions" src="captions.vtt" srclang="en" label="English" default>
</video>Use the VTT file here. The MDN reference for the track element says: “The tracks are formatted in WebVTT format (.vtt files)”.
Video platforms that support closed captions take the file as an upload next to the video. YouTube’s list of supported subtitle and closed caption files includes both SubRip (.srt) and WebVTT (.vtt).
Our guide on how to generate SRT and VTT subtitles with an API covers the transcription request in more detail.
Fix the text before you burn it in
A caption file is plain text, so you can correct it in any editor. Open captions can’t be edited after the render, so check the file first.
Check names first. The speaker in the sample clip is Scott Ko, and the second cue of our file reads “my name’s Scott Coe.” The fix takes three steps:
- Open
captions.vttand correct the text. Leave the times as they are. - Put the corrected file at a public URL.
- Pass that URL to
build_edit()ascaption_urland render again.
Your closed captions and your open captions now come from the same corrected file.
Style the burned-in captions
The script sets three things on the caption asset: a white font in Roboto at size 44, a black stroke around the letters, and align to keep the text at the bottom of its box. Change those values to match your brand.
The same asset can also color the words as they are spoken. Add an animation with a style, such as karaoke or highlight, and an active font color. In our test with a caption file and the karaoke style, the color moved across each line while its cue was on screen. The rich captions guide lists all eight animation styles.
Our guide on how to burn subtitles and captions into a video walks through fonts, backgrounds and positions.
Make both kinds of captions with Shotstack
You now know the difference between open captions and closed captions, and you have a script that makes both from one transcript. Put your own video URL in SOURCE and run it again. You get a caption file for players that support one and a burned-in video for everywhere else.
Create a free Shotstack account to get your API key and caption your first video.
Frequently asked questions (FAQs)
Can I burn captions in without making a caption file first?
Yes. Give the video clip an alias, then set the caption asset’s src to alias:// followed by that name. The render transcribes the clip and draws the captions in one request. The rich captions guide shows the full edit.
Should I use SRT or VTT?
Use VTT for a web page, because the browser’s <track> element reads WebVTT. Use SRT when an upload form asks for it. The two files hold the same cues. The visible difference is the first line, WEBVTT, and a period where SRT has a comma in each time.
What should closed captions include besides speech?
Sounds that matter to the story. MDN describes captions as a “transcription or translation of the dialog, sound effects, relevant musical cues, and other relevant audio information”. A transcript of the speech is the starting point. Add lines such as [door slams] by hand where a viewer needs them.
Can one video have captions in several languages?
With closed captions, yes: add one caption file per language, each in its own <track> element with its own srclang. With open captions, render one video per language. Our guide to a video localization API covers translated versions.