HTML：活的标准

Web 开发人员版 — 最后更新于 2024 年 9 月 12 日

1. 1. 1. 4.8.8 video 元素
      2. 4.8.9 audio 元素
      3. 4.8.10 track 元素
      4. 4.8.11 媒体元素
         1. 4.8.11.1 错误代码
         2. 4.8.11.2 媒体资源的位置
         3. 4.8.11.3 MIME 类型
         4. 4.8.11.4 网络状态
         5. 4.8.11.5 加载媒体资源
         6. 4.8.11.6 媒体资源中的偏移量
         7. 4.8.11.7 就绪状态
         8. 4.8.11.8 播放媒体资源
         9. 4.8.11.9 查找
         10. 4.8.11.10 具有多个媒体轨道的媒体资源
             1. 4.8.11.10.1 AudioTrackList 和 VideoTrackList 对象
             2. 4.8.11.10.2 声明式选择特定的音频和视频轨道
         11. 4.8.11.11 定时文本轨道
             1. 4.8.11.11.1 文本轨道模型
             2. 4.8.11.11.2 获取带内文本轨道
             3. 4.8.11.11.3 文本轨道 API
             4. 4.8.11.11.4 元数据文本轨道的最佳实践
         12. 4.8.11.12 通过 URL 识别轨道类型
         13. 4.8.11.13 用户界面
         14. 4.8.11.14 时间范围
         15. 4.8.11.15 TrackEvent 接口
         16. 4.8.11.16 事件摘要
         17. 4.8.11.17 使用媒体元素的作者的最佳实践

4.8.8 video 元素

类别:

流内容.

短语内容.

嵌入内容.

如果元素具有 controls 属性：交互式内容。

可感知内容.

可以使用此元素的上下文:

在预期 嵌入内容 的位置。

内容模型:

如果元素具有 src 属性：零个或多个 track 元素，然后 透明，但没有 媒体元素 后代。

如果元素没有 src 属性：零个或多个 source 元素，然后零个或多个 track 元素，然后 透明，但没有 媒体元素 后代。

text/html 中的标签省略:

两个标签都不能省略。

内容属性:

全局属性

src — 资源的地址

crossorigin — 元素如何处理跨源请求

poster — 在视频播放之前显示的宣传海报帧

preload — 提示 媒体资源 可能需要多少缓冲

autoplay — 提示页面加载时可以自动启动 媒体资源

playsinline — 鼓励用户代理在元素的播放区域内显示视频内容

loop — 是否循环播放 媒体资源

muted — 是否默认静音 媒体资源

controls — 显示用户代理控件

width — 水平尺寸

height — 垂直尺寸

可访问性注意事项:

供作者使用.

供实现者使用.

DOM 接口:

使用 HTMLVideoElement。

video 元素用于播放视频或电影，以及带有字幕的音频文件。

可以在 video 元素内部提供内容；它适用于不支持 video 的旧版 Web 浏览器，以便可以向这些旧版浏览器的用户显示文本，告知他们如何访问视频内容。

特别是，此内容并非旨在解决可访问性问题。为了使视力障碍、盲人、听力障碍、聋人和患有其他身体或认知障碍的人能够访问视频内容，可以使用各种功能。可以提供字幕，嵌入在视频流中或作为使用 track 元素的外部文件。手语轨道可以嵌入到视频流中。音频描述可以嵌入到视频流中或以文本形式使用 WebVTT 文件（使用 track 元素引用）并由用户代理合成语音。WebVTT 还可以用于提供章节标题。对于那些根本不想使用媒体元素的用户，可以通过在 video 元素附近的散文中简单地链接到它们来提供成绩单或其他文本替代方案。[WEBVTT]

video 元素是一个 媒体元素，其 媒体数据 表面上是视频数据，可能还有关联的音频数据。

src、crossorigin、preload、autoplay、loop、muted 和 controls 属性是 所有媒体元素共有的属性。

poster 属性提供用户代理可以在没有视频数据可用时显示的图像文件的 URL。如果存在，该属性必须包含一个 有效的非空 URL，可能包含空格。

由 poster 属性给出的图像（宣传海报帧）旨在成为视频的代表性帧（通常是前几个非空白帧之一），让用户了解视频的概况。

playsinline 属性是一个 布尔属性。如果存在，它作为对用户代理的提示，表明视频默认情况下应该在文档中“内联”显示，限制在元素的播放区域内，而不是以全屏或独立的可调整大小的窗口显示。

playsinline 属性的缺失并不意味着视频默认情况下将以全屏显示。实际上，大多数用户代理都选择默认情况下内联播放所有视频，并且在这些用户代理中，playsinline 属性没有效果。

video.videoWidth

video.videoHeight

这些属性返回视频的自然尺寸，如果尺寸未知则返回 0。

video 元素支持 尺寸属性。

<script>
 function failed(e) {
   // video playback failed - show a message saying why
   switch (e.target.error.code) {
     case e.target.error.MEDIA_ERR_ABORTED:
       alert('You aborted the video playback.');
       break;
     case e.target.error.MEDIA_ERR_NETWORK:
       alert('A network error caused the video download to fail part-way.');
       break;
     case e.target.error.MEDIA_ERR_DECODE:
       alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
       break;
     case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
       alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
       break;
     default:
       alert('An unknown error occurred.');
       break;
   }
 }
</script>
<p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
<p><a href="tgif.vid">Download the video file</a>.</p>

4.8.9 audio 元素

类别:

流内容.

短语内容.

嵌入内容.

如果元素具有 controls 属性：交互式内容。

如果元素具有 controls 属性：可感知内容。

可以使用此元素的上下文:

在预期 嵌入内容 的位置。

内容模型:

如果元素具有 src 属性：零个或多个 track 元素，然后 透明，但没有 媒体元素 后代。

如果元素没有 src 属性：零个或多个 source 元素，然后零个或多个 track 元素，然后 透明，但没有 媒体元素 后代。

text/html 中的标签省略:

两个标签都不能省略。

内容属性:

全局属性

src — 资源的地址

crossorigin — 元素如何处理跨源请求

preload — 提示媒体资源可能需要缓冲多少内容

autoplay — 提示页面加载时媒体资源可以自动开始播放

loop — 是否循环播放媒体资源

muted — 是否默认静音媒体资源

controls — 显示用户代理控件

可访问性注意事项:

供作者使用.

供实现者使用.

DOM 接口:

使用HTMLAudioElement。

一个audio元素表示一个声音或音频流。

可以在audio元素内部提供内容；这适用于不支持audio的旧版网页浏览器，以便向这些旧版浏览器的用户显示文本，告知他们如何访问音频内容。

特别是，此内容并非旨在解决可访问性问题。为了使音频内容能够被听障人士或其他有身体或认知障碍的人访问，可以使用各种功能。如果提供字幕或手语视频，则可以使用video元素而不是audio元素来播放音频，从而允许用户启用视觉替代方案。可以使用track元素和WebVTT 文件提供章节标题以帮助导航。当然，只需在audio元素附近的文本中链接到它们，即可提供成绩单或其他文本替代方案。 [WEBVTT]

audio元素是一个媒体元素，其媒体数据表面上是音频数据。

src、crossorigin、preload、autoplay、loop、muted和controls属性是所有媒体元素共有的属性。

audio = new Audio([ url ])

返回一个新的audio元素，如果适用，其src属性设置为参数中传递的值。

4.8.10 track 元素

类别:

无。

可以使用此元素的上下文:

作为媒体元素的子元素，位于任何流内容之前。

内容模型:

无.

text/html 中的标签省略:

无结束标签。

内容属性:

全局属性

kind — 文本轨道的类型

src — 资源的地址

srclang — 文本轨道的语言

label — 用户可见的标签

default — 如果没有其他更合适的文本轨道，则启用该轨道

可访问性注意事项:

供作者使用.

供实现者使用.

DOM 接口:

使用HTMLTrackElement。

track元素允许作者为媒体元素指定显式的外部定时文本轨道。它本身不表示任何内容。

kind属性是一个枚举属性，具有以下关键字和状态

该属性的缺失值默认值是subtitles状态，其无效值默认值是metadata状态。

src属性提供了文本轨道数据的URL。该值必须是可能被空格包围的有效非空URL。此属性必须存在。

如果元素的轨道URL标识 WebVTT 资源，并且元素的kind属性不在章节元数据或元数据状态中，则 WebVTT 文件必须是使用提示文本的 WebVTT 文件。 [WEBVTT]

srclang属性提供了文本轨道数据的语言。该值必须是有效的 BCP 47 语言标记。如果元素的kind属性处于subtitles状态，则此属性必须存在。 [BCP47]

label属性为轨道提供了一个用户可读的标题。用户代理在用户界面中列出字幕、隐藏式字幕和音频描述轨道时，会使用此标题。

如果存在该属性，则label属性的值不能是空字符串。此外，同一个媒体元素的track元素子元素不能有两个，其kind属性处于相同状态，其srclang属性都缺失或具有表示相同语言的值，并且其label属性再次都缺失或都具有相同的值。

default属性是一个布尔属性，如果指定，则表示如果用户的首选项未指示另一个轨道更合适，则应启用该轨道。

每个媒体元素最多只能有一个track元素子元素，其kind属性处于subtitles或captions状态，并且其default属性已指定。

每个媒体元素最多只能有一个track元素子元素，其kind属性处于description状态，并且其default属性已指定。

每个媒体元素最多只能有一个track元素子元素，其kind属性处于chapters metadata状态，并且其default属性已指定。

track元素的数量没有限制，其kind属性处于metadata状态，并且其default属性已指定。

track.readyState

返回文本轨道就绪状态，由以下列表中的数字表示

track.NONE (0)

文本轨道未加载状态。

track.LOADING (1)

文本轨道加载中状态。

track.LOADED (2)

文本轨道加载状态。

track。ERROR (3)

文本轨道加载失败状态。

track。track

返回与track元素的文本轨道对应的TextTrack对象。

<video src="brave.webm">
 <track kind=subtitles src=brave.en.vtt srclang=en label="English">
 <track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
 <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
 <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
</video>

4.8.11 媒体元素

HTMLMediaElement对象（在本规范中为audio和video）简称为媒体元素。

媒体元素属性media element attributes，src、crossorigin、preload、autoplay、loop、muted和controls，适用于所有媒体元素。它们在本节中定义。

媒体元素用于向用户呈现音频数据或视频和音频数据。在本节中，这被称为媒体数据，因为本节同样适用于音频或视频的媒体元素。术语媒体资源用于指代完整的媒体数据集合，例如完整的视频文件或完整的音频文件。

一个媒体资源有一个关联的源，它可以是“none”、“multiple”、“rewritten”或一个源。它最初设置为“none”。

一个媒体资源可以有多个音频和视频轨道。对于媒体元素，媒体资源的视频数据仅为当前选择的轨道（如果有）的数据，该数据由元素的videoTracks属性在事件循环上次到达步骤1时给出，而媒体资源的音频数据是元素的audioTracks属性在事件循环上次到达步骤1时给出的所有当前启用的轨道（如果有）的混合结果。

audio和video元素都可用于音频和视频。这两个元素之间的主要区别仅仅在于audio元素没有用于视觉内容（如视频或字幕）的播放区域，而video元素则有。

4.8.11.1 错误代码

media。error

返回一个表示元素当前错误状态的MediaError对象。

如果没有任何错误，则返回null。

media。error。code

返回当前错误的错误代码，来自下面的列表。

media。error。message

返回关于遇到的错误情况的特定信息诊断消息。消息和消息格式在不同的用户代理之间通常不统一。如果没有此类消息可用，则返回空字符串。

MEDIA_ERR_ABORTED（数值1）

根据用户的请求，用户代理中止了媒体资源的获取过程。

MEDIA_ERR_NETWORK（数值2）

某种网络错误导致用户代理停止获取媒体资源，在确认资源可用后。

MEDIA_ERR_DECODE（数值3）

在确认资源可用后，解码媒体资源时发生某种错误。

MEDIA_ERR_SRC_NOT_SUPPORTED（数值4）

src属性或分配的媒体提供程序对象指示的媒体资源不合适。

4.8.11.2 媒体资源的位置

媒体元素上的src内容属性提供了要显示的媒体资源（视频、音频）的URL。如果存在，该属性必须包含一个可能被空格包围的有效非空URL。

如果在媒体元素上指定了itemprop属性，则还必须指定src属性。

媒体元素上的crossorigin内容属性是CORS 设置属性。

媒体提供程序对象media provider object是一个可以表示媒体资源的对象，独立于URL。MediaStream对象、MediaSource对象和Blob对象都是媒体提供程序对象。

media。srcObject [ = source ]

允许媒体元素分配一个媒体提供程序对象。

media。currentSrc

返回当前媒体资源（如果有）的URL。

当没有媒体资源或它没有URL时，返回空字符串。

有三种方法可以指定媒体资源：srcObject IDL 属性、src内容属性和source元素。IDL 属性优先，其次是内容属性，最后是元素。

4.8.11.3 MIME 类型

媒体资源media resource可以用其类型来描述，具体来说是MIME 类型，在某些情况下带有codecs参数。（codecs参数是否允许取决于 MIME 类型。）[RFC6381]

类型通常是不完整的描述；例如，“video/mpeg”除了容器类型之外什么也没有说，即使像“video/mp4; codecs="avc1.42E01E, mp4a.40.2"”这样的类型也不包含诸如实际比特率（仅最大比特率）的信息。因此，给定一个类型，用户代理通常只能知道它是否可能能够播放该类型的媒体（置信度不同），或者是否绝对不能播放该类型的媒体。

用户代理知道无法呈现的类型是指描述用户代理绝对不支持的资源的类型，例如因为它无法识别容器类型，或者不支持列出的编解码器。

没有参数的MIME 类型“application/octet-stream”绝不是用户代理知道无法呈现的类型。当它用于标记潜在的媒体资源时，用户代理必须将该类型视为等同于没有任何显式Content-Type 元数据。

只有没有参数的MIME 类型“application/octet-stream”在此处是特殊情况；如果任何参数与它一起出现，它将像任何其他MIME 类型一样对待。这与未知MIME 类型参数应被忽略的规则有所不同。

media。canPlayType(type)

根据用户代理对播放给定类型媒体资源的信心程度，返回空字符串（否定响应）、“maybe”或“probably”。

<section id="video">
 <p><a href="playing-cats.nfv">Download video</a></p>
</section>
<script>
 const videoSection = document.getElementById('video');
 const videoElement = document.createElement('video');
 const support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
 if (support === "probably") {
   videoElement.setAttribute("src", "playing-cats.nfv");
   videoSection.replaceChildren(videoElement);
 }
</script>

type属性的source元素允许用户代理避免下载其无法呈现的格式的资源。

4.8.11.4 网络状态

media.networkState

从以下列表中的代码返回元素网络活动的当前状态。

NETWORK_EMPTY（数值 0）

元素尚未初始化。所有属性都处于其初始状态。

NETWORK_IDLE（数值 1）

元素已选择了一个资源，但此时它实际上并没有使用网络。

NETWORK_LOADING（数值 2）

用户代理正在积极尝试下载数据。

NETWORK_NO_SOURCE（数值 3）

元素尚未找到要使用的资源。

4.8.11.5 加载媒体资源

media.load()

导致元素重置并从头开始选择和加载新的媒体资源。

preload属性是一个枚举属性，具有以下关键字和状态

属性的缺失值默认值和无效值默认值都由实现定义，尽管元数据状态被建议作为减少服务器负载和提供最佳用户体验之间的折衷方案。

即使媒体资源正在缓冲或播放，也可以更改该属性；上述表格中的描述应考虑到这一点。

作者可能会动态地将属性从“none”或“metadata”切换到“auto”，一旦用户开始播放。例如，在包含许多视频的页面上，这可能用于指示除非请求，否则不下载许多视频，但一旦请求了一个视频，就应积极下载该视频。

autoplay属性可以覆盖preload属性（因为如果媒体播放，它自然需要先缓冲，而不管preload属性给出的提示如何）。但是，同时包含两者并非错误。

media.buffered

返回一个TimeRanges对象，该对象表示用户代理已缓冲的媒体资源的范围。

4.8.11.6 媒体资源中的偏移量

media.duration

返回媒体资源的长度（以秒为单位），假设媒体资源的开始时间为零。

如果持续时间不可用，则返回 NaN。

对于无界流，返回 Infinity。

media.currentTime [ = value ]

返回官方播放位置（以秒为单位）。

可以设置，以跳转到给定时间。

loop属性是一个布尔属性，如果指定，则表示媒体元素在到达末尾时应跳转回媒体资源的开头。

4.8.11.7 就绪状态

media.readyState

从以下列表中的代码返回一个值，该值表示元素相对于渲染当前播放位置的当前状态。

HAVE_NOTHING（数值 0）

没有关于媒体资源的信息可用。没有当前播放位置的数据可用。媒体元素的networkState属性设置为NETWORK_EMPTY始终处于HAVE_NOTHING状态。

HAVE_METADATA（数值 1）

已获取了足够的资源，可以获得资源的持续时间。在video元素的情况下，还可以获得视频的尺寸。没有媒体数据可用于直接的当前播放位置。

HAVE_CURRENT_DATA（数值 2）

直接的当前播放位置的数据可用，但要么可用数据不足以使用户代理能够在不立即恢复到HAVE_METADATA状态的情况下成功推进当前播放位置到播放方向，要么在播放方向上没有更多数据可以获取。例如，在视频中，这对应于用户代理拥有当前帧的数据，但没有下一帧的数据，当当前播放位置位于当前帧的末尾时；以及播放结束时。

HAVE_FUTURE_DATA（数值 3）

直接的当前播放位置的数据可用，以及用户代理能够在不立即恢复到HAVE_METADATA状态的情况下至少稍微推进当前播放位置到播放方向的数据，并且文本轨道已准备好。例如，在视频中，这对应于当当前播放位置位于两帧之间的瞬间时，用户代理拥有至少当前帧和下一帧的视频数据，或者当当前播放位置位于帧中间时，用户代理拥有当前帧的视频数据和音频数据以至少稍微继续播放。如果播放结束，用户代理不能处于此状态，因为在这种情况下当前播放位置永远不会前进。

HAVE_ENOUGH_DATA（数值 4）

满足HAVE_FUTURE_DATA状态描述的所有条件，此外，以下条件之一也为真

• 用户代理估计数据正在以这样的速率获取，如果当前播放位置以元素的playbackRate前进，则在播放到达媒体资源的末尾之前不会超过可用数据。
• 用户代理已进入一种状态，在该状态下，等待更长时间不会导致获取更多数据，因此延迟播放不会有任何好处。（例如，缓冲区可能已满。）

在实践中，HAVE_METADATA和HAVE_CURRENT_DATA之间的区别可以忽略不计。实际上，只有在将video元素绘制到canvas上时，这种区别才相关，它区分了将绘制某些内容（HAVE_CURRENT_DATA或更大）的情况和未绘制任何内容（HAVE_METADATA或更小）的情况。类似地，HAVE_CURRENT_DATA（仅当前帧）和HAVE_FUTURE_DATA（至少此帧和下一帧）之间的区别可以忽略不计（在极端情况下，只有一帧）。只有当页面提供“逐帧”导航的界面时，这种区别才真正重要。

媒体元素的准备就绪状态可能在这些状态之间不连续地跳转。例如，媒体元素的状态可以从HAVE_METADATA直接跳转到HAVE_ENOUGH_DATA，而无需经过HAVE_CURRENT_DATA和HAVE_FUTURE_DATA状态。

autoplay属性是一个布尔属性。当存在时，用户代理将在其能够做到这一点且不会停止的情况下自动开始播放媒体资源。

强烈建议作者使用autoplay属性，而不是使用脚本触发自动播放，因为这允许用户在不需要时覆盖自动播放，例如在使用屏幕阅读器时。作者还建议考虑根本不使用自动播放行为，而是让用户代理等待用户显式开始播放。

4.8.11.8 播放媒体资源

media.paused

如果播放已暂停则返回true；否则返回false。

media.ended

如果播放已到达媒体资源的末尾则返回true。

media.defaultPlaybackRate [ = value ]

返回默认播放速率，用于用户未快进或倒退浏览媒体资源时。

可以设置，以更改默认播放速率。

默认速率对播放没有直接影响，但如果用户切换到快进模式，当他们返回正常播放模式时，预计播放速率将恢复为默认播放速率。

media.playbackRate [ = value ]

返回当前播放速率，其中1.0为正常速度。

可以设置，以更改播放速率。

media.preservesPitch

如果playbackRate不为1.0时使用音调保持算法，则返回true。默认值为true。

可以设置为false，使媒体资源的音频音调根据playbackRate上下变化。这对于美学和性能原因很有用。

media.played

返回一个TimeRanges对象，该对象表示用户代理已播放的媒体资源的范围。

media.play()

将paused属性设置为false，加载媒体资源并在必要时开始播放。如果播放已结束，则将从头重新开始。

media.pause()

将paused属性设置为true，并在必要时加载媒体资源。

4.8.11.9 查找

media.seeking

如果用户代理当前正在查找，则返回true。

media.seekable

返回一个TimeRanges对象，该对象表示用户代理可以查找的媒体资源的范围。

media.fastSeek(time)

尽快查找给定time附近的位置，以速度换取精度。（要查找精确的时间，请使用currentTime属性。）

如果媒体资源未加载，则此操作无效。

4.8.11.10 具有多个媒体轨道的媒体资源

一个媒体资源可以具有多个嵌入式音频和视频轨道。例如，除了主要的视频和音频轨道外，媒体资源还可以包含外语配音对话、导演评论、音频描述、备用角度或手语叠加。

media.audioTracks

返回一个AudioTrackList对象，该对象表示媒体资源中可用的音频轨道。

media.videoTracks

返回一个VideoTrackList对象，该对象表示媒体资源中可用的视频轨道。

4.8.11.10.1 AudioTrackList 和 VideoTrackList 对象

AudioTrackList 和 VideoTrackList 接口由上一节中定义的属性使用。

media.audioTracks.length

media.videoTracks.length

返回列表中的轨道数。

audioTrack = media.audioTracks[index]

videoTrack = media.videoTracks[index]

返回指定的AudioTrack或VideoTrack对象。

audioTrack = media.audioTracks.getTrackById(id)

videoTrack = media.videoTracks.getTrackById(id)

返回具有给定标识符的AudioTrack或VideoTrack对象，如果没有任何轨道具有该标识符，则返回null。

audioTrack.id

videoTrack.id

返回给定轨道的ID。如果格式支持媒体片段语法，则可以使用此ID作为片段，并且可以使用getTrackById()方法。

audioTrack.kind

videoTrack.kind

返回给定轨道所属的类别。可能的轨道类别如下所示。

audioTrack.label

videoTrack.label

返回给定轨道的标签（如果已知），否则返回空字符串。

audioTrack.language

videoTrack.language

返回给定轨道的语言（如果已知），否则返回空字符串。

audioTrack.enabled [ = value ]

如果给定轨道处于活动状态，则返回true，否则返回false。

可以设置，以更改轨道是否启用。如果同时启用多个音频轨道，则将它们混合。

media.videoTracks.selectedIndex

返回当前选定轨道的索引（如果有），否则返回−1。

videoTrack.selected [ = value ]

如果给定轨道处于活动状态，则返回true，否则返回false。

可以设置，以更改轨道是否被选中。可以选择零个或一个视频轨道；在选择新的轨道时，如果先前的轨道已选中，则会取消选择先前的轨道。

4.8.11.10.2 声明式选择特定的音频和视频轨道

通过 audioTracks 和 videoTracks 属性，脚本可以选取要播放的轨道，但也可以通过在 片段（URL 的 媒体资源）中指定特定的轨道来声明式地选取特定的轨道。 片段的格式取决于 MIME 类型 的 媒体资源。 [RFC2046] [URL]

<video src="myvideo#track=Alternative"></video>

4.8.11.11 定时文本轨道

4.8.11.11.1 文本轨道模型

一个 媒体元素 可以具有一组关联的 文本轨道，称为 媒体元素 的 文本轨道列表。 文本轨道 按以下顺序排序

1. 对应于 媒体元素 的 track 元素子元素的 文本轨道，按照 树形顺序。

2. 使用 addTextTrack() 方法添加的任何 文本轨道，按照添加的顺序，最早的排在最前面。

3. 任何 媒体资源特定的文本轨道（对应于 媒体资源 中数据的 文本轨道），按照 媒体资源 的格式规范定义的顺序。

一个 文本轨道 由以下部分组成：

文本轨道的类型

这决定了用户代理如何处理该轨道。类型由字符串表示。可能的字符串有：

• subtitles
• captions
• descriptions
• chapters
• metadata

对于对应于 track 元素的 文本轨道，轨道的类型 可以动态更改。

标签

这是一个供用户识别轨道的可读字符串。

对于对应于 track 元素的 文本轨道，轨道的标签 可以动态更改。

当 文本轨道标签 为空字符串时，用户代理应根据文本轨道的其他属性（例如文本轨道的类型和语言）自动生成一个合适的标签，用于其用户界面。此自动生成的标签在 API 中不可访问。

带内元数据轨道分发类型

这是一个从 媒体资源 中提取的字符串，专门用于带内元数据轨道，以使这些轨道能够分发到文档中的不同脚本。

例如，在网络上流式传输并增强了特定于网络的交互功能的传统电视台广播可以包含用于广告定位、游戏节目期间的琐事游戏数据、体育比赛期间的播放器状态、烹饪节目期间的菜谱信息等的元数据文本轨道。随着每个节目的开始和结束，新的轨道可能会被添加到流中或从流中移除，并且在添加每个轨道时，用户代理可以使用此属性的值将其绑定到专用的脚本模块。

除了带内元数据文本轨道之外，带内元数据轨道分发类型 为空字符串。对于不同的媒体格式，此值如何填充在 公开媒体资源特定文本轨道的步骤 中进行了描述。

语言

这是一个字符串（BCP 47 语言标签），表示文本轨道提示的语言。 [BCP47]

对于对应于 track 元素的 文本轨道，文本轨道的语言 可以动态更改。

就绪状态

以下之一：

未加载

表示尚未获取文本轨道的提示。

正在加载

表示文本轨道正在加载，并且到目前为止尚未遇到任何致命错误。解析器可能还会向轨道添加更多提示。

已加载

表示文本轨道已加载，没有致命错误。

加载失败

表示文本轨道已启用，但当用户代理尝试获取它时，以某种方式失败（例如，URL 无法 解析、网络错误、未知的文本轨道格式）。一些或所有提示可能丢失，并且不会被获取。

随着轨道的获取，文本轨道 的 就绪状态 会动态更改。

模式

以下之一：

禁用

表示文本轨道未激活。除了在 DOM 中公开轨道之外，用户代理正在忽略文本轨道。没有提示处于活动状态，没有事件被触发，并且用户代理不会尝试获取轨道的提示。

隐藏

表示文本轨道处于活动状态，但用户代理未主动显示提示。如果尚未尝试获取轨道的提示，用户代理将立即执行此操作。用户代理正在维护一个哪些提示处于活动状态的列表，并相应地触发事件。

显示

表示文本轨道处于活动状态。如果尚未尝试获取轨道的提示，用户代理将立即执行此操作。用户代理正在维护一个哪些提示处于活动状态的列表，并相应地触发事件。此外，对于 类型 为 字幕 或 隐藏式字幕 的文本轨道，提示将根据需要覆盖在视频上；对于 类型 为 描述 的文本轨道，用户代理以非视觉方式向用户提供提示；对于 类型 为 章节 的文本轨道，用户代理向用户提供了一种机制，用户可以通过选择提示导航到 媒体资源 中的任何点。

零个或多个提示列表

一个 文本轨道提示 列表，以及 更新文本轨道渲染的规则。例如，对于 WebVTT，更新 WebVTT 文本轨道显示的规则。 [WEBVTT]

文本轨道 的 提示列表 可以动态更改，因为 文本轨道 尚未加载 或仍在 加载，或者由于 DOM 操作。

每个 文本轨道 都有一个相应的 TextTrack 对象。

每个 媒体元素 都有一个 待处理文本轨道列表（最初必须为空）、一个 被解析器阻塞 标志（最初必须为 false）和一个 已执行自动轨道选择 标志（最初也必须为 false）。

当用户代理需要 填充媒体元素的待处理文本轨道列表 时，用户代理必须将元素的 待处理文本轨道列表 中的每个 文本轨道 添加到元素的 文本轨道列表 中，这些文本轨道的 文本轨道模式 不是 禁用 并且 文本轨道就绪状态 为 加载中。

只要 track 元素的父节点发生更改，用户代理必须从其所在的任何 待处理文本轨道列表 中删除相应的 文本轨道。

只要 文本轨道 的 文本轨道就绪状态 更改为 已加载 或 加载失败，用户代理必须将其从其所在的任何 待处理文本轨道列表 中删除。

当 媒体元素 由 HTML 解析器 或 XML 解析器 创建时，用户代理必须将元素的 被解析器阻塞 标志设置为 true。当 媒体元素 从 HTML 解析器 或 XML 解析器 的 打开元素栈 中弹出时，用户代理必须 遵守用户对自动文本轨道选择的偏好、填充待处理文本轨道列表 并将元素的 被解析器阻塞 标志设置为 false。

当媒体元素的待处理文本轨道列表为空，且元素的被解析器阻塞标志为假时，媒体元素的文本轨道就已就绪。

每个媒体元素都有一个待处理文本轨道更改通知标志，该标志最初必须未设置。

每当媒体元素的文本轨道列表中的文本轨道的文本轨道模式更改值时，用户代理必须为媒体元素运行以下步骤。

1. 如果媒体元素的待处理文本轨道更改通知标志已设置，则返回。

2. 设置媒体元素的待处理文本轨道更改通知标志。

3. 给定媒体元素，将一个媒体元素任务排队以运行以下步骤。

   1. 取消设置媒体元素的待处理文本轨道更改通知标志。

   2. 在媒体元素的textTracks属性的TextTrackList对象上触发一个名为change的事件。

4. 如果媒体元素的显示海报标志未设置，则运行“时间流逝”步骤。

本节中列出的任务的任务源是DOM操作任务源。

一个文本轨道提示是文本轨道中时间敏感数据的单位，例如，对于字幕和隐藏字幕，它对应于在特定时间出现并在另一个时间消失的文本。

每个文本轨道提示包含：

一个标识符。

一个任意字符串。

一个开始时间。

以秒和秒的分数表示的时间，描述提示适用的媒体数据范围的开始。

一个结束时间。

以秒和秒的分数表示的时间，描述提示适用的媒体数据范围的结束，或者对于无界文本轨道提示，为正无穷大。

一个退出暂停标志。

一个布尔值，指示当达到提示适用的范围的末尾时，是否要暂停媒体资源的播放。

一些其他特定于格式的数据。

根据格式所需的附加字段，包括提示的实际数据。例如，WebVTT 有文本轨道提示书写方向等等。[WEBVTT]

一个无界文本轨道提示是一个文本轨道提示结束时间设置为正无穷大的文本轨道提示。一个活动的无界文本轨道提示不能通过在正常播放期间当前播放位置的通常单调增加而变为非活动状态（例如，直播事件中章节的元数据提示，没有宣布结束时间）。

文本轨道提示开始时间和文本轨道提示结束时间可以为负。（但是，当前播放位置永远不能为负，因此完全在时间零之前的提示不能处于活动状态。）

每个文本轨道提示都有一个对应的TextTrackCue对象（更准确地说，是一个继承自TextTrackCue的对象——例如，WebVTT 提示使用VTTCue接口）。可以通过此TextTrackCue API动态更改文本轨道提示的内存表示。[WEBVTT]

一个文本轨道提示与更新文本轨道渲染的规则相关联，这些规则由特定类型的文本轨道提示的规范定义。当表示提示的对象使用addCue()方法添加到TextTrack对象时，会专门使用这些规则。

此外，每个文本轨道提示都有两条动态信息：

活动标志

此标志最初必须未设置。该标志用于确保在提示变为活动或非活动时适当地触发事件，并确保渲染正确的提示。

每当文本轨道提示从其文本轨道的文本轨道提示列表中删除；每当文本轨道本身从其媒体元素的文本轨道列表中删除或其文本轨道模式更改为已禁用；以及每当媒体元素的readyState更改回HAVE_NOTHING时，用户代理必须同步取消设置此标志。当以这种方式为文本轨道（在相关事件发生之前显示）中的一个或多个提示取消设置标志时，用户代理必须在为所有受影响的提示取消设置标志后，应用这些文本轨道的更新文本轨道渲染的规则。例如，对于基于 WebVTT 的文本轨道，更新 WebVTT 文本轨道显示的规则。[WEBVTT]

显示状态

这用作渲染模型的一部分，以保持提示处于一致的位置。它最初必须为空。每当文本轨道提示活动标志取消设置时，用户代理必须清空文本轨道提示显示状态。

媒体元素的文本轨道的文本轨道提示彼此之间按文本轨道提示顺序排序，该顺序如下确定：首先按其文本轨道对提示进行分组，这些组的排序顺序与其文本轨道在媒体元素的文本轨道列表中出现的顺序相同；然后，在每个组内，提示必须按其开始时间排序，最早的排在最前面；然后，任何具有相同开始时间的提示必须按其结束时间排序，最新的排在最前面；最后，任何具有相同结束时间的提示必须按其上次添加到各自的文本轨道提示列表中的顺序排序，最早的排在最前面（例如，对于来自 WebVTT 文件的提示，最初将是提示在文件中列出的顺序）。[WEBVTT]

4.8.11.11.2 带内文本轨道的来源

一个媒体资源特定的文本轨道是一个文本轨道，它对应于在媒体资源中找到的数据。

4.8.11.11.3 文本轨道 API

media.textTracks.length

返回与媒体元素关联的文本轨道的数量（例如，来自track元素）。这是媒体元素的文本轨道列表中文本轨道的数量。

media.textTracks[ n ]

返回表示媒体元素的文本轨道列表中第n个文本轨道的TextTrack对象。

textTrack = media.textTracks.getTrackById(id)

返回具有给定标识符的TextTrack对象，如果没有任何轨道具有该标识符，则返回null。

textTrack = media.addTextTrack(kind [, label [, language ] ])

创建一个新的TextTrack对象并返回，该对象也会添加到媒体元素的文本轨道列表中。

textTrack.kind

返回文本轨道类型字符串。

textTrack.label

如果存在文本轨道标签，则返回文本轨道标签，否则返回空字符串（表示如果对象暴露给用户，则可能需要根据对象的其它属性生成自定义标签）。

textTrack.language

返回文本轨道语言字符串。

textTrack.id

返回给定轨道的ID。

对于带内轨道，如果格式支持媒体片段语法，则此ID可与片段一起使用，并且可与getTrackById()方法一起使用。

对于对应于track元素的TextTrack对象，这是track元素的ID。

textTrack.inBandMetadataTrackDispatchType

返回文本轨道带内元数据轨道分发类型字符串。

textTrack.mode [ = value ]

返回文本轨道模式，由以下列表中的字符串表示

"disabled"

文本轨道禁用模式。

"hidden"

文本轨道隐藏模式。

"showing"

文本轨道显示模式。

可以设置，以更改模式。

textTrack.cues

返回文本轨道提示列表，作为TextTrackCueList对象。

textTrack.activeCues

返回文本轨道提示列表中当前处于活动状态（即，开始时间早于当前播放位置并且结束时间晚于它）的文本轨道提示，作为TextTrackCueList对象。

textTrack.addCue(cue)

将给定的提示添加到textTrack的文本轨道提示列表。

textTrack.removeCue(cue)

从textTrack的文本轨道提示列表中删除给定的提示。

var sfx = new Audio('sfx.wav');
var sounds = sfx.addTextTrack('metadata');

// add sounds we care about
function addFX(start, end, name) {
  var cue = new VTTCue(start, end, '');
  cue.id = name;
  cue.pauseOnExit = true;
  sounds.addCue(cue);
}
addFX(12.783, 13.612, 'dog bark');
addFX(13.612, 15.091, 'kitten mew');

function playSound(id) {
  sfx.currentTime = sounds.getCueById(id).startTime;
  sfx.play();
}

// play a bark as soon as we can
sfx.oncanplaythrough = function () {
  playSound('dog bark');
}
// meow when the user tries to leave,
// and have the browser ask them to stay
window.onbeforeunload = function (e) {
  playSound('kitten mew');
  e.preventDefault();
}

cuelist.length

✔MDN

TextTrackCueList/length

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回列表中提示的数量。

cuelist[index]

返回列表中索引为index的文本轨道提示。这些提示按文本轨道提示顺序排序。

cuelist.getCueById(id)

✔MDN

TextTrackCueList/getCueById

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回具有文本轨道提示标识符id的第一个文本轨道提示（按文本轨道提示顺序）。

如果没有任何提示具有给定的标识符或参数为空字符串，则返回null。

cue.track

✔MDN

TextTrackCue/track

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回此文本轨道提示所属的TextTrack对象（如果有），否则返回null。

cue.id [ = value ]

✔MDN

TextTrackCue/id

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回文本轨道提示标识符。

可以设置。

cue.startTime [ = value ]

✔MDN

TextTrackCue/startTime

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回文本轨道提示开始时间（以秒为单位）。

可以设置。

cue.endTime [ = value ]

✔MDN

TextTrackCue/endTime

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

返回文本轨道提示结束时间（以秒为单位）。

对于无界文本轨道提示，返回正无穷大。

可以设置。

cue.pauseOnExit [ = value ]

✔MDN

TextTrackCue/pauseOnExit

所有当前引擎都支持。

Firefox31+Safari6+Chrome23+

---

Opera12.1+Edge79+

---

Edge (Legacy)12+Internet Explorer10+

---

Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

如果设置了文本轨道提示退出暂停标志，则返回true，否则返回false。

可以设置。

4.8.11.11.4 元数据文本轨道的最佳实践

文本轨道可用于存储与媒体数据相关的数据，用于交互式或增强型视图。

例如，显示体育广播的页面可以包含有关当前比分的信息。假设正在直播机器人比赛。图像可以叠加分数，如下所示

为了使分数显示在用户将视频跳转到任意点时都能正确渲染，元数据文本轨道提示需要具有适当的分数长度。例如，在上图中，可能会有一个持续比赛时间的提示，给出比赛编号，一个持续到蓝方联盟分数发生变化的提示，以及一个持续到红方联盟分数发生变化的提示。如果视频只是直播事件的流，则右下角的时间可能来自当前视频时间，而不是基于提示。但是，如果视频只是精彩片段，则这些信息也可能在提示中给出。

以下是这些内容在WebVTT文件中可能是什么样子

WEBVTT

...

05:10:00.000 --> 05:12:15.000
matchtype:qual
matchnumber:37

...

05:11:02.251 --> 05:11:17.198
red:78

05:11:03.672 --> 05:11:54.198
blue:66

05:11:17.198 --> 05:11:25.912
red:80

05:11:25.912 --> 05:11:26.522
red:83

05:11:26.522 --> 05:11:26.982
red:86

05:11:26.982 --> 05:11:27.499
red:89

...

这里的关键是要注意信息是在与相关事件适用的时间长度相对应的提示中给出的。如果分数在分数发生变化时作为零长度（或非常短，几乎为零长度）的提示给出，例如在05:11:17.198说“红+2”，在05:11:25.912说“红+3”等，就会出现问题：主要是，搜索更难实现，因为脚本必须遍历整个提示列表以确保没有错过任何通知；此外，如果提示很短，脚本可能永远不会看到它们处于活动状态，除非它专门监听它们。

以这种方式使用提示时，建议作者使用cuechange事件来更新当前的注释。（特别是，使用timeupdate事件不太合适，因为它即使在提示没有改变时也需要执行工作，更重要的是，会在元数据提示变为活动状态和显示更新之间引入更高的延迟，因为timeupdate事件受到速率限制。）

4.8.11.12 通过URL识别轨道类型

需要使用URL来识别AudioTrack kind或VideoTrack kind IDL属性的返回值，或识别文本轨道类型的其他规范或格式必须使用about:html-kind URL。

4.8.11.13 用户界面

controls属性是布尔属性。如果存在，则表示作者没有提供脚本化控制器，并希望用户代理提供自己的控件集。

media.volume [ = value ]

返回当前播放音量，作为0.0到1.0范围内的数字，其中0.0是最安静的，1.0是最响亮的。

可以设置，以更改音量。

如果新值不在0.0 .. 1.0范围内，则抛出"IndexSizeError" DOMException。

media.muted [ = value ]

如果音频静音，则返回true，覆盖volume属性；如果正在使用volume属性，则返回false。

可以设置，以更改音频是否静音。

媒体元素上的muted内容属性是布尔属性，它控制媒体资源音频输出的默认状态，可能会覆盖用户偏好。

此属性没有动态效果（它仅控制元素的默认状态）。

<video src="adverts.cgi?kind=video" controls autoplay loop muted></video>

4.8.11.14 时间范围

实现TimeRanges接口的对象表示时间范围（周期）列表。

media.length

返回对象中范围的数量。

time = media.start(index)

返回具有给定索引的范围的开始时间。

如果索引超出范围，则抛出"IndexSizeError" DOMException。

time = media.end(index)

返回具有给定索引的范围的结束时间。

如果索引超出范围，则抛出"IndexSizeError" DOMException。

4.8.11.15 TrackEvent 接口

event.track

返回与事件相关的轨道对象（TextTrack、AudioTrack 或 VideoTrack）。

4.8.11.16 事件摘要

以下事件在媒体元素上触发，作为上述处理模型的一部分。

以下事件在source 元素上触发

以下事件在AudioTrackList、VideoTrackList 和 TextTrackList 对象上触发

以下事件在TextTrack 对象和track 元素上触发

以下事件在track 元素上触发

以下事件在TextTrackCue 对象上触发

4.8.11.17 使用媒体元素的作者最佳实践

在机顶盒或手机等小型设备上播放音频和视频资源，通常受设备有限的硬件资源限制。例如，设备可能只支持三个同时播放的视频。因此，在媒体元素完成播放后释放其持有的资源是一个好习惯，可以通过非常小心地移除对该元素的所有引用并允许其被垃圾回收来实现，或者，更好的方法是将元素的src 属性设置为空字符串。在设置了srcObject 的情况下，改为将srcObject 设置为 null。

同样，当播放速率不完全为 1.0 时，硬件、软件或格式限制会导致视频帧丢失，以及音频出现断续或静音。