Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 122 Β· Images and Media

Captions and Subtitles

Add captions and subtitles to video with the track element and WebVTT files. Learn kind, srclang, label and default, cue timing, settings and styling.

Millions of people watch video without sound: people who are deaf or hard of hearing, people in a quiet library or a noisy train, people watching in a language they are still learning. For all of them, text on the screen is what makes a video understandable.

HTML adds timed text to a <video> with the <track> element, and the text itself lives in a simple file format called WebVTT. In this lesson you will learn the different kinds of tracks, write your own WebVTT file, position and style the text, and read cues from JavaScript.

Captions, subtitles and friends

These words are often used interchangeably, but HTML distinguishes them. Each <track> has a kind that says what its text is for:

kind For whom Contains
captions Viewers who cannot hear the audio The dialogue plus important sounds and speaker names: [door slams], [soft music]
subtitles Viewers who can hear but do not understand the language A translation of the dialogue only
descriptions Viewers who cannot see the video Text descriptions of what happens on screen, meant to be read aloud
chapters Everyone Titles for sections of the video, for navigation
metadata Scripts Data for JavaScript; never shown to the viewer

If you leave kind out, the browser assumes subtitles. Browsers display captions and subtitles on top of the video and list them in the player's CC menu. Built-in support for presenting descriptions and chapters is very limited, so those are mostly used by custom players through JavaScript.

Closed vs. open captions. Text added with <track> is closed: viewers can switch it on or off, and it stays real text that can be resized, restyled and searched. Text burned into the video pixels is open: always visible, impossible to turn off, translate or enlarge. Prefer closed captions.

The <track> element

<track> is a void element placed inside <video> (or <audio>), after the <source> elements:

HTML
<video controls width="640" height="360">
  <source src="/samples/media/fractal.webm" type="video/webm">
  <source src="/samples/media/fractal.mp4" type="video/mp4">
  <track kind="captions" src="/captions/fractal.en.vtt" srclang="en" label="English" default>
  <track kind="subtitles" src="/captions/fractal.es.vtt" srclang="es" label="EspaΓ±ol">
</video>
  • src β€” the URL of the WebVTT file.
  • kind β€” one of the values from the table above.
  • srclang β€” the language of the text, such as en or es. It is required for subtitles.
  • label β€” the name shown in the player's menu. Write each label in its own language ("EspaΓ±ol", not "Spanish"), so people can find theirs.
  • default β€” turns this track on automatically. Use it on at most one caption or subtitle track.

The viewer can switch tracks from the player's controls. Browsers may also pick a track that matches the viewer's language or accessibility settings.

Tracks from another origin need CORS. A caption file on a different domain loads only if the <video> has a crossorigin attribute and the caption server sends an Access-Control-Allow-Origin header. With crossorigin set, the video files must allow CORS too. Hosting captions on the same site as the page avoids all of this.

That CORS rule matters for the examples below. The live editor runs your code in a locked-down sandbox that counts as a different origin, so instead of fetching the .vtt files, each example includes the WebVTT text right in the page and a two-line script turns it into a data: URL. On your own site, the src attribute alone is all you need.

Captions and subtitles

Compare the two tracks. The English captions include the sound cues in square brackets, because a deaf viewer would otherwise miss them. The Spanish subtitles translate only the words, because their viewers can hear the tone themselves.

Writing WebVTT

WebVTT (Web Video Text Tracks) is a plain-text format. Save it as UTF-8 with the extension .vtt and serve it with the MIME type text/vtt. A file looks like this:

TEXT
WEBVTT

NOTE Captions for the trailer. Last checked in October.

intro
00:00:00.000 --> 00:00:03.000
Welcome to the Night Market.

00:00:03.500 --> 00:00:07.250
<v Lena>Try the dumplings first.</v>
<v Omar>No, the noodles!</v>

The rules:

  • The file must start with WEBVTT.
  • Blocks are separated by one blank line. Each caption block is called a cue.
  • A cue may start with an optional identifier line (intro above), useful for scripts and styling.
  • The timing line has a start and end time separated by -->. Times are hours:minutes:seconds.milliseconds; the hours part is optional, so 00:03.500 is fine. Milliseconds need exactly three digits after a period, not a comma.
  • The lines after the timing are the cue text, shown together. Keep it to one or two short lines.
  • NOTE starts a comment that viewers never see.
  • Write &amp;, &lt; and &gt; for &, < and > in cue text, just like entities in HTML.

Coming from SRT? The older SubRip (.srt) format looks very similar but uses commas in timestamps (00:00:03,500) and numbered cues. Browsers do not play SRT directly; convert it by adding the WEBVTT header and changing the commas to periods.

Tags inside cues

Cue text can contain a small set of tags:

Tag Meaning
<v Name>…</v> A voice: who is speaking. Great for captions with several speakers.
<i>, <b>, <u> Italic, bold, underline. Italic is a common convention for off-screen voices and song lyrics.
<c.classname>…</c> A span with a class, for styling.
<lang fr>…</lang> Text in a different language.

Cue settings

After the end time, you can add settings that position the cue:

Setting Example Effect
line line:0 or line:10% Vertical position. Line 0 is the top; negative numbers count from the bottom.
position position:20% Horizontal position of the cue box.
size size:50% Width of the cue box.
align align:start Text alignment: start, center, end, left or right.
vertical vertical:rl Vertical text, for languages such as Japanese.

Move captions to the top when something important is happening at the bottom of the frame, such as on-screen text.

Edit the WebVTT in this example β€” change the words, the times, the speakers or the settings β€” and press play again:

Write your own WebVTT

Notice that the first two cues overlap in time, so both appear at once: the sound description at the top (line:0) and Mira's line at the bottom.

Styling captions with ::cue

The ::cue pseudo-element in your page's CSS styles the text of all cues. ::cue(selector) targets parts of them: voices with v[voice="Name"], classes from <c.name>, or tags such as b and i. Only a limited set of properties applies β€” mainly color, background, font properties, text-decoration, text-shadow, outline and opacity.

Style gently. Many viewers set their preferred caption size and colors in their operating system or browser, and those settings usually take priority over yours. Readable contrast and a solid background matter more than branding.

Text tracks in JavaScript

Each track is exposed as a TextTrack object through video.textTracks. Its mode is one of:

  • "showing" β€” cues are loaded and displayed.
  • "hidden" β€” cues are loaded and events fire, but nothing is displayed.
  • "disabled" β€” the track is off and not loaded.

With mode = "hidden", you can show cues anywhere you like. The cuechange event fires whenever the active cues change:

Captions outside the video

The same technique powers interactive transcripts, where every cue is listed on the page and the current one is highlighted. You can also create cues entirely in script with video.addTextTrack() and new VTTCue(start, end, text).

Good captioning habits

  • Caption everything that carries meaning: dialogue, speaker changes, music that sets the mood, and sounds that matter to the story.
  • Keep cues short and in sync. Aim for one or two lines, shown long enough to read comfortably.
  • Do not trust raw auto-generated captions. Speech recognition is a good first draft, but names, numbers and technical terms need a human check.
  • Offer a transcript as well. It helps people who use screen readers, people who prefer reading, and search engines. For audio-only content such as podcasts, a transcript is the main text alternative.

You will find more on making media accessible in Accessibility Basics.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. Which kind of track includes sound effects such as "[door slams]"?

    Captions are for viewers who cannot hear the audio, so they include meaningful sounds and speaker names. Subtitles translate only the dialogue.
  2. 2. Which line is a valid WebVTT timing line?

    WebVTT uses a period before the milliseconds, and the hours part is optional. Commas are the older SRT format.
  3. 3. What must the very first line of a WebVTT file be?

    Every WebVTT file starts with the word WEBVTT, followed by a blank line before the first cue.
  4. 4. You want to display the current cue in your own element below the video, not on top of it. What mode should the track have?

    In hidden mode the cues are loaded and cuechange fires, but the browser does not draw them over the video.
  5. 5. What does the default attribute on a track do?

    default enables the track from the start. Viewers can still switch it off or choose another one.

Summary

  • <track> adds timed text to <video>; kind can be captions, subtitles, descriptions, chapters or metadata.
  • Captions include important sounds and speakers for viewers who cannot hear; subtitles translate dialogue.
  • srclang sets the language, label names the track in the menu, and default turns one on automatically.
  • WebVTT files start with WEBVTT; cues are separated by blank lines and timed as mm:ss.ttt --> mm:ss.ttt.
  • Cue tags (<v>, <c>, <i>) and settings (line, position, align, size) control content and placement; ::cue styles them.
  • Caption files from another origin need CORS and the crossorigin attribute.
  • textTracks, mode and cuechange let you build custom caption displays and transcripts.

Next up: putting whole web pages inside your page with Iframes.