WebVTT API

**Web 视频文本轨道**（**WebVTT**）是文本轨道，提供与其他媒体（如视频或音频轨道）时间对齐的特定文本“提示”。**WebVTT API** 提供了定义和操作这些文本轨道的功能。WebVTT API 主要用于显示覆盖视频内容的字幕或隐藏式字幕，但它还有其他用途：提供章节信息以方便导航以及需要与音频或视频内容时间对齐的通用元数据。

概念和用法

文本轨道是时间对齐文本数据的容器，可以与视频或音频轨道并行播放，以提供内容的翻译、转录或概述。视频或音频媒体元素可以定义不同类型或不同语言的轨道，允许用户根据自己的偏好或需求显示相应的轨道。

可以指定的不同类型的文本数据列在下面。请注意，浏览器不一定支持所有类型的文本轨道。

subtitles 提供口语对话的文本翻译。这是文本轨道的默认类型，如果使用，则必须指定源语言。
captions 提供口语文本的转录，可能包括有关其他音频（如音乐或背景噪音）的信息。它们适用于听力障碍用户。
chapters 提供高级导航信息，使用户能够更轻松地切换到相关内容。
metadata 用于任何其他类型的时间对齐信息。

轨道内时间对齐的文本数据单元称为“提示”。每个提示都有开始时间、结束时间和文本有效负载。它还可以具有“提示设置”，这些设置会影响其显示区域、位置、对齐方式和/或大小。最后，提示可以有一个标签，该标签可用于选择它进行 CSS 样式设置。

可以使用 WebVTT 文件格式在文件中定义文本轨道和提示，然后使用 <track> 元素将其与特定的 <video> 元素关联。

或者，您可以使用 HTMLMediaElement.addTextTrack() 在 JavaScript 中向媒体元素添加 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 实例表示。

示例

使用 WebVTT API 添加隐藏式字幕

HTML

以下示例向视频添加新的 TextTrack，然后使用 TextTrack.addCue() 方法调用添加提示，并使用构造的 VTTCue 对象作为参数。

html

<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video>

CSS

css

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

JavaScript

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 文件格式中定义样式。

HTML

视频本身的 HTML 与我们之前看到的相同

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

html

<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-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 也将文本样式分别设置为绿色和紫色。

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 和 CSS 与上面第一个示例相同，因此此处我们仅显示标记和设置文本样式的特定代码。

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

<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video>

按标签类型设置样式

我们将创建的第一个提示将在视频的全部 6 秒内显示，并显示使用 b、u、i 和 c 标签标记的文本。

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: lightpurple;
}

按类设置样式

第二个提示紧随第一个提示之后显示，并包含相同的标签。但是，它们都应用了 myclass 类。

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;
}

使用属性设置样式

接下来的两个提示分别在 2 秒和 3 秒后显示。第一个显示使用 lang 标签标记的三个英语语言环境的文本，而第二个显示具有“Bob”属性的 <v>（语音）标签。

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：Web 视频文本轨道格式 # the-vttcue-接口
HTML 标准 # 文本轨道
WebVTT：Web 视频文本轨道格式 # the-vttregion-接口

CSS 的::cue 和 ::cue()伪元素

WebVTT API

概念和用法

接口

相关接口

相关 CSS 扩展

示例

使用 WebVTT API 添加隐藏式字幕

HTML

CSS

JavaScript

结果

显示在文件中定义的 VTT 内容

在 HTML 或样式表中设置 WebVTT 样式

HTML

CSS

JavaScript

结果

更多提示样式示例

按标签类型设置样式

按类设置样式

使用属性设置样式

结果

规范

浏览器兼容性

api.VTTCue

api.TextTrack

api.VTTRegion

另请参阅