WebVTT API

Web Video Text Tracks ( WebVTT ) are text tracks providing specific text "cues" that are time-aligned with other media, such as video or audio tracks. The WebVTT API provides functionality to define and manipulate these text tracks. The WebVTT API is primarily used for displaying subtitles or captions that overlay with video content, but it has other uses: providing chapter information for easier navigation and generic metadata that needs to be time-aligned with audio or video content.

Concepts and usage

A text track is a container for time-aligned text data that can be played in parallel with a video or audio track to provide a translation, transcription, or overview of the content. A video or audio media element may define tracks of different kinds or in different languages, allowing users to display appropriate tracks based on their preferences or needs.

The different kinds of text data that can be specified are listed below. Note that browsers do not necessarily support all kinds of text tracks.


           subtitles

provide a textual translation of spoken dialog. This is the default type of text track, and if used, the source language must be specified.


           captions

provide a transcription of spoken text, and may include information about other audio such as music or background noise. They are intended for hearing impaired users.


           chapters

provide high level navigation information, allowing users to more easily switch to relevant content.


           metadata

is used for any other kinds of time-aligned information.

The individual time-aligned units of text data within a track are referred to as "cues". Each cue has a start time, end time, and textual payload. It may also have "cue settings", which affect its display region, position, alignment, and/or size. Lastly, a cue may have a label, which can be used to select it for CSS styling.

A text track and cues can be defined in a file using the WebVTT File Format , and then associated with a particular <video> element using the <track> element.

Alternatively you can add a TextTrack to a media element in JavaScript using HTMLMediaElement.addTextTrack() , and then add individual VTTCue objects to the track with TextTrack.addCue() .

The ::cue CSS pseudo-element can be used both in HTML and in a WebVTT file to style the cues for a particular element, for a particular tag within a cue, for a VTT class, or for a cue with a particular label. The ::cue-region pseudo-element is intended for styling cues in a particular region, but is not supported in any browser.

Most important WebVTT features can be accessed using either the file format or Web API.

Interfaces

VTTCue
VTTRegion
TextTrack
TextTrackCue
TextTrackCueList
TextTrackList

Related interfaces

TrackEvent

Related CSS extensions

These CSS pseudo-element are used to style cues in media with VTT tracks.


            ::cue

Matches cues within a selected element in media with VTT tracks.

Note: The specification defines another pseudo-element, ::cue-region , but this is not supported by any browsers.

Examples

Using the WebVTT API to add captions

HTML

The following example adds a new TextTrack to the video, then adds cues using TextTrack.addCue() method calls, with constructed VTTCue objects as arguments.

html

<video controls src="/shared-assets/videos/friday.mp4"></video>
css
video {
  width: 420px;
  height: 300px;
JavaScript
js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(new VTTCue(1.5, 2.9, "Tell me, is the lord of the universe in?"));
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(new VTTCue(4.3, 6, "Somebody must've stolen the crown jewels"));
console.log(track.cues);
Result
&lt;/div&gt;&lt;/div&gt;&lt;/section&gt;&lt;section aria-labelledby="displaying_vtt_content_defined_in_a_file"&gt;&lt;h3 id="displaying_vtt_content_defined_in_a_file"&gt;&lt;a href="#displaying_vtt_content_defined_in_a_file"&gt;Displaying VTT content defined in a file&lt;/a&gt;&lt;/h3&gt;&lt;div class="section-content"&gt;&lt;p&gt;This example demonstrates how to add the same set of captions to the video seen in the above &lt;a href="#using_the_webvtt_api_to_add_captions"&gt;Using the WebVTT API to add captions&lt;/a&gt; example. This time, however, we will do it declaratively using a &lt;a href="/en-US/docs/Web/HTML/Reference/Elements/track"&gt;&lt;code&gt;&amp;lt;track&amp;gt;&lt;/code&gt;&lt;/a&gt; element.&lt;/p&gt;
&lt;p&gt;First, let's define the captions inside a "captions.vtt" file:&lt;/p&gt;
&lt;pre class="brush: plain notranslate"&gt;WEBVTT
00:00.000 --&amp;gt; 00:00.900
Hildy!
00:01.000 --&amp;gt; 00:01.400
How are you?
00:01.500 --&amp;gt; 00:02.900
Tell me, is the lord of the universe in?
00:03.000 --&amp;gt; 00:04.200
Yes, he's in - in a bad humor
00:04.300 --&amp;gt; 00:06.000
Somebody must've stolen the crown jewels
&lt;p&gt;We can then add this to a &lt;a href="/en-US/docs/Web/HTML/Reference/Elements/video"&gt;&lt;code&gt;&amp;lt;video&amp;gt;&lt;/code&gt;&lt;/a&gt; element using the &lt;a href="/en-US/docs/Web/HTML/Reference/Elements/track"&gt;&lt;code&gt;&amp;lt;track&amp;gt;&lt;/code&gt;&lt;/a&gt; element.
The following HTML would result in the same text track as the previous example:&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;html&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: html notranslate"&gt;&lt;code&gt;&amp;lt;video controls src="video.webm"&amp;gt;
  &amp;lt;track default kind="captions" src="captions.vtt" srclang="en" /&amp;gt;
&amp;lt;/video&amp;gt;
&lt;p&gt;We can add multiple &lt;a href="/en-US/docs/Web/HTML/Reference/Elements/track"&gt;&lt;code&gt;&amp;lt;track&amp;gt;&lt;/code&gt;&lt;/a&gt; elements to specify different kinds of tracks in multiple languages, using the &lt;code&gt;kind&lt;/code&gt; and &lt;code&gt;srclang&lt;/code&gt; attributes. Note that, if &lt;code&gt;kind&lt;/code&gt; is specified, &lt;code&gt;srclang&lt;/code&gt; &lt;em&gt;must&lt;/em&gt; be set too.
The &lt;code&gt;default&lt;/code&gt; attribute may be added to just one &lt;code&gt;&amp;lt;track&amp;gt;&lt;/code&gt;: this is the one that will be played if user preferences don't specify a particular language or kind.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;html&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: html notranslate"&gt;&lt;code&gt;&amp;lt;video controls src="video.webm"&amp;gt;
  &amp;lt;track default kind="captions" src="captions.vtt" srclang="en" /&amp;gt;
  &amp;lt;track kind="subtitles" src="subtitles.vtt" srclang="en" /&amp;gt;
  &amp;lt;track kind="descriptions" src="descriptions.vtt" srclang="en" /&amp;gt;
  &amp;lt;track kind="chapters" src="chapters_de.vtt" srclang="de" /&amp;gt;
  &amp;lt;track kind="subtitles" src="subtitles_en.vtt" srclang="en" /&amp;gt;
&amp;lt;/video&amp;gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;&lt;/section&gt;&lt;section aria-labelledby="styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;h3 id="styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;a href="#styling_webvtt_in_html_or_a_stylesheet"&gt;Styling WebVTT in HTML or a stylesheet&lt;/a&gt;&lt;/h3&gt;&lt;div class="section-content"&gt;&lt;p&gt;You can style WebVTT cues by matching elements using the &lt;a href="/en-US/docs/Web/CSS/::cue"&gt;&lt;code&gt;::cue&lt;/code&gt;&lt;/a&gt; pseudo-element.
This allows you to modify the appearance of all cue text, or just specific elements. In this example, we'll add some styling to the &lt;a href="#using_the_webvtt_api_to_add_captions"&gt;first example above&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Note:&lt;/strong&gt;
It is also possible to define styles in the &lt;a href="/en-US/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format"&gt;WebVTT File Format&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The HTML for the video itself is the same as we saw previously:&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;pre class="brush: css hidden notranslate live-sample---styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;code&gt;video {
  width: 420px;
  height: 300px;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;html&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: html notranslate live-sample---styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;code&gt;&amp;lt;video controls src="/shared-assets/videos/friday.mp4"&amp;gt;&amp;lt;/video&amp;gt;
&lt;p&gt;First, we use the &lt;a href="/en-US/docs/Web/CSS/::cue"&gt;&lt;code&gt;::cue&lt;/code&gt;&lt;/a&gt; pseudo-element to select all video text cues, giving them larger red and a gradient background.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;code&gt;video::cue {
  font-size: 1.5rem;
  background-image: linear-gradient(to bottom, yellow, lightyellow);
  color: red;
&lt;p&gt;We then use &lt;a href="/en-US/docs/Web/CSS/::cue"&gt;&lt;code&gt;::cue&lt;/code&gt;&lt;/a&gt; to select text that has been marked up using the &lt;code&gt;u&lt;/code&gt; and &lt;code&gt;b&lt;/code&gt; elements and style them green and yellow, respectively.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;code&gt;video::cue(u) {
  color: green;
video::cue(b) {
  color: purple;
&lt;h4 id="javascript_2"&gt;JavaScript&lt;/h4&gt;
&lt;p&gt;The JavaScript is the same as in the first example, except that we have marked up some of the cue text using &lt;code&gt;&amp;lt;b&amp;gt;&lt;/code&gt; (bold) and &lt;code&gt;&amp;lt;u&amp;gt;&lt;/code&gt; (underline) tags.
By default the marked text would be displayed as bold or underlined (depending on the tag) but we have used the &lt;a href="/en-US/docs/Web/CSS/::cue"&gt;&lt;code&gt;::cue&lt;/code&gt;&lt;/a&gt; in the previous section to also style the text to be green and purple, respectively.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;js&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: js notranslate live-sample---styling_webvtt_in_html_or_a_stylesheet"&gt;&lt;code&gt;let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(
  new VTTCue(1.5, 2.9, "Tell me, is the &amp;lt;u&amp;gt;lord of the universe&amp;lt;/u&amp;gt; in?"),
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(
  new VTTCue(4.3, 6, "Somebody must've &amp;lt;b&amp;gt;stolen&amp;lt;/b&amp;gt; the crown jewels"),
console.log(track.cues);
&lt;h4 id="result_2"&gt;Result&lt;/h4&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"/&gt;&lt;iframe class="sample-code-frame" title="Styling WebVTT in HTML or a stylesheet sample" id="frame_styling_webvtt_in_html_or_a_stylesheet" width="400" height="330" src="about:blank" data-live-path="/en-US/docs/Web/API/WebVTT_API/" data-live-id="styling_webvtt_in_html_or_a_stylesheet" sandbox="allow-same-origin allow-scripts" loading="lazy"/&gt;&lt;/div&gt;&lt;/div&gt;&lt;/section&gt;&lt;section aria-labelledby="more_cue_styling_examples"&gt;&lt;h3 id="more_cue_styling_examples"&gt;&lt;a href="#more_cue_styling_examples"&gt;More cue styling examples&lt;/a&gt;&lt;/h3&gt;&lt;div class="section-content"&gt;&lt;p&gt;This example shows more examples of how you can mark up cue text with tags and then style them.
The same markup and styles can be used in the &lt;a href="/en-US/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format"&gt;WebVTT File Format&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The HTML and CSS for displaying the video itself is the same as for the &lt;a href="#using_the_webvtt_api_to_add_captions"&gt;first example above&lt;/a&gt; so here we only show the specific code for marking up and styling the text.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;pre class="brush: css hidden notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video {
  width: 420px;
  height: 300px;
&lt;div class="code-example"&gt;&lt;pre class="brush: html hidden notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;&amp;lt;video controls src="/shared-assets/videos/friday.mp4"&amp;gt;&amp;lt;/video&amp;gt;
&lt;h4 id="styling_by_tag_type"&gt;Styling by tag type&lt;/h4&gt;
&lt;p&gt;The first cue we create will be displayed for all 6 seconds of the video and display text marked up with &lt;code&gt;b&lt;/code&gt;, &lt;code&gt;u&lt;/code&gt;, &lt;code&gt;i&lt;/code&gt; and &lt;code&gt;c&lt;/code&gt; tags.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;js&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: js notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(
  new VTTCue(
    "Styles: Normal &amp;lt;b&amp;gt;bold&amp;lt;/b&amp;gt; &amp;lt;u&amp;gt;underlined&amp;lt;/u&amp;gt; &amp;lt;i&amp;gt;italic&amp;lt;/i&amp;gt; &amp;lt;c&amp;gt;class&amp;lt;/c&amp;gt;",
&lt;p&gt;First, we'll add a rule to make all cues 1.2 times bigger than normal.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video::cue {
  font-size: 1.2rem;
&lt;p&gt;Then we style each of the tags above with a different color.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video::cue(u) {
  color: green;
video::cue(b) {
  color: purple;
video::cue(i) {
  color: red;
video::cue(c) {
  color: lavender;
&lt;h4 id="styling_by_class"&gt;Styling by class&lt;/h4&gt;
&lt;p&gt;The second cue is displayed right after the first one and includes the same tags. However, they all have a class of &lt;code&gt;myclass&lt;/code&gt; applied to them.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;js&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: js notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;track.addCue(
  new VTTCue(
    "Styles: Class markup: &amp;lt;b.myclass&amp;gt;bold&amp;lt;/b&amp;gt; &amp;lt;u.myclass&amp;gt;underlined&amp;lt;/u&amp;gt; &amp;lt;i.myclass&amp;gt;italic&amp;lt;/i&amp;gt; &amp;lt;c.myclass&amp;gt;class&amp;lt;/c&amp;gt;",
&lt;p&gt;We style all items with the &lt;code&gt;.myclass&lt;/code&gt; class with a light blue text color, except for the specific case of &lt;code&gt;c.myclass&lt;/code&gt;, which is given a blue text color.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video::cue(.myclass) {
  color: lightblue;
video::cue(c.myclass) {
  color: blue;
&lt;h4 id="styling_using_attributes"&gt;Styling using attributes&lt;/h4&gt;
&lt;p&gt;The next two cues are displayed after two and then three seconds.
The first displays text marked up with the &lt;code&gt;lang&lt;/code&gt; tag for three locales of English, while the second displays a &lt;code&gt;&amp;lt;v&amp;gt;&lt;/code&gt; (voice) tag with the "Bob" attribute.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;js&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: js notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;track.addCue(
  new VTTCue(
    "&amp;lt;lang en&amp;gt;Lang markup: 'en'&amp;lt;/lang&amp;gt;  &amp;lt;lang en-GB&amp;gt;Text: 'en-GB'&amp;lt;/lang&amp;gt; &amp;lt;lang en-US&amp;gt;Text: 'en-US'&amp;lt;/lang&amp;gt;",
track.addCue(new VTTCue(3, 6, "&amp;lt;v Bob&amp;gt;Bob's voice&amp;lt;/v&amp;gt;"));
&lt;p&gt;We use the &lt;code&gt;lang&lt;/code&gt; attribute selector to give each language variant a different text color.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video::cue([lang="en"]) {
  color: lightgreen;
video::cue([lang="en-GB"]) {
  color: darkgreen;
video::cue(:lang(en-US)) {
  color: #6082b6;
&lt;p&gt;Then we use the &lt;code&gt;v&lt;/code&gt; tag and attribute selector for &lt;code&gt;voice&lt;/code&gt; to color text in "Bob's voice" orange.&lt;/p&gt;
&lt;div class="code-example"&gt;&lt;div class="example-header"&gt;&lt;span class="language-name"&gt;css&lt;/span&gt;&lt;/div&gt;&lt;pre class="brush: css notranslate live-sample---more_cue_styling_examples"&gt;&lt;code&gt;video::cue(v[voice="Bob"]) {
  color: orange;