1. Web
  2. Web API
  3. WebVTT API
  4. Web 影片文字軌道格式 (WebVTT)

Web 影片文字軌道格式 (WebVTT)

Baseline 已廣泛支援

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

Web 影片文字軌道格式 (WebVTT) 是一種純文字檔案格式，用於顯示與 <video> 和 <audio> 元素中的內容同步的定時文字軌道。例如，這些可用於為 <video> 新增隱藏式字幕和字幕文字疊加。

與媒體元素關聯的 WebVTT 檔案使用 <track> 元素新增——請參閱顯示檔案中定義的 VTT 內容。一個媒體元素可以與多個檔案關聯，每個檔案代表不同型別的定時資料，例如隱藏式字幕、字幕或章節標題，並翻譯成不同的語言環境。

注意： WebVTT 內容也可以使用 WebVTT API 透過程式設計方式建立和管理。

概述

WebVTT 檔案的 MIME 型別為 text/vtt，副檔名為 .vtt。內容必須使用 UTF-8 編碼。

WebVTT 的結構由以下元件組成，其中一些是可選的，按此順序排列

  • 一個標頭，由一個可選的位元組順序標記 (BOM)——字串 WEBVTT——後跟一個可選的文字標頭組成，該標頭由一個或多個空格或製表符分隔（在 WebVTT 檔案中，製表符和空格可以互換）。
  • 一個或多個空行，每個空行相當於兩個連續的換行符。
  • 零個或多個 STYLE、REGION 或 NOTE 塊，由一個或多個空行分隔。
  • 零個或多個提示或 NOTE 塊，由一個或多個空行分隔。

下面顯示了一個簡單的 WebVTT 檔案，其中包含 WEBVTT 字串（但沒有標頭文字）、一個 NOTE 塊和兩個提示。

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.

以下各節解釋了檔案的各個部分，包括上面示例中未使用的部分。

WebVTT 標頭

WebVTT 檔案以包含以下內容的標頭塊開頭

  • 一個可選的位元組順序標記 (BOM)，它是 Unicode 字元 U+FEFF。
  • 字串 WEBVTT。
  • WEBVTT 右側的可選文字標頭。
    • WEBVTT 後必須至少有一個空格。
    • 您可以使用此標頭向檔案新增描述。
    • 您可以在文字標頭中使用除換行符或字串 --> 之外的任何內容。

WEBVTT 字串是 WebVTT 檔案中唯一必需的部分，因此最簡單的 WebVTT 檔案如下所示

WEBVTT

以下示例顯示了帶文字的標頭。請注意，此文字必須至少由一個空格或製表符分隔。

WEBVTT This file has no cues.

WebVTT 提示

提示定義了在特定時間間隔內顯示單個字幕、副標題或其他文字塊。提示必須出現在標頭和任何 STYLE 或 REGION 塊之後。

每個提示由三行或更多行組成

  • 一個可選的提示識別符號，後跟一個換行符。
  • 提示計時，指示有效載荷文字應顯示的時間範圍。這些可選地後跟提示設定，在第一個設定之前和每個設定之間至少有一個空格，後跟一個換行符。
  • 提示有效載荷文字，可以跨多行，並以空行終止。

這是一個簡單提示的示例。第一行指定了提示的顯示開始時間和結束時間，使用字串 --> 分隔。第二行定義了要顯示的文字。

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

下一個提示稍微複雜一些。它以一個提示識別符號開頭——1 - Title Crawl——這可用於在 JavaScript 和 CSS 中引用該提示。它還在提示計時之後有提示設定，用於設定提示位置。

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.

請注意，輸出將尊重有效載荷文字中的換行符，這允許您使用連字元 (-) 字元建立專案列表，如所示。通常，您只應在需要時插入這些換行符，因為瀏覽器會適當地換行。

重要的是不要在提示中使用“額外”空行，例如在計時行和提示有效載荷之間，或在有效載荷內。這是因為空行將結束當前提示。

提示的每個部分將在以下各節中更詳細地解釋。

提示識別符號

識別符號是標識提示的名稱。它可用於從 JavaScript 或 CSS 引用提示。它不能包含換行符，也不能包含字串 -->。它必須以單個換行符結尾。識別符號不必是唯一的，儘管通常對其進行編號（例如 1、2、3）。

以下示例顯示了一個包含多個帶識別符號的提示的檔案

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

提示計時

提示計時指示提示顯示的時間間隔。它有一個開始時間和結束時間，由時間戳表示。結束時間必須大於開始時間，開始時間必須大於或等於所有以前的開始時間。

提示可能具有重疊的計時，除非 WebVTT 檔案用於章節（<track> kind 是 chapters）。

每個提示計時包含五個元件

  • 開始時間的時間戳。
  • 至少一個空格。
  • 字串 -->。
  • 至少一個空格。
  • 結束時間的時間戳，必須大於開始時間。

時間戳可以以下兩種格式之一指定

  • mm:ss.ttt
  • hh:mm:ss.ttt

其中元件定義如下

hh

表示小時，必須至少為兩位數。它可以大於兩位數（例如 9999:00:00.000）。

mm

表示分鐘，必須介於 00 和 59 之間（含）。

ss

表示秒，必須介於 00 和 59 之間（含）。

ttt

表示毫秒，必須介於 000 和 999 之間（含）。

以下是一些提示計時示例

  • 基本提示計時示例

    00:00:22.230 --> 00:00:24.606
00:00:30.739 --> 00:00:34.074
00:00:34.159 --> 00:00:35.743
00:00:35.827 --> 00:00:40.122

  • 重疊提示計時示例

    00:00:00.000 --> 00:00:10.000
00:00:05.000 --> 00:01:00.000
00:00:30.000 --> 00:00:50.000

  • 非重疊提示計時示例

    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

提示設定

提示設定是可選元件，用於將提示有效載荷文字定位在影片上方。這包括水平和垂直位置。可以指定零個或多個提示設定，並以任何順序使用，只要每個設定最多使用一次。

提示設定新增到提示計時的右側。提示計時和第一個設定之間以及每個設定之間必須有一個或多個空格。冒號分隔設定的名稱和值。設定區分大小寫；使用所示的小寫字母。有五個可用的提示設定

vertical

表示文字將垂直而不是水平顯示，例如在某些亞洲語言中。有兩個可能的值

rl

書寫方向是從右到左。

lr

書寫方向是從左到右。

line

如果未設定 vertical，則 line 指定文字垂直顯示的位置。如果設定了 vertical，則 line 指定文字水平顯示的位置。其值可以是

行號

提示的第一行在影片上顯示的位置。正數從上往下計數，負數從下往上計數。

百分比

一個介於 0 到 100 之間（含）的整數（即沒有小數），後跟一個百分號 (%)。

行 vertical 省略 vertical:rl vertical:lr
line:0 top right left
line:-1 bottom left right
line:0% top right left
line:100% bottom left right
position

如果未設定 vertical，則 position 指定文字水平顯示的位置。如果設定了 vertical，則 position 指定文字垂直顯示的位置。該值是一個介於 0 到 100 之間（含）的百分比。

位置 vertical 省略 vertical:rl vertical:lr
position:0% left top top
position:100% right bottom bottom
size

如果未設定 vertical，則 size 指定文字區域的寬度。如果設定了 vertical，則 size 指定文字區域的高度。該值是一個介於 0 到 100 之間（含）的百分比。

大小 vertical 省略 vertical:rl vertical:lr
size:100% 全寬 全高 全高
size:50% 半寬 半高 半高
align

指定文字的對齊方式。如果設定了 size 提示設定，文字將在其提供的空間內對齊。

對齊 vertical 省略 vertical:rl vertical:lr
align:start left top top
align:center 水平居中 垂直居中 垂直居中
align:end right bottom bottom

以下是一些示例。第一行演示沒有設定。第二行可能用於在標誌或標籤上疊加文字。第三行可能用於標題。最後一行可能用於亞洲語言。

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%

提示有效載荷

有效載荷是定義提示內容（例如字幕或隱藏式字幕文字）的地方。它可能包含換行符，但不能包含兩個連續的換行符：那將建立一個空行，表示塊的結束。

提示文字有效載荷不能包含字串 -->、和號字元 (&) 或小於號 (<)。如果需要，您可以使用字元引用，例如和號的命名字元引用 &amp; 和小於號的 &lt;。還建議您使用大於號轉義序列 &gt; 而不是大於號字元 (>)，以避免與標籤混淆。如果您將 WebVTT 檔案用於元資料，則這些限制不適用。

請注意，所有主流瀏覽器都允許在提示、註釋或其他文字中使用任何字元引用。舊版瀏覽器可能只支援以下命名字元引用子集

名稱 字元 轉義序列
和號 & &amp;
小於號 < &lt;
大於號 > &gt;
從左到右標記 none &lrm;
從右到左標記 none &rlm;
不間斷空格 &nbsp;

提示有效載荷文字標籤

許多標籤，例如 <b>，可用於在提示中標記和樣式化文字。但是，如果 WebVTT 檔案用於 <track> 元素，並且屬性 kind 是 chapters，則不能使用標籤。

時間戳標籤

時間戳標籤用於啟用卡拉 OK 風格的字幕。時間戳必須大於提示的開始時間戳，大於提示有效載荷中任何先前的時間戳，並且小於提示的結束時間戳。活動文字是時間戳和下一個時間戳之間的文字，如果有效載荷中沒有其他時間戳，則到有效載荷的末尾。有效載荷中活動文字之前的任何文字是先前文字。活動文字之外的任何文字是未來文字。

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

以下標籤是提示中允許的 HTML 標籤，並且需要開標籤和閉標籤（例如，<b>text</b>）。用這些標籤標記的文字可以在STYLE 塊中使用 ::cue 偽元素進行格式化。

斜體標籤 (<i></i>)

使包含的文字變為斜體。

xml
<i>text</i>
粗體標籤 (<b></b>)

使包含的文字變為粗體。

xml
<b>text</b>
下劃線標籤 (<u></u>)

為包含的文字新增下劃線。

xml
<u>text</u>
類標籤 (<c></c>)

為包含的文字新增一個類，以便透過 CSS 進行選擇。

xml
<c.classname>text</c>
注音標籤 (<ruby></ruby>)

與注音文本標籤一起使用，以顯示注音字元（即，其他字元上方的小注釋字元）。

xml
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
注音文本標籤 (<rt></rt>)

與注音標籤一起使用，以顯示注音字元（即，其他字元上方的小注釋字元）。

xml
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
語音標籤 (<v></v>)

類似於類標籤，也用於使用 CSS 樣式化包含的文字。

xml
<v Bob>text</v>
語言標籤 (<lang></lang>)

用於突出顯示已標記為屬於特定語言或語言變體的文字，使用 BCP 47 語言標籤格式。

xml
<lang en-GB>English text as spoken in Great Britain!</lang>

NOTE 塊

NOTE 塊是可選部分，可用於向 WebVTT 檔案添加註釋。它們是供閱讀檔案的人使用的，使用者看不到。例如，您可以使用它們來記錄作者聯絡方式、提供結構概述或為仍需要編寫的提示新增佔位符。

它們可以用於 WebVTT 檔案中標題之後的任何位置。

NOTE 塊可以包含換行符，但不能包含兩個連續的換行符：那將建立一個空行，表示塊的結束。

註釋不能包含字串 -->、和號字元 (&) 或小於號 (<)。如果您希望使用這些字元，則需要使用字元引用，例如和號的 &amp; 和小於號的 &lt;。還建議您使用大於號轉義序列 (&gt;) 而不是大於號字元 (>)，以避免與標籤混淆。

註釋由三部分組成

  • 字串 NOTE。
  • 一個空格或一個新行。
  • 零個或多個除上述字元以外的字元。

以下是一些示例

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 塊

STYLE 塊是可選部分，可用於在 WebVTT 檔案中嵌入提示的 CSS 樣式。請注意，這些用於樣式化提示的外觀和大小，而不是其位置和佈局，這些由提示設定控制。

注意： WebVTT 提示也可以透過關聯的嵌入影片/音訊元素的文件載入的 CSS 樣式進行匹配。

STYLE 塊必須出現在檔案中任何提示塊之前。

每個塊由以下行組成

  • 字串 STYLE 後跟零個或多個空格或製表符，然後是換行符。
  • 一個字串，使用 ::cue 偽元素定義要匹配和應用的 CSS 樣式。

塊不能包含字串 -->。它可能包含換行符，但不能包含兩個連續的換行符：那將建立一個空行，表示塊的結束。

下面顯示了一個帶有兩個 STYLE 塊的簡單 WebVTT 檔案。它使用 ::cue 將文字顏色應用於所有提示文字，並將不同的文字顏色僅應用於帶有 <b></b> 標籤的文字。

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.

注意： 在 WebVTT API 的更多提示樣式示例中，有演示許多以下情況的即時示例。

匹配所有提示有效載荷文字

使用 ::cue 匹配所有提示有效載荷文字。

例如，以下 STYLE 塊將匹配所有提示文字並將其著色為黃色。

STYLE
::cue {
  color: yellow;
}

匹配標籤型別

透過在 ::cue() 中指定標籤作為型別選擇器，匹配用特定提示有效載荷文字標籤（例如 c、i、b、u、ruby、rt、v 和 lang）標記的提示文字。

例如，以下塊會將用 lang 標記的提示有效載荷文字匹配為黃色，並將其他每個標籤匹配為紅色。

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

匹配類選擇器

匹配 ::cue() 中使用類選擇器標記的所有標籤。

以下 WebVTT 檔案中的 STYLE 塊將匹配其後的所有文字，因為所有標籤都具有 myclass 類。

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>

要選擇特定的標籤和類，您必須在 ::cue() 中同時指定兩者

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

匹配屬性

用特定標籤和屬性標記的提示有效載荷文字可以使用屬性選擇器進行匹配。

例如，考慮以下 WebVTT 檔案，其中文字使用 v 和 lang 提示有效載荷文字標籤進行標記，並使用屬性指定特定的語音（“Salame”）和語言。

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>

使用偽類匹配

前面的示例使用屬性匹配為特定語言的文字設定樣式。您還可以使用 :lang() 偽類匹配語言，如下面的 STYLE 塊所示。

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

您可以類似地與 :past 和 :future 偽類匹配，以提供卡拉 OK 般的體驗。

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

其他偽類，如 link、nth-last-child 和 nth-child 應該類似地工作。

匹配提示 ID

透過在 ::cue() 中指定 id 來匹配特定的提示 id。

注意： 在撰寫本文時，這似乎在任何主流瀏覽器中都不受支援。

例如，以下 WebVTT 檔案應將識別符號為 cue1 的提示樣式設定為綠色。

WEBVTT

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

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

請注意，WebVTT CSS 中的轉義序列與 HTML 頁面中的使用方式相同。以下示例演示瞭如何轉義提示識別符號中的空格

WEBVTT

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

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

規範

規範
WebVTT：網頁影片文字軌道格式

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ，由 MDN 貢獻者。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.