文本轨道是 HTML5 的一项功能，用于向终端用户显示时间触发的文本。Video.js 提供了跨浏览器实现的文本轨道。

关于“远程”文本轨道的注意事项

Video.js 引用了所谓的“远程”文本轨道。这是一个方便的术语，指那些关联了 <track> 元素的轨道，而不是没有关联的轨道。

两者都可以通过编程方式创建，但**只有远程文本轨道可以从播放器中删除。**因此，我们建议**只**使用远程文本轨道。

创建文本文件

定时文本需要 WebVTT 格式的文本文件。此格式定义了一个“提示”列表，每个提示都有一个开始时间、一个结束时间和要显示的文本。 Microsoft 提供了一个构建器，可以帮助您开始制作文件。

注意： 创建字幕时，还有其他字幕格式化技术，可以使字幕更具意义，例如声音效果周围的括号（例如 [ birds chirping ]）。

有关字幕的更深入样式指南，请参阅 Captioning Key，但请记住，并非所有功能都受 WebVTT 或（更可能）Video.js WebVTT 实现的支持。

将文本轨道添加到 Video.js

创建 WebVTT 文件后，可以使用 track 标签将其添加到 video 元素中。与 source 元素类似，track 元素应作为 video 元素的子元素添加。

<video
  class="video-js"
  controls
  preload="auto"
  width="640"
  height="264"
  data-setup='{}'>
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
  <track kind="captions" src="//example.com/path/to/captions.vtt" srclang="en" label="English" default>
</video>

Video.js 会自动从 video 元素中读取 track 元素。轨道（远程和非远程）也可以通过编程方式添加。

track 属性

kind

标准定义

Video.js 支持的轨道类型之一

• "subtitles"（默认）：视频中对话的翻译，用于音频可用但无法理解的情况。字幕显示在视频上方。
• "captions"：对话、声音效果、音乐提示和其他音频信息的转录，适用于聋哑/听力障碍观众，或视频静音时。隐藏式字幕也显示在视频上方。
• "chapters"：用于在视频中创建导航的章节标题。通常，这些以章节列表的形式呈现，观众可以使用它们来导航视频。
• "descriptions"：视频内容中动作的文本描述，用于视频部分不可用或观看者失明或不使用屏幕的情况。描述由屏幕阅读器朗读或转换为单独的音轨。
• "metadata"：包含用于 JavaScript 解析并执行某些操作的数据的轨道。这些不会显示给用户。

label

标准定义

轨道的简短描述性文本，将在用户界面中使用。例如，在选择字幕语言的菜单中。

default

标准定义

布尔属性 default 可用于指示轨道模式应以 "showing" 开始。否则，观看者需要从字幕或副标题菜单中选择他们的语言。

注意： 对于章节，如果您希望显示章节菜单，则 default 是必需的。

srclang

标准定义

文本轨道的语言的有效 BCP 47 代码，例如英语为 "en"，西班牙语为 "es"。

有关支持的语言翻译，请参阅 Video.js 根目录中的语言文件夹 (/lang)，并参考语言指南以获取 Video.js 中语言的更多信息。

来自不同域的文本轨道

由于 Video.js 通过 JavaScript 加载文本轨道文件，因此适用同源策略。如果您希望播放器从一个域提供服务，而文本轨道从另一个域提供服务，则需要在提供文本轨道的服务器上启用 CORS。

除了启用 CORS，您还需要将 crossorigin 属性添加到视频元素本身。此属性有两个可能的值 "anonymous" 和 "use-credentials"。大多数用户希望对跨域轨道使用 "anonymous"。

<video class="video-js" crossorigin="anonymous">
  <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
  <track src="//example.com/oceans.vtt" kind="captions" srclang="en" label="English">
</video>

需要注意的是，视频文件本身也**需要** CORS 头。这是因为某些浏览器将 crossorigin 属性应用于视频源本身，而不仅仅是轨道。这被规范视为安全问题。

使用文本轨道

通过编程方式显示轨道

某些用例要求通过编程方式打开和关闭字幕，而不是强制用户自己操作。这可以通过修改文本轨道的 mode 属性轻松实现。

mode 可以是三个值之一："disabled"、"hidden" 和 "showing"。当文本轨道的 mode 为 "disabled" 时，轨道在视频播放时不会显示在屏幕上。

当 mode 设置为 "showing" 时，轨道对观看者可见，并在视频播放时更新。

// Get all text tracks for the current player.
var tracks = player.textTracks();

for (var i = 0; i < tracks.length; i++) {
  var track = tracks[i];

  // Find the English captions track and mark it as "showing".
  if (track.kind === 'captions' && track.language === 'en') {
    track.mode = 'showing';
  }
}

监听提示激活

mode 的受支持值之一是 "hidden"。此 mode 意味着轨道会随视频播放而更新，但对观看者不可见。这对于 kind="metadata" 的轨道最为有用。

元数据文本轨道的一个常见用例是使用它们在提示激活时触发行为。为此，轨道会发出一个 "cuechange" 事件。

// Get all text tracks for the current player.
var tracks = player.textTracks();
var metadataTrack;

for (var i = 0; i < tracks.length; i++) {
  var track = tracks[i];

  // Find the metadata track that's labeled "ads".
  if (track.kind === 'metadata' && track.label === 'ads') {
    track.mode = 'hidden';

    // Store it for usage outside of the loop.
    metadataTrack = track;
  }
}

// Add a listener for the "cuechange" event and start ad playback.
metadataTrack.addEventListener('cuechange', function() {
  player.ads.startLinearAdMode();
});

模拟文本轨道

默认情况下，Video.js 将使用原生文本轨道，如果原生功能损坏、不完整或不存在，则会回退到模拟文本轨道。

Video.js API 和 TextTrack 对象的建模基于 W3C 规范。Video.js 使用 Mozilla 的 vtt.js 库来解析和显示模拟文本轨道。

要禁用原生文本轨道功能并强制 Video.js 始终使用模拟文本轨道，可以将 nativeTextTracks 选项传递给技术组件。

// Create a player, passing `nativeTextTracks: false` to the HTML5 tech.
var player = videojs('myvideo', {
  html5: {
    nativeTextTracks: false
  }
});

文本轨道设置

使用模拟文本轨道时，字幕菜单中会有一个附加项，名为“字幕设置”。这允许用户更改字幕在屏幕上的样式。

可以通过关闭 TextTrackSettings 组件并隐藏菜单项来禁用此功能。

var player = videojs('myvideo', {
  // Make the text track settings dialog not initialize.
  textTrackSettings: false
});

/* Hide the captions settings item from the captions menu. */
.vjs-texttrack-settings {
  display: none;
}

文本轨道优先级

一般来说，"descriptions" 轨道的优先级低于 "captions" 和 "subtitles"。这对于使用 Video.js 的开发者意味着什么？

• 如果您使用 default 属性，Video.js 将选择第一个标记为 default 的轨道并将其打开。如果有多个轨道标记为 default，它将先打开第一个 "captions" 或 "subtitles" 轨道，**然后**再打开任何 "descriptions" 轨道。
  • 这仅适用于模拟文本轨道支持，原生文本轨道的行为会根据浏览器而变化。
• 如果从菜单中选择了一个轨道，Video.js 将关闭所有其他相同类型的轨道。虽然这暗示 Video.js 支持同时开启 "subtitles" 和 "captions"，但目前情况并非如此；Video.js 仅支持一次显示一个轨道。
  • 这意味着对于模拟文本轨道，Video.js 将显示第一个启用的 "subtitles" 或 "captions" 轨道。
  • 当支持原生文本轨道时，其他相同类型的轨道仍将被禁用，但可能显示多个文本轨道。
  • 如果选择了 "descriptions" 轨道，随后又选择了 "subtitles" 或 "captions" 轨道，则 "descriptions" 轨道将被禁用，其菜单按钮也将被禁用。
• 以编程方式启用轨道时，Video.js 执行的强制措施很少。
  • 对于模拟文本轨道，Video.js 选择第一个 "showing" 的轨道——再次优先选择 "subtitles" 或 "captions" 而非 "descriptions"。
  • 对于原生文本轨道，此行为取决于浏览器。某些浏览器将允许同时显示多个文本轨道，但其他浏览器在选择新轨道时将禁用所有其他轨道。

API

有关更完整的信息，请参阅 Video.js API 文档。

远程文本轨道

如上文所述，远程文本轨道代表 Video.js 提供的推荐 API，因为它们可以被移除。

• Player#remoteTextTracks()

• Player#remoteTextTrackEls()

• Player#addRemoteTextTrack(Object options)

  可用选项与可用的 track 属性相同。并且 language 作为 srclang 属性的别名也受支持——两者在此处都有效。

  注意：如果您需要回调，可以使用以下技术代替回调

  const trackEl = player.addRemoteTextTrack({src: 'en.vtt'}, false);
  trackEl.addEventListener('load', function() {
    // your callback goes here
  });

• Player#removeRemoteTextTrack(HTMLTrackElement|TextTrack)

文本轨道

在大多数用例中，通常建议您使用**远程**文本轨道，而不是这些纯粹通过编程方式添加的文本轨道。

• Player#textTracks()

• Player#addTextTrack(String kind, [String label [, String language]])

  注意： 非远程文本轨道仅用于轨道的**纯编程用法**，并且有一个重要的限制：它们**一旦创建就无法删除**。

  标准的 addTextTrack **没有**相应的 removeTextTrack 方法；因此，我们实际上不鼓励使用此方法！

• TextTrackList()

• TextTrack()