Revision 996485 of WebVTT

<div>{{HTMLVersionHeader("5")}}</div>

<p>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")}}.</p>

<p>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.</p>

<p>The mime type of WebVTT is <code>text/vtt</code>.</p>

<h2 id="WebVTT_Body">WebVTT Body</h2>

<p>The structure of a WebVTT file requires two things and has four optional components.</p>

<ul>
 <li>An optional byte order mark (BOM)</li>
 <li>The string <code>WEBVTT</code></li>
 <li>An optional text header to the right of <code>WEBVTT</code>.
  <ul>
   <li>There must be at least one space after <code>WEBVTT</code></li>
   <li>You might use this to add a description to the file</li>
   <li>You may use anything except newlines or the string "<code>--&gt;"</code></li>
  </ul>
 </li>
 <li>A blank line, which is equivalent to two consecutive newlines.</li>
 <li>Zero or more cues or comments.</li>
 <li>Zero or more blank lines.</li>
</ul>

<h5 id="Example_1_-_Simplest_possible_WEBVTT_file">Example 1 - Simplest possible WEBVTT file</h5>

<pre class="eval">
WEBVTT
</pre>

<h5 id="Example_2_-_Very_simple_WebVTT_file">Example 2 - Very simple WebVTT file</h5>

<pre class="eval">
WEBVTT - This file has no cues.
</pre>

<h5 id="Example_3_-_Common_WebVTT_example">Example 3 - Common WebVTT example</h5>

<pre class="eval">
WEBVTT - This file has cues.

14
00:01:14.815 --&gt; 00:01:18.114
- What?
- Where are we now?

15
00:01:18.171 --&gt; 00:01:20.991
- This is big bat country.

16
00:01:21.058 --&gt; 00:01:23.868
- [ Bats Screeching ]
- They won't get in your hair. They're after the bugs.
</pre>

<h2 id="WebVTT_Comment">WebVTT Comment</h2>

<p>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.</p>

<p>A comment cannot contain the string "<code>--&gt;",</code>&nbsp;the ampersand character (&amp;), or the less-than sign (&lt;). Instead use the escape sequence "&amp;amp;" for ampersand and "&amp;lt;" for less-than. It is also recommended that you use the greater-than escape sequence "&amp;gt;" instead of the greater-than character (&gt;) to avoid confusion with tags.</p>

<p>A comment consists of three parts:</p>

<ul>
 <li>The string <code>NOTE</code></li>
 <li>A space or a newline</li>
 <li>Zero or more characters other than those noted above</li>
</ul>

<h5 id="Example_4_-_Common_WebVTT_example">Example 4 - Common WebVTT example</h5>

<pre class="eval">
NOTE This is a comment
</pre>

<h5 id="Example_5_-_Multi-line_comment">Example 5 - Multi-line comment</h5>

<pre class="eval">
NOTE
Another comment that is spanning
more than one line.

NOTE You can also make a comment
across more than one line this way.
</pre>

<h5 id="Example_6_-_Common_comment_usage">Example 6 - Common comment usage</h5>

<pre class="eval">
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 --&gt; 00:02:20.000
- Ta en kopp varmt te.
- Det är inte varmt.

2
00:02:20.000 --&gt; 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 --&gt; 00:02:30.000
-Ta en kopp.
</pre>

<h2 id="WebVTT_Cues">WebVTT Cues</h2>

<p>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:</p>

<ul>
 <li>An optional cue identifier followed by a newline</li>
 <li>Cue timings</li>
 <li>Optional cue settings with at least one space before the first and between each setting</li>
 <li>One or more newlines</li>
 <li>The cue payload text</li>
</ul>

<h5 id="Example_7_-_Example_of_a_cue">Example 7 - Example of a cue</h5>

<pre class="eval">
1 - Title Crawl
00:00:5.000 --&gt; 00:00:10.000 line:0 position:20% size:60% align:start
Some time ago in a place rather distant....</pre>

<h3 id="Cue_Identifier">Cue Identifier</h3>

<p>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 "<code>--&gt;"</code>. 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, ...).</p>

<h5 id="Example_8_-_Cue_identifier_from_Example_7">Example 8 - Cue identifier from Example 7</h5>

<pre class="eval">
1 - Title Crawl</pre>

<h5 id="Example_9_-_Common_usage_of_identifiers">Example 9 - Common usage of identifiers</h5>

<pre class="eval">
WEBVTT

1
00:00:22.230 --&gt; 00:00:24.606
This is the first subtitle.

2
00:00:30.739 --&gt; 00:00:34.074
This is the second.

3
00:00:34.159 --&gt; 00:00:35.743
Third
</pre>

<h3 id="Cue_Timings">Cue Timings</h3>

<p>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.</p>

<p>If the WebVTT file is being used for chapters ({{HTMLElement("track")}} {{htmlattrxref("kind")}} is <code>chapters</code>) then the file cannot have overlapping timings.</p>

<p>Each cue timing contains five components:</p>

<ul>
 <li>Timestamp for start time</li>
 <li>At least one space</li>
 <li>The string "<code>--&gt;"</code></li>
 <li>At least one space</li>
 <li>Timestamp for end time
  <ul>
   <li>Which must be greater than the start time</li>
  </ul>
 </li>
</ul>

<p>The timestamps must be in one of two formats:</p>

<ul>
 <li><code>mm:ss.ttt</code></li>
 <li><code>hh:mm:ss.ttt</code></li>
</ul>

<p>Where the components are defined as follows:</p>

<ul>
 <li><code>hh</code> is hours

  <ul>
   <li>Must be at least two digits</li>
   <li>Hours can be greater than two digits (e.g. 9999:00:00.000)</li>
  </ul>
 </li>
 <li><code>mm</code> is minutes
  <ul>
   <li>Must be between 00 and 59 inclusive</li>
  </ul>
 </li>
 <li><code>ss</code> is senconds
  <ul>
   <li>Must be between 00 and 59 inclusive</li>
  </ul>
 </li>
 <li><code>ttt</code> is miliseconds
  <ul>
   <li>Must be between 000 and 999 inclusive</li>
  </ul>
 </li>
</ul>

<h5 id="Example_10_-_Basic_cue_timing_examples">Example 10 - Basic cue timing examples</h5>

<pre class="eval">
00:22.230 --&gt; 00:24.606
00:30.739 --&gt; 00:00:34.074
00:00:34.159 --&gt; 00:35.743
00:00:35.827 --&gt; 00:00:40.122</pre>

<h5 id="Example_11_-_Overlapping_cue_timing_examples">Example 11 - Overlapping cue timing examples</h5>

<pre class="eval">
00:00:00.000 --&gt; 00:00:10.000
00:00:05.000 --&gt; 00:01:00.000
00:00:30.000 --&gt; 00:00:50.000</pre>

<h5 id="Example_12_-_Non-overlapping_cue_timing_examples">Example 12 - Non-overlapping cue timing examples</h5>

<pre class="eval">
00:00:00.000 --&gt; 00:00:10.000
00:00:10.000 --&gt; 00:01:00.581
00:01:00.581 --&gt; 00:02:00.100
00:02:01.000 --&gt; 00:02:01.000</pre>

<h3 id="Cue_Settings">Cue Settings</h3>

<p>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.</p>

<p>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:</p>

<ul>
 <li><strong>vertical</strong>

  <ul>
   <li>Indicates that the text will be displayed vertically rather than horizontally, such as in some Asian languages.</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="2">Table 1 - vertical values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th><code>vertical:rl</code></th>
     <td>writing direction is right to left</td>
    </tr>
    <tr>
     <th><code>vertical:lr</code></th>
     <td>writing direction is left to right</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>line</strong>
  <ul>
   <li>Specifies where text appears vertically. If vertical is set, line specifies where text appears horizontally.</li>
   <li>Value can be a line number
    <ul>
     <li>The line height is the height of the first line of the cue as it appears on the video</li>
     <li>Positive numbers indicate top down</li>
     <li>Negative numbers indicate bottom up</li>
    </ul>
   </li>
   <li>Or value can be a percentage
    <ul>
     <li>Must be an integer (i.e. no decimals) between 0 and 100 inclusive</li>
     <li>Must be followed by a percent sign (%)</li>
    </ul>
   </li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 2 - line examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th>&nbsp;</th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>line:0</code></th>
     <td>top</td>
     <td>right</td>
     <td>left</td>
    </tr>
    <tr>
     <th><code>line:-1</code></th>
     <td>bottom</td>
     <td>left</td>
     <td>right</td>
    </tr>
    <tr>
     <th><code>line:0%</code></th>
     <td>top</td>
     <td>right</td>
     <td>left</td>
    </tr>
    <tr>
     <th><code>line:100%</code></th>
     <td>bottom</td>
     <td>left</td>
     <td>right</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>position</strong>
  <ul>
   <li>Specifies where the text will appear horizontally. If vertical is set, position specifies where the text will appear vertically.</li>
   <li>Value is a percentage</li>
   <li>Must be an integer (no decimals) between 0 and 100 inclusive</li>
   <li>Must be followed by a percent sign (%)</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 3 - position examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th>&nbsp;</th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>position:0%</code></th>
     <td>left</td>
     <td>top</td>
     <td>top</td>
    </tr>
    <tr>
     <th><code>position:100%</code></th>
     <td>right</td>
     <td>bottom</td>
     <td>bottom</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>size</strong>
  <ul>
   <li>Specifies the width of the text area. If vertical is set, size specifies the height of the text area.</li>
   <li>Value is a percentage</li>
   <li>Must be an integer (i.e. no decimals) between 0 and 100 inclusive</li>
   <li>Must be followed by a percent sign (%)</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 4 - size examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th>&nbsp;</th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>size:100%</code></th>
     <td>full width</td>
     <td>full height</td>
     <td>full height</td>
    </tr>
    <tr>
     <th><code>size:50%</code></th>
     <td>half width</td>
     <td>half height</td>
     <td>half height</td>
    </tr>
   </tbody>
  </table>
 </li>
 <li><strong>align</strong>
  <ul>
   <li>Specifies the alignment of the text. Text is aligned within the space given by the size cue setting if it is set.</li>
  </ul>

  <table>
   <thead>
    <tr>
     <th colspan="4">Table 5 - align values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th>&nbsp;</th>
     <th><code>vertical</code> omitted</th>
     <th><code>vertical:rl</code></th>
     <th><code>vertical:lr</code></th>
    </tr>
    <tr>
     <th><code>align:start</code></th>
     <td>left</td>
     <td>top</td>
     <td>top</td>
    </tr>
    <tr>
     <th><code>align:middle</code></th>
     <td>centred horizontally</td>
     <td>centred vertically</td>
     <td>centred vertically</td>
    </tr>
    <tr>
     <th><code>align:end</code></th>
     <td>right</td>
     <td>bottom</td>
     <td>bottom</td>
    </tr>
   </tbody>
  </table>
 </li>
</ul>

<h5 id="Example_13_-_Cue_setting_examples">Example 13 - Cue setting examples</h5>

<p>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.</p>

<pre class="eval">
00:00:5.000 --&gt; 00:00:10.000
00:00:5.000 --&gt; 00:00:10.000 line:63% position:72% align:start
00:00:5.000 --&gt; 00:00:10.000 line:0 position:20% size:60% align:start
00:00:5.000 --&gt; 00:00:10.000 vertical:rt line:-1 align:end
</pre>

<h3 id="Cue_Payload">Cue Payload</h3>

<p>The payload is where the main information or content is located. In normal usage the payload contains the subtitles to be displayed.&nbsp;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.</p>

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

<p>In addition to the three escape sequences mentioned above, there are fours others. They are listed in the table below.</p>

<table>
 <thead>
  <tr>
   <th colspan="3">Table 6 - Escape sequences</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <th>Name</th>
   <th>Character</th>
   <th>Escape Sequence</th>
  </tr>
  <tr>
   <td>Ampersand</td>
   <td>&amp;</td>
   <td><code>&amp;amp;</code></td>
  </tr>
  <tr>
   <td>Less-than</td>
   <td>&lt;</td>
   <td><code>&amp;lt;</code></td>
  </tr>
  <tr>
   <td>Greater-than</td>
   <td>&gt;</td>
   <td><code>&amp;gt;</code></td>
  </tr>
  <tr>
   <td>Left-to-right mark</td>
   <td>&nbsp;</td>
   <td><code>&amp;lrm;</code></td>
  </tr>
  <tr>
   <td>Right-to-left mark</td>
   <td>&nbsp;</td>
   <td><code>&amp;rlm;</code></td>
  </tr>
  <tr>
   <td>Non-breaking space</td>
   <td><code>&nbsp;</code></td>
   <td><code>&amp;nbsp;</code></td>
  </tr>
 </tbody>
</table>

<h3 id="Cue_Payload_Text_Tags">Cue Payload Text Tags</h3>

<p>There are a number of tags, such as <code>&lt;bold&gt;</code>, that can be used. However, if the WebVTT file is used in a {{HTMLElement("track")}} element where the attribute {{htmlattrxref("kind")}} is <code>chapters</code> then you cannot use tags.</p>

<ul>
 <li><strong>Timestamp tag</strong>

  <ul>
   <li>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&nbsp;<em>active text</em> 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&nbsp;<em>active text</em> in the payload is&nbsp;<em>previous text</em> . Any text beyond the&nbsp;<em>active text</em> is&nbsp;<em>future text</em> . This enables karaoke style captions.</li>
  </ul>

  <div>
  <h5 id="Example_12_-_Karaoke_style_text">Example 12 - Karaoke style text</h5>

  <pre class="eval">
1
00:16.500 --&gt; 00:18.500
When the moon &lt;00:17.500&gt;hits your eye

1
00:00:18.500 --&gt; 00:00:20.500
Like a &lt;00:19.000&gt;big-a &lt;00:19.500&gt;pizza &lt;00:20.000&gt;pie

1
00:00:20.500 --&gt; 00:00:21.500
That's &lt;00:00:21.000&gt;amore
      </pre>
  </div>
 </li>
</ul>

<p>The following tags are the HTML tags allowed in a cue and require opening and closing tags (e.g. <code>&lt;b&gt;text&lt;/b&gt;</code>).</p>

<ul>
 <li><strong>Class tag</strong> (<code>&lt;c&gt;&lt;/c&gt;</code>)

  <ul>
   <li>Style the contained text using a CSS class.</li>
  </ul>

  <div>
  <h5 id="Example_14_-_Class_tag">Example 14 - Class tag</h5>

  <pre class="brush: html">
&lt;c.classname&gt;text&lt;/c&gt;</pre>
  </div>
 </li>
 <li><strong>Italics tag</strong> (<code>&lt;i&gt;&lt;/i&gt;</code>)
  <ul>
   <li>Italicize the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_15_-_Italics_tag">Example 15 - Italics tag</h5>

  <pre class="brush: html">
&lt;i&gt;text&lt;/i&gt;</pre>
  </div>
 </li>
 <li><strong>Bold tag</strong> (<code>&lt;b&gt;&lt;/b&gt;</code>)
  <ul>
   <li>Bold the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_16_-_Bold_tag">Example 16 - Bold tag</h5>

  <pre class="brush: html">
&lt;b&gt;text&lt;/b&gt;</pre>
  </div>
 </li>
 <li><strong>Underline tag</strong> (<code>&lt;u&gt;&lt;/u&gt;</code>)
  <ul>
   <li>Underline the contained text.</li>
  </ul>

  <div>
  <h5 id="Example_17_-_Underline_tag">Example 17 - Underline tag</h5>

  <pre class="brush: html">
&lt;u&gt;text&lt;/u&gt;</pre>
  </div>
 </li>
 <li><strong>Ruby tag</strong> (<code>&lt;ruby&gt;&lt;/ruby&gt;</code>)
  <ul>
   <li>Used with ruby text tags to display <a href="https://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li>
  </ul>

  <div>
  <h5 id="Example_18_-_Ruby_tag">Example 18 - Ruby tag</h5>

  <pre class="brush: html">
&lt;ruby&gt;WWW&lt;rt&gt;World Wide Web&lt;/rt&gt;oui&lt;rt&gt;yes&lt;/rt&gt;&lt;/ruby&gt;</pre>
  </div>
 </li>
 <li><strong>Ruby text tag</strong> (<code>&lt;rt&gt;&lt;/rt&gt;</code>)
  <ul>
   <li>Used with ruby tags to display <a href="https://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li>
  </ul>

  <div>
  <h5 id="Example_19_-_Ruby_text_tag">Example 19 - Ruby text tag</h5>

  <pre class="brush: html">
&lt;ruby&gt;WWW&lt;rt&gt;World Wide Web&lt;/rt&gt;oui&lt;rt&gt;yes&lt;/rt&gt;&lt;/ruby&gt;</pre>
  </div>
 </li>
 <li><strong>Voice tag</strong> (<code>&lt;v&gt;&lt;/v&gt;</code>)
  <ul>
   <li>Similar to class tag, also used to style the contained text using CSS.</li>
  </ul>

  <div>
  <h5 id="Example_20_-_Voice_tag">Example 20 - Voice tag</h5>

  <pre class="brush: html">
&lt;v Bob&gt;text&lt;/v&gt;</pre>
  </div>
 </li>
</ul>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th>Specification</th>
   <th>Status</th>
   <th>Comment</th>
  </tr>
  <tr>
   <td>{{SpecName("WebVTT")}}</td>
   <td>{{Spec2("WebVTT")}}</td>
   <td>Initial definition</td>
  </tr>
 </tbody>
</table>

<h2 id="Compatibility">Compatibility</h2>

<p>{{CompatibilityTable}}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>18</td>
   <td>24<sup>[1]</sup></td>
   <td>10</td>
   <td>15.0</td>
   <td>7</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IChrome for Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4.4</td>
   <td>{{CompatNo}}</td>
   <td>35.0</td>
   <td>21.0</td>
   <td>7</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] This feature is disabled by default in Gecko. See <a href="https://wiki.mozilla.org/WebVTT">more information within theMozilla wiki</a>.</p>