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.