Web 视频文本轨道格式 (WebVTT)

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 文件以包含以下内容的标头块开头

• 一个可选的字节顺序标记 (BOM)，即 Unicode 字符 U+FEFF。
• 字符串“WEBVTT”。
• WEBVTT 右侧的可选文本标头。
  • WEBVTT 后必须至少有一个空格。
  • 您可以使用此标头向文件添加说明。
  • 您可以在文本标头中使用任何内容，但换行符或字符串“-->”除外。

WEBVTT 字符串是 WebVTT 文件中唯一必需的部分，因此最简单的 WebVTT 文件如下所示

WEBVTT

以下示例显示了一个带文本的标头。请注意，此文本必须用至少一个空格或制表符分隔。

WEBVTT This file has no cues.

提示定义单个字幕、字幕或其他文本块，以便在特定时间间隔内显示。提示必须出现在标头和任何 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	顶部	右侧	左侧
line:-1	底部	左侧	右侧
line:0%	顶部	右侧	左侧
line:100%	底部	左侧	右侧

position

如果未设置 vertical，则 position 指定文本在水平方向上的显示位置。如果设置了 vertical，则 position 指定文本在垂直方向上的显示位置。值为介于 0 和 100（含）之间的百分比。

位置	vertical 未省略	vertical:rl	vertical:lr
position:0%	左侧	顶部	顶部
position:100%	右侧	底部	底部

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	左侧	顶部	顶部
align:center	水平居中	垂直居中	垂直居中
align:end	右侧	底部	底部

以下是一些示例。第一行演示了没有设置。第二行可用于在标志或标签上叠加文本。第三行可用于标题。最后一行可用于亚洲语言。

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%

有效负载是定义提示内容的位置，例如字幕或隐藏式字幕文本。它可以包含换行符，但不能包含两个连续的换行符：这将创建一个空行，表示块的结尾。

提示文本有效负载不能包含字符串 -->、与号 (&) 或小于号 (<)。如果需要，您可以改为使用 字符引用，例如命名字符引用 & 用于与号，< 用于小于号。还建议您使用大于号转义序列 > 而不是大于号 (>) 以避免与标签混淆。如果您将 WebVTT 文件用于元数据，则这些限制不适用。

请注意，所有主流浏览器都允许在提示、注释或其他文本中使用任何字符引用。较旧的浏览器版本可能仅支持以下命名字符引用的子集。

许多标签，例如<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></ruby>)

与 ruby 文本标签一起使用，以显示ruby 字符（即，其他字符上方的较小的注释字符）。

xml

<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>

Ruby 文本标签（<rt></rt>)

与 ruby 标签一起使用，以显示ruby 字符（即，其他字符上方的较小的注释字符）。

xml

<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>

语音标签（<v></v>)

类似于类标签，也用于使用 CSS 设置包含文本的样式。

xml

<v Bob>text</v>

语言标签（<lang></lang>)

用于突出显示已标记为属于特定语言或语言变体的文本，使用 RFC 5646：语言识别标签（也称为 BCP 47） 中定义的格式。

xml

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

NOTE 块是可选部分，可用于向 WebVTT 文件添加注释。它们旨在供读取文件的人员使用，用户看不到。例如，您可以使用它们来记录作者联系信息、提供结构概述或为仍需编写的提示添加占位符。

它们可以在标题后的 WebVTT 文件中的任何位置使用。

NOTE 块可能包含换行符，但不能包含两个连续的换行符：这将创建一个空行，表示块的结束。

注释不能包含字符串-->、和号字符 (&) 或小于号 (<)。如果要使用这些字符，则需要改为使用 字符引用，例如 & 表示和号，< 表示小于号。还建议使用大于号转义序列 (>) 而不是大于号字符 (>)，以避免与标签混淆。

注释由三个部分组成

• 字符串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 块是可选部分，可用于将提示的 CSS 样式嵌入到 WebVTT 文件中。请注意，这些用于设置提示的外观和大小，而不是其位置和布局，位置和布局由 提示设置 控制。

STYLE 块必须出现在文件中的任何提示块之前。

每个块包含以下行

• 字符串 STYLE 后跟零个或多个空格或制表符，然后是一个换行符。
• 一个字符串，用于定义要匹配和应用的 CSS 样式，使用 ::cue 伪元素。

块不能包含字符串 -->。它可能包含换行符，但不能包含两个连续的换行符：这将创建一个空行，表示块的结束。

下面显示了一个带有两个 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.

使用 ::cue 匹配所有提示有效载荷文本。

例如，以下 STYLE 块将匹配所有提示文本并将其颜色设置为黄色。

STYLE
cue {
  color: yellow;
}

匹配使用特定 提示有效载荷文本标签（如 c、i、b、u、ruby、rt、v 和 lang）标记的提示文本，方法是在 ::cue() 中将标签指定为类型选择器。

例如，以下块将把使用 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() 中同时指定两者。

STYLE ::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 的体验。

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

其他伪类（如 link、nth-last-child 和 nth-child）应该以类似的方式工作。

通过在 ::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(#crédit\ de\ transcription) {
  color: red;
}

crédit de transcription
00:04.000 --> 00:05.000
Transcrit par Célestes™

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