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 上查看此页面 • 报告此内容的错误