docs.rodeo

MDN Web Docs mirror

Web Video Text Tracks Format (WebVTT)

{{DefaultAPISidebar("WebVTT")}} 

Web Video Text Tracks Format (WebVTT) is a plain-text file format for displaying timed text tracks that are synchronized with content in {{HTMLElement("video")}}  and {{HTMLElement("audio")}}  elements. These can be used, for example, to add closed captions and subtitle text overlays to a {{HTMLElement("video")}} .

The WebVTT files associated with a media element are added using the {{HTMLElement("track")}}  element — see Displaying VTT content defined in a file. A media element can be associated with a number of files, each representing different kinds of timed data, such as closed captions, subtitles, or chapter headings, translated into different locales.

[!NOTE] WebVTT content can also be created and managed programmatically using the WebVTT API.

Overview

WebVTT files have a MIME type of text/vtt and the file extension .vtt. The content must be encoded using {{Glossary("UTF-8")}} .

The structure of a WebVTT consists of the following components, some of them optional, in this order:

A simple WebVTT file that has the WEBVTT string (but no header text), a NOTE block, and two cues is shown below:

WEBVTT

NOTE This is a multi-line note block.
These are used for comments by the author
Two cue blocks are defined below.

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

00:05.000 --> 00:09.000
Because:
- It will perforate your stomach.
- You could die.

The following sections explain the parts of the file, including those not used in the example above.

WebVTT Header

WebVTT files start with a header block containing the following:

The WEBVTT string is the only required part of the WebVTT file, so the simplest possible WebVTT file would look like this:

WEBVTT

The example below shows a header with text. Note that this text must be separated by at least one space or tab.

WEBVTT This file has no cues.

WebVTT cues

A cue defines a single caption, subtitle, or other text block to be displayed over a particular time interval. Cues must appear after the header and any STYLE or REGION blocks.

Each cue consists of three or more lines:

Here is an example of a simple cue. The first line specifies the cue’s display start and end times, separated using the string -->. The second line defines the text to be displayed.

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

The next cue is slightly more complicated. It starts with a cue identifier — 1 - Title Crawl — which may be used to reference the cue in JavaScript and CSS. It also has cue settings after the cue timings to set the cue position.

1 - Title Crawl
00:05.000 --> 00:09.000 line:0 position:20% size:60% align:start
Because:
- It will perforate your stomach.
- You could die.

Note that the output will respect line breaks in the payload text, which allows you to create bulleted lists using hyphen (-) characters as shown. Generally you should only insert these breaks when needed, as the browser will wrap text appropriately.

It is important to not use “extra” blank lines within a cue, for example between the timings line and the cue payload, or within the payload. This is because a blank line will end the current cue.

Each part of the cue is explained in more detail in the following sections.

Cue identifier

The identifier is a name that identifies the cue. It can be used to reference the cue from JavaScript or CSS. It must not contain a newline and cannot contain the string -->. It must end with a single new line. Identifiers do not have to be unique, although it is common to number them (e.g., 1, 2, 3).

The example below shows a file with several cues that include identifiers:

WEBVTT

1
00:00:22.230 --> 00:00:24.606
This is the first subtitle.

2 Some Text
00:00:30.739 --> 00:00:34.074
This is the second.

3
00:00:34.159 --> 00:00:35.743
This is the third

Cue timings

A cue timing indicates the time interval when the cue is shown. It has a start and end time, represented by timestamps. The end time must be greater than the start time, and the start time must be greater than or equal to all previous start times.

Cues may have overlapping timings, unless the WebVTT file is being used for chapters ({{HTMLElement("track")}}  kind is chapters).

Each cue timing contains five components:

The timestamps can be specified in one of the following two formats:

Where the components are defined as follows:

Here are a few cue timing examples:

Cue settings

Cue settings are optional components that position the cue payload text over the video. This includes horizontal and vertical positions. Zero or more cue settings can be specified and used in any order so long as each setting is used no more than once.

Cue settings are added to the right of cue timings. There must be one or more spaces between the cue timing and the first setting and between each setting. A colon separates a setting’s name and value. The settings are case-sensitive; use lowercase as shown. There are five available cue settings:

Here are a few examples. The first line demonstrates no settings. The second line might be used to overlay text on a sign or label. The third line might be used for a title. The last line might be used for an Asian language.

00:00:05.000 --> 00:00:10.000
00:00:05.000 --> 00:00:10.000 line:63% position:72% align:start
00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start
00:00:05.000 --> 00:00:10.000 vertical:rt line:-1 align:end
00:00:05.000 --> 00:00:10.000 position:10%,line-left align:left size:31%
00:00:05.000 --> 00:00:10.000 position:90% align:right size:35%
00:00:05.000 --> 00:00:10.000 position:45%,line-right align:center size:90%

Cue payload

The payload is where the cue content is defined, such as the subtitle or closed caption text. It may contain newlines but cannot contain two consecutive newlines: that would create a blank line, which indicates the end of the block.

A cue text payload cannot contain the string -->, the ampersand character (&), or the less-than sign (<). If needed, you can instead use a {{glossary("character reference")}}  such as the named character reference &amp; for ampersand and &lt; for less-than. It is also recommended that you use the greater-than escape sequence &gt; instead of the greater-than character (>) to avoid confusion with tags. If you are using the WebVTT file for metadata these restrictions do not apply.

Note that all major browsers allow any {{glossary("character reference")}}  in cues, notes, or other text. Older browser versions may support only the following subset of named character references:

Name Character Escape sequence
Ampersand & &amp;
Less-than < &lt;
Greater-than > &gt;
Left-to-right mark none &lrm;
Right-to-left mark none &rlm;
Non-breaking space &nbsp;

Cue payload text tags

A number of tags, such as <b>, can be used for marking up and styling text within a cue. However, if the WebVTT file is used in a {{HTMLElement("track")}}  element where the attribute kind is chapters then you cannot use tags.

The following tags are the HTML tags allowed in a cue and require opening and closing tags (e.g., <b>text</b>). Text marked up with these tags can be formatted in STYLE blocks using the {{cssxref("::cue")}}  pseudo-element.

NOTE blocks

NOTE blocks are optional sections that can be used to add comments to a WebVTT file. They are intended for those reading the file and are not seen by users. For example, you might use them to record author contact details, provide an overview of your structure, or add placeholders for cues that still need to be written.

They can be used anywhere in the WebVTT file after the header.

NOTE blocks may contain newlines but cannot contain two consecutive newlines: that would create a blank line, which indicates the end of the block.

A comment cannot contain the string -->, the ampersand character (&), or the less-than sign (<). If you wish to use these characters, you need to instead use a {{glossary("character reference")}}  such as &amp; for ampersand and &lt; for less-than. It is also recommended that you use the greater-than escape sequence (&gt;) instead of the greater-than character (>) to avoid confusion with tags.

A comment consists of three parts:

Here are some examples:

NOTE This is a single line comment

NOTE
This is a simple multi line comment

NOTE
One comment that is spanning
more than one line.

NOTE You can also make a comment
across more than one line this way.

NOTE TODO I might add a line to indicate work that still has to be done.

STYLE Blocks

STYLE blocks are optional sections that can be used to embed CSS styling of cues within a WebVTT file. Note that these are used to style the appearance and size of the cues, but not their position and layout, which are controlled by the Cue settings.

[!NOTE] WebVTT cues can also be matched by CSS styles loaded by the associated document embedding the video/audio element.

STYLE blocks must appear before any cue blocks in the file.

Each block consists of the following lines:

The block cannot contain the string -->. It may contain newlines but cannot contain two consecutive newlines: that would create a blank line, which indicates the end of the block.

A simple WebVTT files with two STYLE blocks is shown below. This uses {{cssxref("::cue")}}  to apply a text color to all cue text, and a different text color just to text that is tagged with <b></b> tags.

WEBVTT

STYLE
::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}
/* Style blocks cannot use blank lines nor "dash dash greater than" */

NOTE comment blocks can be used between style blocks.

STYLE
::cue(b) {
  color: peachpuff;
}

00:00:00.000 --> 00:00:10.000
- Hello <b>world</b>.

NOTE style blocks cannot appear after the first cue.

[!NOTE] There are live examples demonstrating many of the following cases in More cue styling examples in WebVTT API.

Match all cue payload text

Match on all cue payload text using {{cssxref("::cue")}} .

For example, the following STYLE block would match all cue text and color it yellow.

STYLE
::cue {
  color: yellow;
}

Match a tag type

Match cue text marked up with particular cue payload text tags, such as c, i, b, u, ruby, rt, v, and lang, by specifying the tag in {{cssxref("::cue()")}}  as a type selector.

For example, the following block would match cue payload text marked up with lang as yellow, and each of the other tags as red.

STYLE
::cue(c),
::cue(i),
::cue(b),
::cue(u),
::cue(ruby),
::cue(rt),
::cue(v) {
  color: red;
}
::cue(lang) {
  color: yellow;
}

Match a class selector

Match all tags marked up using a class selector in ::cue().

The STYLE block in the following WebVTT file would match all the text after it, because all the tags have the myclass class.

WEBVTT

STYLE
::cue(.myclass) {
  color: yellow;
}

00:00:00.000 --> 00:00:08.000
<c.myclass>Yellow!</c>
<i.myclass>Yellow!</i>
<u.myclass>Yellow!</u>
<b.myclass>Yellow!</b>
<u.myclass>Yellow!</u>
<ruby.myclass>Yellow! <rt.myclass>Yellow!</rt></ruby>
<v.myclass Kathryn>Yellow!</v>
<lang.myclass en>Yellow!</lang>

To select a particular tag and class you must specify both in ::cue():

STYLE ::cue(b.myclass) {
  color: yellow;
}

Match an attribute

Cue payload text marked up with a particular tag and attribute can be matched using an attribute selector.

For example, consider the following WebVTT file, which has text marked up using the v and lang cue payload text tags, using attributes to specify the particular voice (“Salame”) and languages.

WEBVTT

STYLE
::cue([lang="en-US"]) {
color: yellow;
}
::cue(lang[lang="en-GB"]) {
color: cyan;
}
::cue(v[voice="Salame"]) {
color: lime;
}

00:00:00.000 --> 00:00:08.000
Yellow!

00:00:08.000 --> 00:00:16.000
<lang en-GB>Cyan!</lang>

00:00:16.000 --> 00:00:24.000
I like <v Salame>lime.</v>

Match using pseudo-classes

The previous example styled text for a particular language using attribute matching. You can also match languages using the :lang() pseudo class, as demonstrated by the STYLE block below.

STYLE
::cue(:lang(en)) {
  color: yellow;
}
::cue(:lang(en-GB)) {
  color: cyan;
}

You can similarly match with the :past and :future pseudo-classes, to provide a karaoke-like experience.

video::cue(:past) {
  color: yellow;
}
video::cue(:future) {
  color: cyan;
}

Other pseudo-classes such as link, nth-last-child, and nth-child should work similarly.

Match a cue id

Match against a particular cue id by specifying the id inside {{cssxref("::cue()")}} .

[!NOTE] At time of writing this does not appear to be supported in any of the main browsers.

For example, the following WebVTT file should style the cue with identifier cue1 in green.

WEBVTT

STYLE ::cue(#cue1) {
  color: green;
}

cue1
00:00:00.000 --> 00:00:08.000
Green!

Note that escape sequences are used in WebVTT CSS in the same way as HTML pages. The below example shows how to escape spaces in a cue identifier:

WEBVTT

STYLE
::cue(#transcription\ credits) {
  color: red;
}

transcription credits
00:04.000 --> 00:05.000
Transcribed by Célestes™

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN