Introduction to WebVTT
WebVTT stands for Web Video Text Tracks. This is a W3C standard which was introduced so that a standard for video text tracks could be introduced and can be embedded into browsers as a standard feature. This is an API which is used in junction with HTML <track> tag. The simple example of WebVTT can be taken as captions and subtitles which can be edited and arranged in a separate WebVTT file. The simple purpose of this can be a time synchronized subtitles with audio or video data which is being run on any website at any given instance of time.
WebVTT is a format for displaying timed text tracks (e.g. subtitles) with the {{HTMLElement("track")}} element. The primary purpose of WebVTT files is to add subtitles to a {{HTMLElement("video")}}.
WebVTT is a text based format. A WebVTT file must be encoded in UTF-8 format. Where you can use spaces you can also use tabs.
The mime type of WebVTT is text/vtt.
An example of WebVTT is given below:
WEBVTT 00:11.000 --> 00:13.000 <v Roger Bingham>We are in New York City 00:13.000 --> 00:16.000 <v Roger Bingham>We’re actually at the Lucern Hotel, just down the street 00:16.000 --> 00:18.000 <v Roger Bingham>from the American Museum of Natural History 00:18.000 --> 00:20.000 <v Roger Bingham>And with me is Neil deGrasse Tyson 00:20.000 --> 00:22.000 <v Roger Bingham>Astrophysicist, Director of the Hayden Planetarium 00:22.000 --> 00:24.000 <v Roger Bingham>at the AMNH.
The WebVTT code contains the cues which can be either a single line or multiple lines. As given below:
WEBVTT 00:01.000 --> 00:04.000 Never drink liquid nitrogen. 00:05.000 --> 00:09.000 — It will perforate your stomach. — You could die.
WebVTT Body
The structure of a WebVTT file requires two things and has four optional components.
- An optional byte order mark (BOM)
- The string
WEBVTT - An optional text header to the right of
WEBVTT.- There must be at least one space after
WEBVTT - You might use this to add a description to the file
- You may use anything except newlines or the string "
-->"
- There must be at least one space after
- A blank line, which is equivalent to two consecutive newlines.
- Zero or more cues or comments.
- Zero or more blank lines
Example 1 - Simplest possible WEBVTT file
WEBVTT
Example 2 - Very simple WebVTT file
WEBVTT - This file has no cues.
Example 3 - Common WebVTT example
WEBVTT - This file has cues. 14 00:01:14.815 --> 00:01:18.114 - What? - Where are we now? 15 00:01:18.171 --> 00:01:20.991 - This is big bat country. 16 00:01:21.058 --> 00:01:23.868 - [ Bats Screeching ] - They won't get in your hair. They're after the bugs.
Inner Structure of WebVTT file
The structure of writing the caption can be understood from above code, where the first time is starting time for showing the caption under and and the second time after à is ending time for that particular caption. Then from next line with starting symbol of hyphen (-) a caption can be specified. We can alos place the comments before or after the caption section in order to use them for information just like in any other programming language to remind things as we work through large programs. Comments start with the NOTE keyword. Comments can either be dingle or multiple line. The format for specifying both types of comments is same.
WebVTT stands for Web Video Text Tracks. This is a W3C standard which was introduced so that a standard for video text tracks could be introduced and can be embedded into browsers as a standard feature. This is an API which is used in junction with HTML <track> tag. The simple example of WebVTT can be taken as captions and subtitles which can be edited and arranged in a separate WebVTT file. The simple purpose of this can be a time synchronized subtitles with audio or video data which is being run on any website at any given instance of time.
From following examples we can observe the general structure of WebVTT files.
WEBVTT 00:11.000 --> 00:13.000 <v Roger Bingham>We are in New York City 00:13.000 --> 00:16.000 <v Roger Bingham>We’re actually at the Lucern Hotel, just down the street 00:16.000 --> 00:18.000 <v Roger Bingham>from the American Museum of Natural History 00:18.000 --> 00:20.000 <v Roger Bingham>And with me is Neil deGrasse Tyson 00:20.000 --> 00:22.000 <v Roger Bingham>Astrophysicist, Director of the Hayden Planetarium 00:22.000 --> 00:24.000 <v Roger Bingham>at the AMNH.
The WebVTT code contains the cues which can be either a single line or multiple lines. As given below:
WEBVTT 00:01.000 --> 00:04.000 Never drink liquid nitrogen. 00:05.000 --> 00:09.000 — It will perforate your stomach. — You could die.
The structure of writing the caption can be understood from above code, where the first time is starting time for showing the caption under and and the second time after à is ending time for that particular caption. Then from next line with starting symbol of hyphen (-) a caption can be specified. We can alos place the comments before or after the caption section in order to use them for information just like in any other programming language to remind things as we work through large programs. Comments start with the NOTE keyword. Comments can either be dingle or multiple line. The format for specifying both types of comments is same.
WebVTT Comment
Comments are an optional component that can be used to add information to a WebVTT file. Comments are intended for those reading the file and are not seen by users. Comments may contain newlines but it cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a comment.
A comment cannot contain the string "-->", the ampersand character (&), or the less-than sign (<). Instead use the escape sequence "&" for ampersand and "<" for less-than. It is also recommended that you use the greater-than escape sequence ">" instead of the greater-than character (>) to avoid confusion with tags.
A comment consists of three parts:
- The string
NOTE - A space or a newline
- Zero or more characters other than those noted above
Example 4 - Common WebVTT example
NOTE This is a comment
Example 5 - Multi-line comment
NOTE Another comment that is spanning more than one line. NOTE You can also make a comment across more than one line this way.
Example 6 - Common comment usage
WEBVTT - Translation of that film I like NOTE This translation was done by Kyle so that some friends can watch it with their parents. 1 00:02:15.000 --> 00:02:20.000 - Ta en kopp varmt te. - Det är inte varmt. 2 00:02:20.000 --> 00:02:25.000 - Har en kopp te. - Det smakar som te. NOTE This last line may not translate well. 3 00:02:25.000 --> 00:02:30.000 -Ta en kopp
Usage
We can also embed the CSS files within HTML files so that the cues which are attached to that page can be format according to the look and feel of web design. The style can be defined in head part of HTML page where the track file can be listed using the track tag and src attribute to make a link between WebVTT file and HTML page. It must be noted that the file format for WebVTT is ‘.vtt’. This can be done as follows:
<!doctype html>
<html>
<head>
<title>Styling WebVTT cues</title>
<style>
video::cue {
background-image: linear-gradient(to bottom, dimgray, lightgray);
color: papayawhip;
}
video::cue(b) {
color: peachpuff;
}
</style>
</head>
<body>
<video controls autoplay src="video.webm">
<track default src="track.vtt">
</video>
</body>
</html>
Above is an example of using the CSS style sheet for formatting but it is used in HTML file, another way to do it is to define the style directly in WebVTT file, which is advantageous in case when we are changing the look and feel of HTML pages but we want the style to be coherent and consistent throughout the website with same design as it used before. The example of styling within the WebVTT file using CSS is given below:
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;
}
hello
00:00:00.000 --> 00:00:10.000
Hello <b>world</b>.
NOTE style blocks cannot appear after the first cue.
We can also use the identifier in WebVTT file which can be used for defining a new style for some particular cues in file. The example where we wanted the transcription text to be red highlighted and the other part to remain normal, we can define it as follows using CSS. Where it must be noted that the CSS uses escape sequences the way they are used in HTML pages:
WEBVTT
1
00:00.000 --> 00:02.000
That’s an, an, that’s an L!
crédit de transcription
00:04.000 --> 00:05.000
Transcrit par Célestes™
::cue(#\31) { color: lime; }
::cue(#crédit\ de\ transcription) { color: red; }
Positioning of captions or subtitles is also supported and is done the way we do it in CSS as shown below:
WEBVTT 00:00:00.000 --> 00:00:04.000 position:10%,line-left align:left size:35% Where did he go? 00:00:03.000 --> 00:00:06.500 position:90% align:right size:35% I think he went down this lane. 00:00:04.000 --> 00:00:06.500 position:45%,line-right align:center size:35% What are you waiting for?
The connection between the HTML, CSS and WebVTT files is simple as making a connection between the particular files the way we reference an image link using <a> tag and src attribute for image. Similar method is followed to attach the WebVTT file to any HTML page with a difference that WebVTT uses the <track> tag instead of <a>.
WebVTT Cues
A cue is a single subtitle block that has a single start time, end time, and textual payload. Example 6 consists of the header, a blank line, and then five cues separated by blank lines. A cue consists of five components:
- An optional cue identifier followed by a newline
- Cue timings
- Optional cue settings with at least one space before the first and between each setting
- One or more newlines
- The cue payload text
Example 7 - Example of a cue
1 - Title Crawl 00:00:5.000 --> 00:00:10.000 line:0 position:20% size:60% align:start Some time ago in a place rather distant....
Cue Identifier
The identifier is a name that identifies the cue. It can be used to reference the cue from a script. It must not contain a newline and cannot contain the string "-->". It must end with a single newline. They do not have to be unique, although it is common to number them (e.g. 1, 2, 3, ...).
Example 8 - Cue identifier from Example 7
1 - Title Crawl
Example 9 - Common usage of identifiers
WEBVTT 1 00:00:22.230 --> 00:00:24.606 This is the first subtitle. 2 00:00:30.739 --> 00:00:34.074 This is the second. 3 00:00:34.159 --> 00:00:35.743 Third
Cue Timings
A cue timing indicates when the cue is shown. It has a start and end time which are 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.
If the WebVTT file is being used for chapters ({{HTMLElement("track")}} {{htmlattrxref("kind")}} is chapters) then the file cannot have overlapping timings.
Each cue timing contains five components:
- Timestamp for start time
- At least one space
- The string "
-->" - At least one space
- Timestamp for end time
- Which must be greater than the start time
The timestamps must be in one of two formats:
mm:ss.ttthh:mm:ss.ttt
Where the components are defined as follows:
hhis hours- Must be at least two digits
- Hours can be greater than two digits (e.g. 9999:00:00.000)
mmis minutes- Must be between 00 and 59 inclusive
ssis senconds- Must be between 00 and 59 inclusive
tttis miliseconds- Must be between 000 and 999 inclusive
Example 10 - Basic cue timing examples
00:22.230 --> 00:24.606 00:30.739 --> 00:00:34.074 00:00:34.159 --> 00:35.743 00:00:35.827 --> 00:00:40.122
Example 11 - Overlapping cue timing examples
00:00:00.000 --> 00:00:10.000 00:00:05.000 --> 00:01:00.000 00:00:30.000 --> 00:00:50.000
Example 12 - Non-overlapping cue timing examples
00:00:00.000 --> 00:00:10.000 00:00:10.000 --> 00:01:00.581 00:01:00.581 --> 00:02:00.100 00:02:01.000 --> 00:02:01.000
Cue Settings
Cue settings are optional components used to position where the cue payload text will be displayed over the video. This includes whether the text is displayed horizontally or vertically. There can be zero or more of them, and they can be used in any order so long as each setting is used no more than once.
The cue settings are added to the right of the cue timings. There must be one or more spaces between the cue timing and the first setting and between each setting. A setting's name and value are separated by a colon. The settings are case sensitive so use lower case as shown. There are five cue settings:
- vertical
- Indicates that the text will be displayed vertically rather than horizontally, such as in some Asian languages.
Table 1 - vertical values vertical:rlwriting direction is right to left vertical:lrwriting direction is left to right - line
- Specifies where text appears vertically. If vertical is set, line specifies where text appears horizontally.
- Value can be a line number
- The line height is the height of the first line of the cue as it appears on the video
- Positive numbers indicate top down
- Negative numbers indicate bottom up
- Or value can be a percentage
- Must be an integer (i.e. no decimals) between 0 and 100 inclusive
- Must be followed by a percent sign (%)
Table 2 - line examples verticalomittedvertical:rlvertical:lrline:0top right left line:-1bottom left right line:0%top right left line:100%bottom left right - position
- Specifies where the text will appear horizontally. If vertical is set, position specifies where the text will appear vertically.
- Value is a percentage
- Must be an integer (no decimals) between 0 and 100 inclusive
- Must be followed by a percent sign (%)
Table 3 - position examples verticalomittedvertical:rlvertical:lrposition:0%left top top position:100%right bottom bottom - size
- Specifies the width of the text area. If vertical is set, size specifies the height of the text area.
- Value is a percentage
- Must be an integer (i.e. no decimals) between 0 and 100 inclusive
- Must be followed by a percent sign (%)
Table 4 - size examples verticalomittedvertical:rlvertical:lrsize:100%full width full height full height size:50%half width half height half height - align
- Specifies the alignment of the text. Text is aligned within the space given by the size cue setting if it is set.
Table 5 - align values verticalomittedvertical:rlvertical:lralign:startleft top top align:middlecentred horizontally centred vertically centred vertically align:endright bottom bottom
Example 13 - Cue setting 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:5.000 --> 00:00:10.000 00:00:5.000 --> 00:00:10.000 line:63% position:72% align:start 00:00:5.000 --> 00:00:10.000 line:0 position:20% size:60% align:start 00:00:5.000 --> 00:00:10.000 vertical:rt line:-1 align:end
Cue Payload
The payload is where the main information or content is located. In normal usage the payload contains the subtitles to be displayed. The payload text may contain newlines but it cannot contain a blank line, which is equivalent to two consecutive newlines. A blank line signifies the end of a cue.
A cue text payload cannot contain the string "-->", the ampersand character (&), or the less-than sign (<). Instead use the escape sequence "&" for ampersand and "<" for less-than. It is also recommended that you use the greater-than escape sequence ">" 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.
In addition to the three escape sequences mentioned above, there are fours others. They are listed in the table below.
| Table 6 - Escape sequences | ||
|---|---|---|
| Name | Character | Escape Sequence |
| Ampersand | & | & |
| Less-than | < | < |
| Greater-than | > | > |
| Left-to-right mark | ‎ |
|
| Right-to-left mark | ‏ |
|
| Non-breaking space | |
|
Cue Payload Text Tags
There are a number of tags, such as <bold>, that can be used. However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute {{htmlattrxref("kind")}} is chapters then you cannot use tags.
- Timestamp tag
- The timestamp must be greater that the cue's start timestamp, greater than any previous timestamp in the cue payload, and less than the cue's end timestamp. The active text is the text between the timestamp and the next timestamp or to the end of the payload if there is not another timestamp in the payload. Any text before the active text in the payload is previous text . Any text beyond the active text is future text . This enables karaoke style captions.
Example 12 - Karaoke style text
1 00:16.500 --> 00:18.500 When the moon <00:17.500>hits your eye 1 00:00:18.500 --> 00:00:20.500 Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie 1 00:00:20.500 --> 00:00:21.500 That's <00:00:21.000>amore
The following tags are the HTML tags allowed in a cue and require opening and closing tags (e.g. <b>text</b>).
- Class tag (
<c></c>)- Style the contained text using a CSS class.
Example 14 - Class tag
<c.classname>text</c>
- Italics tag (
<i></i>)- Italicize the contained text.
Example 15 - Italics tag
<i>text</i>
- Bold tag (
<b></b>)- Bold the contained text.
Example 16 - Bold tag
<b>text</b>
- Underline tag (
<u></u>)- Underline the contained text.
Example 17 - Underline tag
<u>text</u>
- Ruby tag (
<ruby></ruby>)- Used with ruby text tags to display ruby characters (i.e. small annotative characters above other characters).
Example 18 - Ruby tag
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
- Ruby text tag (
<rt></rt>)- Used with ruby tags to display ruby characters (i.e. small annotative characters above other characters).
Example 19 - Ruby text tag
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
- Voice tag (
<v></v>)- Similar to class tag, also used to style the contained text using CSS.
Example 20 - Voice tag
<v Bob>text</v>
Interfaces
There are two interfaces or APIs used in WebVTT which are:
VTTCue interface
It is used for providing an interface in Document Object Model API, where different attributes supported by it can be used to prepare and alter the cues in number of ways.
Constructor is the first point for starting the Cue which is defined using the default constructorVTTCue(startTime, endTime, text) where starting time, ending time and text for cue can be adjusted. After that we can set the region for that particular cue to which this cue belongs using cue.region. Vertical, horizontal, line, lineAlign, Position, positionAlign, text, size and Align can be used to alter the cue and its formation, just like we can alter the objects form, shape and visibility in HTML using CSS. But the VTTCue interface is within the WebVTT provides the vast range of adjustment variables which can be used directly to alter the Cue. Following interface can be used to expose WebVTT cues in DOM API:
enum AutoKeyword { "auto" };
enum DirectionSetting { "" /* horizontal */, "rl", "lr" };
enum LineAlignSetting { "start", "center", "end" };
enum PositionAlignSetting { "start", "center", "end", "auto" };
enum AlignSetting { "start", "center", "end", "left", "right" };
[Constructor(double startTime, double endTime, DOMString text)]
interface VTTCue : TextTrackCue {
attribute VTTRegion? region;
attribute DirectionSetting vertical;
attribute boolean snapToLines;
attribute (double or AutoKeyword) line;
attribute LineAlignSetting lineAlign;
attribute (double or AutoKeyword) position;
attribute PositionAlignSetting positionAlign;
attribute double size;
attribute AlignSetting align;
attribute DOMString text;
DocumentFragment getCueAsHTML();
};
VTT Region interface
This is the second interface in WebVTT API.
The new keyword can be used for defining a new VTTRegion object which can then be used for containing the multiple cues. There are several properties of VTTRegion which are width, lines, regionAnchorX, RegionAnchorY, viewportAnchorX, viewportAnchorY and scroll that can be used to specify the look and feel of this VTT region. The interface code is given below which can be used to expose the WebVTT regions in DOM API:
enum ScrollSetting { "" /* none */, "up" };
[Constructor]
interface VTTRegion {
attribute double width;
attribute long lines;
attribute double regionAnchorX;
attribute double regionAnchorY;
attribute double viewportAnchorX;
attribute double viewportAnchorY;
attribute ScrollSetting scroll;
};
Methods and properties
The methods used in WebVTT are those which are used to alter the cue or region as the attributes for both interfaces are different. We can categorize them for better understanding relating to each interface in WebVTT:
-
VTTCue
- The methods which are available in this interface are:
- GetCueAsHTML to get the HTML of that Cue.
- VTT Constructor for creating new objects of Cues
- Autokeyword
- DirectionSetting: to set the direction of caption or text in a file
- LineAlignment: to adjust the line alignment
- PositionAlignSetting: to adjust the position of text
- The methods which are available in this interface are:
-
VTTRegion
- The methods used for region are listed below along with description of their functionality:
- ScrollSetting: For adjusting the scrolling setting of all nodes present in given region
- VTT Region Constructor: for construction of new VTT Regions
- The methods used for region are listed below along with description of their functionality:
Tutorial on how to write a WebVTT file
There are few steps that can be followed to write a simple webVTT file. Before start, it must be noted that you can make use of a notepad and then save the file as ‘.vtt’ file. Steps are given below:
- Open a notepad.
- The first line of WebVTT is standardized similar in the way some other languages require you to put headers as the file starts to indicate the file type. One the very first line you have to write
‘WEBVTT’.
3. Leave the second line blank, one third line the time for first cue can is to be specified. For example, for a first que starting at time 1 second and ending at 5 second, it is written as:
‘00: 01.000 00: 05.000’
- On the next line you can write the caption for this cue which will run from 1 sec to 5th sec.
- Following the similar steps, a complete WebVTT file for specific video or audio file can be made.
CSS Pseudo-classes
CSS pseudo classes allow us to classify the type of object which we want to differentiate from other types of objects. It works in similar manner in WebVTT files as it works in HTML file.
It is one of the good features supported by WebVTT is the localization and use of class elements which can be used in same way they are used in HTML and CSS to classify the style for particular type of objects, but here these are used for styling and classifying the Cues as shown below:
WEBVTT 04:02.500 --> 04:05.000 J’ai commencé le basket à l'âge de 13, 14 ans 04:05.001 --> 04:07.800 Sur les <i.foreignphrase><lang en>playground</lang></i>, ici à Montpellier
In the above example it can be observed that we can use the identifier and pseudo class name for defining the language of caption, where <i> tag is for italics.
The type of pseudo class is determined by the selector it is using and working is similar in nature as it works in HTML. Following CSS pseudo classes can be used:
- Lang (Lanugage): e.g. p:lang(it)
- Link: e.g. a:link
- Nth-last-child: e.g. p:nth-last-child(2)
- Nth-child(n): e.g. p:nth-child(2)
Where p and a are the tags which are used in HTML for paragraph and link, respectively and they can be replaced by identifiers which are used for Cues in WebVTT file.
Specifications
| Specification | Status | Comment |
|---|---|---|
| {{SpecName("WebVTT")}} | {{Spec2("WebVTT")}} | Initial definition |
Compatibility
{{CompatibilityTable}}
| Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| Basic support | 18 | 28 | 10 | 15.0 | 7 |
| Feature | Android | Firefox Mobile (Gecko) | IChrome for Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|
| Basic support | 4.4 | {{CompatNo}} | 35.0 | 21.0 | 7 |