path: root/files/zh-tw/web/api/webvtt_api/index.html

---
title: WebVTT
slug: Web/API/WebVTT_API
translation_of: Web/API/WebVTT_API
original_slug: Web/API/Web_Video_Text_Tracks_Format
---
<p>WebVTT 是一種 UTF-8 編碼的文字檔案格式，可藉由 {{ HTMLElement("track") }} 元素顯示加註時間資訊之文字軌，其主要設計目的是為 {{ HTMLElement("video") }} 顯示字幕。</p>

<p>WebVTT 當中可以採用空白或分隔字元（tab）。</p>

<p>WebVTT 的 MIME Type 為 <code>text/vtt</code>。</p>

<p> </p>

<h2 id="WebVTT_文本">WebVTT 文本</h2>

<p>WebVTT 檔的結構中，有兩項必備資訊、四項選用資訊。</p>

<ul>
 <li>選用：byte order mark (BOM)</li>
 <li>字串 <code>WEBVTT</code></li>
 <li>選用：於 <code>WEBVTT</code> 右側可加上文字標題
  <ul>
   <li>在 <code>WEBVTT</code> 之後至少要有一個空白字元</li>
   <li>可以藉此為檔案加上描述</li>
   <li>除了換行字元及<code>「--&gt;</code>」字串外，可以是任何文字</li>
  </ul>
 </li>
 <li>一個空白行，由兩個連續的換行字元構成。</li>
 <li>選用：一個以上的時間節點（cue）或註解</li>
 <li>選用：一個以上的空白行</li>
</ul>

<h5 id="範例_1_-_最簡單的_WEBVTT_檔">範例 1 - 最簡單的 WEBVTT 檔</h5>

<pre>  WEBVTT

</pre>

<h5 id="範例_2_-_很簡單的_WebVTT_檔">範例 2 - 很簡單的 WebVTT 檔</h5>

<pre>  WEBVTT - 這個檔案沒有時間節點

</pre>

<h5 id="範例_3_-_常見的_WebVTT_例子">範例 3 - 常見的 WebVTT 例子</h5>

<pre>  WEBVTT - 這個檔案有時間節點

  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>

<p> </p>

<h2 id="WebVTT_註解">WebVTT 註解</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>註解中不能包含「<code>--&gt;」字串、「</code>&amp;」符號或「&lt;」符號。如欲使用後兩者，可採跳脫字串「&amp;amp;」或「&amp;lt;」。此外雖規格上允許使用「&gt;」字元，仍然建議跳脫為「&amp;gt;」以避免混淆。</p>

<p>註解由三個部分組成：</p>

<ul>
 <li>字串 <code>NOTE</code></li>
 <li>一個空白字元或換行字元</li>
 <li>選用：一個以上的字元，除了前面提到的禁用字元外皆可使用</li>
</ul>

<h5 id="範例_4_-_常見_WebVTT_範例">範例 4 - 常見 WebVTT 範例</h5>

<pre>  NOTE 這行是註解
</pre>

<h5 id="範例_5_-_多行註解">範例 5 - 多行註解</h5>

<pre>  NOTE
  這也是註解，
  只是拆成多行。

  NOTE 當然也可以像這樣
  來分行寫註解。
</pre>

<h5 id="範例_6_-_常見註解使用方式">範例 6 - 常見註解使用方式</h5>

<pre>  WEBVTT - 翻譯我喜歡的影片字幕

  NOTE
  本字幕由 Kyle 翻譯，
  希望可以讓我的朋友跟家人一同觀賞。

  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>

<p> </p>

<h2 id="WebVTT_時間節點">WebVTT 時間節點</h2>

<p>時間節點（cue）是具備單一開始時間、結束時間、文字內容的字幕區段。 Example 6 consists of the header, a blank line, and then five cues separated by blank lines. 時間節點由五個部分組成：</p>

<ul>
 <li>選用：時間節點 ID，後接著一個換行字元</li>
 <li>時間資訊</li>
 <li>選用：時間節點設定，每個設定值以空白字元分隔，第一個設定值前也要加個空白字元</li>
 <li>一個以上的換行字元</li>
 <li>文字內容</li>
</ul>

<h5 id="範例7_-_Example_of_a_cue">範例7 - Example of a cue</h5>

<pre>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>

<p> </p>

<h3 id="節點_ID">節點 ID</h3>

<p>此 ID 代表時間節點的名稱，可以用以在腳本語言中參照某段特定時間節點。ID 中禁用換行字元，也不可以包括「<code>--&gt;」字串。</code>ID 最後必須以一個換行字元作為結束。</p>

<p>雖然通常都用數字（1, 2, 3...）作為 ID，但規格上並不要求每個 ID 都是為一值。</p>

<h5 id="範例_8_-_範例_7_中的時間節點_ID">範例 8 - 範例 7 中的時間節點 ID</h5>

<pre>1 - Title Crawl</pre>

<h5 id="範例_9_-_ID_常見用法">範例 9 - ID 常見用法</h5>

<pre>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>

<p> </p>

<h3 id="時間資訊">時間資訊</h3>

<p>時間資訊標注了此段節點的出現時機，其中包括開始時間與結束時間。結束時間必須比開始時間晚，而開始時間必須比先前所有的開始時間晚，或至少是同一時間。</p>

<p>不同時間節點可以設定為同時顯示，但若 WebVTT 檔案是用在 chapters（{{ HTMLElement("track") }} 的 {{ htmlattrxref("kind") }} 設定為 <code>chapters</code>），則不允許兩段節點同時出現。</p>

<p>每項時間資訊都由五個部分組成：</p>

<ul>
 <li>開始時間</li>
 <li>一個以上的空白字元</li>
 <li>「<code>--&gt;」字串</code></li>
 <li>一個以上的空白字元</li>
 <li>結束時間
  <ul>
   <li>必須比開始時間晚</li>
  </ul>
 </li>
</ul>

<p>時間的表示方式，可以是以下兩種：</p>

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

<p>其中的各元素說明如下：</p>

<ul>
 <li><code>hh</code> - 小時

  <ul>
   <li>至少要有兩個數字，不小於 01</li>
   <li>可以超過兩個數字（例如 9999:00:00.000）</li>
  </ul>
 </li>
 <li><code>mm</code> - 分
  <ul>
   <li>從 00 到 59</li>
  </ul>
 </li>
 <li><code>ss</code> - 秒
  <ul>
   <li>從 00 到 59</li>
  </ul>
 </li>
 <li><code>ttt</code> - 毫秒
  <ul>
   <li>從 000 到 999</li>
  </ul>
 </li>
</ul>

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

<pre>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>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>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>

<p> </p>

<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>水平方向</li>
  </ul>

  <table style="margin-left: 30px;">
   <thead>
    <tr>
     <th colspan="2">Table 1 - vertical values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th><code>vertical:rl</code></th>
     <td>文字方向由右至左</td>
    </tr>
    <tr>
     <th><code>vertical:lr</code></th>
     <td>文字方向由左至右</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 style="margin-left: 30px;">
   <thead>
    <tr>
     <th colspan="4">Table 2 - line examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th> </th>
     <th><code>vertical</code> 省略時</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 style="margin-left: 30px;">
   <thead>
    <tr>
     <th colspan="4">Table 3 - position examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th> </th>
     <th><code>vertical</code> 省略時</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 style="margin-left: 30px;">
   <thead>
    <tr>
     <th colspan="4">Table 4 - size examples</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th> </th>
     <th><code>vertical</code> 省略時</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 style="margin-left: 30px;">
   <thead>
    <tr>
     <th colspan="4">Table 5 - align values</th>
    </tr>
   </thead>
   <tbody>
    <tr>
     <th> </th>
     <th><code>vertical</code> 省略時</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>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>

<p> </p>

<h3 id="文字內容">文字內容</h3>

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

<p>文字內容中不能包含「<code>--&gt;」字串、「</code>&amp;」符號或「&lt;」符號。如欲使用後兩者，可採跳脫字串「&amp;amp;」或「&amp;lt;」。此外雖規格上允許使用「&gt;」字元，仍然建議跳脫為「&amp;gt;」以避免混淆。若您使用 WebVTT 檔作為後設資料，則可不管這些限制。</p>

<p>除了上述的三個跳脫字串外，還有其他四種跳脫字串，分列如下</p>

<table>
 <thead>
  <tr>
   <th colspan="3">Table 6 - 跳脫字串</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <th>名稱</th>
   <th>字元</th>
   <th>跳脫字串</th>
  </tr>
  <tr>
   <td>「與」</td>
   <td>&amp;</td>
   <td><code>&amp;amp;</code></td>
  </tr>
  <tr>
   <td>小於</td>
   <td>&lt;</td>
   <td><code>&amp;lt;</code></td>
  </tr>
  <tr>
   <td>大於</td>
   <td>&gt;</td>
   <td><code>&amp;gt;</code></td>
  </tr>
  <tr>
   <td>左到右標記</td>
   <td> </td>
   <td><code>&amp;lrm;</code></td>
  </tr>
  <tr>
   <td>右到左標記</td>
   <td> </td>
   <td><code>&amp;rlm;</code></td>
  </tr>
  <tr>
   <td>不斷行空白</td>
   <td><code> </code></td>
   <td><code>&amp;nbsp;</code></td>
  </tr>
 </tbody>
</table>

<p> </p>

<h3 id="文字內容中的標籤">文字內容中的標籤</h3>

<p>有很多標籤（例如 <code>&lt;bold&gt;</code>）可以用在文字內容中，但若 {{ HTMLElement("track") }} 的 {{ htmlattrxref("kind") }} 設定為 <code>chapters</code> 時，其中所用的 WebVTT  檔案裡就不能使用標籤。</p>

<ul>
 <li><strong>時間標籤</strong>

  <ul>
   <li>時間標籤中的時間，必須比該節點的開始時間晚、比同節點先前之其他時間標籤晚，並且早於該節點的結束時間。<em>當前文字（active text）</em> 代表此時間標籤到下個時間標籤（或文字內容的結尾）之間的文字，其他同節點中，比<em>當前文字</em> 早的文字都稱為<em>先前文字（previous text）</em> ，而晚於<em>當前文字</em> 的便稱為<em>未來文字（future text）</em> 。如此便可做出卡拉OK字幕效果</li>
  </ul>

  <div style="margin-left: 30px;">
  <h5 id="Example_12_-_Karaoke_style_text">Example 12 - Karaoke style text</h5>

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

<p>以下則需要開頭標籤與結束標籤（例如 <code>&lt;b&gt;text&lt;/b&gt;</code>）。</p>

<ul>
 <li><strong>Class 標籤</strong>（<code>&lt;c&gt;&lt;/c&gt;</code>）

  <ul>
   <li>以 CSS 類別為該段文字設定樣式</li>
  </ul>

  <div style="margin-left: 30px;">
  <h5 id="Example_14_-_Class_tag">Example 14 - Class tag</h5>

  <pre>&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 style="margin-left: 30px;">
  <h5 id="Example_15_-_Italics_tag">Example 15 - Italics tag</h5>

  <pre>&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 style="margin-left: 30px;">
  <h5 id="Example_16_-_Bold_tag">Example 16 - Bold tag</h5>

  <pre>&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 style="margin-left: 30px;">
  <h5 id="Example_17_-_Underline_tag">Example 17 - Underline tag</h5>

  <pre>&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="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li>
  </ul>

  <div style="margin-left: 30px;">
  <h5 id="Example_18_-_Ruby_tag">Example 18 - Ruby tag</h5>

  <pre>&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="http://en.wikipedia.org/wiki/Ruby_character">ruby characters</a> (i.e. small annotative characters above other characters).</li>
  </ul>

  <div style="margin-left: 30px;">
  <h5 id="Example_19_-_Ruby_text_tag">Example 19 - Ruby text tag</h5>

  <pre>&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 style="margin-left: 30px;">
  <h5 id="Example_20_-_Voice_tag">Example 20 - Voice tag</h5>

  <pre>&lt;v Bob&gt;text&lt;/v&gt;</pre>
  </div>
 </li>
</ul>

<p> </p>

<h2 id="瀏覽器支援">瀏覽器支援</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>基本支援</td>
   <td>18 以上</td>
   <td>24 (<a href="https://wiki.mozilla.org/WebVTT" title="https://wiki.mozilla.org/WebVTT">預設為關閉</a>)</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>基本支援</td>
   <td>4.4 以上</td>
   <td>       目前尚不支援</td>
   <td>         35.0 以上</td>
   <td>   21.0 以上</td>
   <td>7 以上</td>
  </tr>
 </tbody>
</table>

<p> </p>

<p> </p>
</div>

<h2 id="規格">規格</h2>

<ul>
 <li><a class="external" href="http://dev.w3.org/html5/webvtt/" title="http://dev.w3.org/html5/webvtt/">http://dev.w3.org/html5/webvtt/</a></li>
</ul>