1. Web
  2. Web API
  3. WebVTT API

WebVTT API

Web Video Text Tracks (WebVTT) 是文字軌道，提供與影片或音訊軌道等其他媒體同步的特定文字“提示”。WebVTT API 提供了定義和操作這些文字軌道的函式。WebVTT API 主要用於顯示疊加在影片內容上的字幕或說明，但也有其他用途：提供章節資訊以便於導航，以及需要與音訊或影片內容同步的通用元資料。

概念與用法

文字軌道是同步文字資料的容器，可以與影片或音訊軌道並行播放，以提供內容的翻譯、轉錄或概述。影片或音訊媒體元素可以定義不同種類或不同語言的軌道，允許使用者根據自己的偏好或需求顯示合適的軌道。

可以指定的文字資料種類包括 captions（字幕）、descriptions（描述）、chapters（章節）、subtitles（副標題）或 metadata（元資料）；<track> 文件中有更多關於這些含義的資訊。請注意，瀏覽器不一定支援所有種類的文字軌道。

軌道內的單個同步文字資料單元稱為“提示”。每個提示都有開始時間、結束時間和文字內容。它還可以有“提示設定”，影響其顯示區域、位置、對齊方式和/或大小。最後，一個提示可以有一個標籤，用於選擇它進行 CSS 樣式設定。

可以使用 WebVTT 檔案格式 在檔案中定義文字軌道和提示，然後使用 <track> 元素將其與特定的 <video> 元素關聯起來。

或者，您可以使用 JavaScript 透過 HTMLMediaElement.addTextTrack() 將 TextTrack 新增到媒體元素，然後使用 TextTrack.addCue() 將單個 VTTCue 物件新增到軌道中。

::cue CSS 偽元素 可在 HTML 和 WebVTT 檔案中使用，以樣式化特定元素的提示、提示中的特定標籤、VTT 類或帶有特定標籤的提示。::cue-region 偽元素用於樣式化特定區域的提示，但目前不受任何瀏覽器支援。

大多數重要的 WebVTT 功能都可以透過檔案格式或 Web API 訪問。

介面

VTTCue

表示提示，即與媒體元素關聯的文字軌道在特定時間段內顯示的文字。

VTTRegion

表示影片元素的一部分，VTTCue 可以渲染到其中。

TextTrack

表示一個文字軌道，它包含要顯示在播放時與相關媒體元素在不同時間點一起顯示的提示列表。

TextTrackCue

各種提示型別的抽象基類，例如 VTTCue。

TextTrackCueList

一個類陣列物件，表示一個動態更新的 TextTrackCue 物件列表。可以透過 TextTrack.cues 獲取此型別的例項，以獲取 TextTrack 物件中的所有提示。

TextTrackList

表示媒體元素定義的文字軌道列表，列表中的每個軌道由一個單獨的 TextTrack 例項表示。

TrackEvent

作為 HTML DOM API 的一部分，這是 addtrack 和 removetrack 事件的介面，當軌道被新增到 TextTrackList（或更普遍地說，當軌道被新增到/從 HTML 媒體元素中移除時）時觸發。

這些 CSS 偽元素 用於為帶有 VTT 軌道的媒體中的提示設定樣式。

::cue

匹配帶有 VTT 軌道的媒體中選定元素內的提示。

注意： 規範還定義了另一個偽元素 ::cue-region，但目前沒有任何瀏覽器支援它。

示例

使用 WebVTT API 新增字幕

HTML

以下示例向影片添加了一個新的 TextTrack，然後使用 TextTrack.addCue() 方法呼叫新增提示，引數為構造的 VTTCue 物件。

html
<video controls src="/shared-assets/videos/friday.mp4"></video>

CSS

css
video {
  width: 420px;
  height: 300px;
}

JavaScript

js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(new VTTCue(1.5, 2.9, "Tell me, is the lord of the universe in?"));
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(new VTTCue(4.3, 6, "Somebody must've stolen the crown jewels"));
console.log(track.cues);

結果

顯示檔案中定義的 VTT 內容

此示例演示瞭如何將與上面“使用 WebVTT API 新增字幕”示例中相同的字幕集新增到影片中。但是，這次我們將使用 <track> 元素以宣告方式進行。

首先，我們在“captions.vtt”檔案中定義字幕

WEBVTT

00:00.000 --> 00:00.900
Hildy!

00:01.000 --> 00:01.400
How are you?

00:01.500 --> 00:02.900
Tell me, is the lord of the universe in?

00:03.000 --> 00:04.200
Yes, he's in - in a bad humor

00:04.300 --> 00:06.000
Somebody must've stolen the crown jewels

然後，我們可以使用 <track> 元素將其新增到 <video> 元素中。以下 HTML 將產生與上一個示例相同的文字軌道

html
<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" srclang="en" />
</video>

我們可以新增多個 <track> 元素，使用 kind 和 srclang 屬性來指定不同種類的軌道和多種語言。請注意，如果指定了 kind，則 srclang 必須也一併設定。default 屬性只能新增到單個 <track> 上：當用戶偏好未指定特定語言或種類時，將播放此軌道。

html
<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" srclang="en" />
  <track kind="subtitles" src="subtitles.vtt" srclang="en" />
  <track kind="descriptions" src="descriptions.vtt" srclang="en" />
  <track kind="chapters" src="chapters_de.vtt" srclang="de" />
  <track kind="subtitles" src="subtitles_en.vtt" srclang="en" />
</video>

在 HTML 或樣式表中設定 WebVTT 樣式

您可以透過使用 ::cue 偽元素匹配元素來設定 WebVTT 提示的樣式。這允許您修改所有提示文字或僅特定元素的顯示外觀。在此示例中，我們將為上面“使用 WebVTT API 新增字幕”的第一個示例新增一些樣式。

注意：也可以在 WebVTT 檔案格式 中定義樣式。

HTML

影片本身的 HTML 與我們之前看到的相同

html
<video controls src="/shared-assets/videos/friday.mp4"></video>

CSS

首先，我們使用 ::cue 偽元素來選擇所有影片文字提示，讓它們變得更大，並帶有紅色和漸變背景。

css
video::cue {
  font-size: 1.5rem;
  background-image: linear-gradient(to bottom, yellow, lightyellow);
  color: red;
}

然後，我們使用 ::cue 選擇使用 u 和 b 元素標記的文字，並分別將它們樣式化為綠色和黃色。

css
video::cue(u) {
  color: green;
}

video::cue(b) {
  color: purple;
}

JavaScript

JavaScript 與第一個示例相同，只是我們使用 <b>（粗體）和 <u>（下劃線）標籤標記了部分提示文字。預設情況下，標記的文字將顯示為粗體或下劃線（取決於標籤），但我們在上一節使用了 ::cue 來將文字分別樣式化為綠色和紫色。

js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(
  new VTTCue(1.5, 2.9, "Tell me, is the <u>lord of the universe</u> in?"),
);
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(
  new VTTCue(4.3, 6, "Somebody must've <b>stolen</b> the crown jewels"),
);
console.log(track.cues);

結果

更多提示樣式示例

此示例展示了更多關於如何使用標籤標記提示文字然後進行樣式設定的示例。相同的標記和樣式也可用於 WebVTT 檔案格式。

用於顯示影片本身的 HTML 與上面“使用 WebVTT API 新增字幕”的第一個示例相同，因此我們在此僅顯示用於標記和設定文字樣式的特定程式碼。

按標籤型別設定樣式

我們建立的第一個提示將在影片的全部 6 秒內顯示，並顯示用 b、u、i 和 c 標籤標記的文字。

js
let video = document.querySelector("video");

let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

track.addCue(
  new VTTCue(
    0,
    6,
    "Styles: Normal <b>bold</b> <u>underlined</u> <i>italic</i> <c>class</c>",
  ),
);

首先，我們將新增一條規則，使所有提示比正常大小大 1.2 倍。

css
video::cue {
  font-size: 1.2rem;
}

然後，我們為上述每個標籤設定不同的顏色。

css
video::cue(u) {
  color: green;
}

video::cue(b) {
  color: purple;
}

video::cue(i) {
  color: red;
}

video::cue(c) {
  color: lavender;
}

按類設定樣式

第二個提示在第一個提示之後立即顯示，幷包含相同的標籤。但是，它們都應用了 myclass 類。

js
track.addCue(
  new VTTCue(
    1,
    6,
    "Styles: Class markup: <b.myclass>bold</b> <u.myclass>underlined</u> <i.myclass>italic</i> <c.myclass>class</c>",
  ),
);

我們將所有帶有 .myclass 類的專案設定為淺藍色文字顏色，除了 c.myclass 的特定情況，該情況設定為藍色文字顏色。

css
video::cue(.myclass) {
  color: lightblue;
}

video::cue(c.myclass) {
  color: blue;
}

使用屬性設定樣式

接下來的兩個提示分別在兩秒和三秒後顯示。第一個顯示用 lang 標籤標記的文字，用於三種英語方言；第二個顯示帶有“Bob”屬性的 <v>（語音）標籤。

js
track.addCue(
  new VTTCue(
    2,
    6,
    "<lang en>Lang markup: 'en'</lang>  <lang en-GB>Text: 'en-GB'</lang> <lang en-US>Text: 'en-US'</lang>",
  ),
);

track.addCue(new VTTCue(3, 6, "<v Bob>Bob's voice</v>"));

我們使用 lang 屬性選擇器為每種語言變體設定不同的文字顏色。

css
video::cue([lang="en"]) {
  color: lightgreen;
}

video::cue([lang="en-GB"]) {
  color: darkgreen;
}

video::cue(:lang(en-US)) {
  color: #6082b6;
}

然後，我們使用 v 標籤和 voice 的屬性選擇器，將“Bob 的聲音”中的文字顏色設定為橙色。

css
video::cue(v[voice="Bob"]) {
  color: orange;
}

結果

示例應顯示與上述樣式匹配的彩色提示（如果文字未著色，則表示您的瀏覽器不支援 ::cue）。

規範

規範
WebVTT：網頁影片文字軌道格式
# the-vttcue-interface
WebVTT：網頁影片文字軌道格式
# the-vttregion-interface
HTML
# texttrack

瀏覽器相容性

api.VTTCue

api.TextTrack

api.VTTRegion

另見

幫助改進 MDN

瞭解如何貢獻

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

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