动态标准 — 最后更新于 2024年9月12日
video
元素audio
元素track
元素TrackEvent
接口video
元素所有当前引擎都支持。
所有当前引擎都支持。
controls
属性:交互式内容。src
属性:零个或多个 track
元素,然后是 透明的,但没有 媒体元素 后代。src
属性:零个或多个 source
元素,然后是零个或多个 track
元素,然后是 透明的,但没有 媒体元素 后代。src
— 资源的地址crossorigin
— 元素如何处理跨域请求poster
— 视频播放前显示的宣传海报帧preload
— 提示 媒体资源 可能需要多少缓冲autoplay
— 提示页面加载时可以自动启动 媒体资源playsinline
— 鼓励用户代理在元素的播放区域内显示视频内容loop
— 是否循环 媒体资源muted
— 是否默认静音 媒体资源controls
— 显示用户代理控件width
— 水平尺寸height
— 垂直尺寸[Exposed =Window ]
interface HTMLVideoElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute unsigned long width ;
[CEReactions ] attribute unsigned long height ;
readonly attribute unsigned long videoWidth ;
readonly attribute unsigned long videoHeight ;
[CEReactions ] attribute USVString poster ;
[CEReactions ] attribute boolean playsInline ;
};
video
元素用于播放视频或电影,以及带字幕的音频文件。
可以在 video
元素内部提供内容。用户代理不应将此内容显示给用户;它适用于不支持 video
的旧版 Web 浏览器,以便可以向这些旧版浏览器的用户显示文本,告知他们如何访问视频内容。
特别是,此内容并非旨在解决可访问性问题。为了使视频内容能够被视力障碍、盲人、听力障碍、聋人和患有其他身体或认知障碍的人访问,可以使用各种功能。字幕可以嵌入视频流中,也可以作为外部文件使用 track
元素提供。手语轨道可以嵌入视频流中。音频描述可以嵌入视频流中,也可以使用 WebVTT 文件 以文本形式嵌入,并由用户代理合成语音。WebVTT 还可以用于提供章节标题。对于不想使用媒体元素的用户,可以通过简单地在 video
元素附近的散文中链接到它们来提供成绩单或其他文本替代方案。[WEBVTT]
video
元素是一个 媒体元素,其 媒体数据 显然是视频数据,可能还有关联的音频数据。
src
、crossorigin
、preload
、autoplay
、loop
、muted
和 controls
属性是 所有媒体元素共有的属性。
poster
属性提供用户代理在没有可用视频数据时可以显示的图像文件的 URL。如果存在此属性,则必须包含一个 有效的非空 URL,可能被空格包围。
如果要使用指定的资源,那么,在创建元素或设置、更改或删除 poster
属性时,用户代理必须运行以下步骤以确定元素的 宣传海报帧(无论元素的 显示宣传海报标志 的值如何)
如果 url 为失败,则返回。没有 宣传海报帧。
令 request 为一个新的 请求,其 URL 为 url、客户端 为元素的 节点文档 的 相关设置对象、目标 为“image
”、发起者类型 为“video
”、凭据模式 为“include
”,并且其 使用 URL 凭据标志 已设置。
poster
属性给出的图像,即 宣传海报帧,旨在成为视频的代表性帧(通常是前几个非空白帧之一),让用户了解视频的内容。
playsinline
属性是一个 布尔属性。如果存在,它会作为一条提示,建议用户代理默认情况下以“内联”方式在文档中显示视频,限制在元素的播放区域内,而不是以全屏或独立的可调整大小的窗口显示。
playsinline
属性的缺失并不意味着视频将默认以全屏方式显示。事实上,大多数用户代理选择默认情况下内联播放所有视频,并且在这些用户代理中,playsinline
属性没有效果。
video
元素表示下面列表中第一个匹配条件给出的内容。
readyState
属性为 HAVE_NOTHING
,或者为 HAVE_METADATA
但尚未获取任何视频数据,或者元素的 readyState
属性为任何后续值,但 媒体资源 没有视频通道)。video
元素 表示其 海报帧(如果存在),否则表示 透明黑色,且没有 自然尺寸。video
元素 暂停 时,当前播放位置 为视频的第一帧,并且元素的 显示海报标志 被设置。video
元素 表示其 海报帧(如果存在),否则表示视频的第一帧。video
元素 暂停 且与 当前播放位置 相对应的视频帧不可用(例如,因为视频正在查找或缓冲)时。video
元素既不 可能正在播放 也不 暂停(例如,查找或停止时)时。video
元素 表示已渲染的视频的最后一帧。video
元素 暂停 时。video
元素 表示与 当前播放位置 相对应的视频帧。video
元素具有视频通道并且 可能正在播放)。video
元素 表示在持续增加的 “当前”位置 处的视频帧。当 当前播放位置 发生变化,使得最后渲染的帧不再是与视频中 当前播放位置 相对应的帧时,必须渲染新帧。视频帧必须从 事件循环 最后到达 步骤 1 时 选中 的视频轨道中获取。
视频流中哪个帧对应于特定播放位置由视频流的格式定义。
video
元素还 表示任何 文本轨道提示,这些提示的 文本轨道提示激活标志 已设置,并且其 文本轨道 处于 显示 模式,以及 媒体资源 中的任何音频,在 当前播放位置。
与 媒体资源 关联的任何音频,如果播放,必须与 当前播放位置 同步播放,在元素的 有效媒体音量 下。用户代理必须播放音频轨道中的音频,这些音频轨道在 事件循环 最后到达步骤 1 时已 启用。
除了以上内容外,用户代理还可以通过在视频或元素播放区域的其他区域叠加文本或图标,或以其他适当的方式,向用户提供消息(例如“缓冲中”、“未加载视频”、“错误”或更详细的信息)。
无法渲染视频的用户代理可以改为使元素 表示指向外部视频播放实用程序或视频数据本身的链接。
当 video
元素的 媒体资源 具有视频通道时,该元素提供一个 绘制源,其宽度为 媒体资源 的 自然宽度,其高度为 媒体资源 的 自然高度,其外观为与 当前播放位置 相对应的视频帧(如果可用),否则(例如,当视频正在查找或缓冲时)为其先前外观(如果存在),否则(例如,因为视频仍在加载第一帧)为黑色。
video.videoWidth
所有当前引擎都支持。
video.videoHeight
所有当前引擎都支持。
这些属性返回视频的自然尺寸,如果尺寸未知则返回 0。
媒体资源 的 自然宽度 和 自然高度 是资源以 CSS 像素 为单位的尺寸,在考虑了资源的尺寸、纵横比、清晰光圈、分辨率等因素后,根据资源使用的格式定义。如果变形格式未定义如何将纵横比应用于视频数据的尺寸以获得“正确”尺寸,则用户代理必须通过增加一个尺寸并保持另一个尺寸不变来应用比率。
videoWidth
IDL 属性必须返回视频以 CSS 像素 为单位的 自然宽度。videoHeight
IDL 属性必须返回视频以 CSS 像素 为单位的 自然高度。如果元素的 readyState
属性为 HAVE_NOTHING
,则这些属性必须返回 0。
每当视频的 自然宽度 或 自然高度 发生变化时(包括例如,因为 选定的视频轨道 已更改),如果元素的 readyState
属性不为 HAVE_NOTHING
,则用户代理必须 将一个媒体元素任务排队,并给定 媒体元素 以 触发名为 resize
的事件,在 媒体元素 上。
在没有相反样式规则的情况下,视频内容应在元素的播放区域内渲染,以便视频内容以尽可能大的尺寸显示在播放区域的中心,同时完全适合播放区域,并保持视频内容的纵横比。因此,如果播放区域的纵横比与视频的纵横比不匹配,则视频将显示为带黑边的或带黑柱的。元素播放区域中不包含视频的区域不表示任何内容。
在实现 CSS 的用户代理中,可以通过使用 渲染部分中建议的样式规则 来实现上述要求。
video
元素播放区域的 自然宽度 是 海报帧 的 自然宽度(如果可用,并且元素当前 表示其海报帧);否则,它是视频资源的 自然宽度(如果可用);否则 自然宽度 缺失。
video
元素播放区域的 自然高度 是 海报帧 的 自然高度(如果可用,并且元素当前 表示其海报帧);否则,它是视频资源的 自然高度(如果可用);否则 自然高度 缺失。
默认对象大小为 300 个 CSS 像素 宽和 150 个 CSS 像素 高。 [CSSIMAGES] 默认对象大小
用户代理应提供控件来启用或禁用字幕、音频描述轨道和其他与视频流关联的附加数据的显示,尽管此类功能再次不应干扰页面的正常渲染。
用户代理可以允许用户以更适合用户的方式查看视频内容,例如全屏或在独立的可调整大小的窗口中。用户代理甚至可能在默认情况下播放视频时触发此类查看模式,尽管当指定了 playsinline
属性时,它们不应这样做。与其他用户界面功能一样,启用此功能的控件不应干扰页面的正常渲染,除非用户代理正在 公开用户界面。但是,在这种独立的查看模式下,用户代理可以使完整的用户界面可见,即使 controls
属性不存在。
用户代理可以允许视频播放影响可能干扰用户体验的系统功能;例如,用户代理可以在视频播放过程中禁用屏幕保护程序。
poster
IDL 属性必须 反映 poster
内容属性。
playsInline
IDL 属性必须 反映 playsinline
内容属性。
此示例显示了如何检测视频何时无法正确播放。
< 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 >
audio
元素所有当前引擎都支持。
所有当前引擎都支持。
controls
属性:交互式内容。controls
属性:可感知内容。src
属性:零个或多个 track
元素,则 透明,但没有 媒体元素 后代。src
属性:零个或多个 source
元素,然后零个或多个 track
元素,则 透明,但没有 媒体元素 后代。src
— 资源的地址crossorigin
— 元素如何处理跨源请求preload
— 提示 媒体资源 可能需要多少缓冲autoplay
— 提示页面加载时可以自动启动 媒体资源loop
— 是否循环 媒体资源muted
— 是否默认静音 媒体资源controls
— 显示用户代理控件[Exposed =Window ,
LegacyFactoryFunction =Audio (optional DOMString src )]
interface HTMLAudioElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
};
可以在 audio
元素内部提供内容。用户代理不应将此内容显示给用户;它适用于不支持 audio
的旧版 Web 浏览器,以便可以向这些旧版浏览器的用户显示文本,告知他们如何访问音频内容。
特别是,此内容并非旨在解决可访问性问题。为了使音频内容对聋人或其他身体或认知障碍者可访问,可以使用各种功能。如果提供字幕或手语视频,则可以使用 video
元素而不是 audio
元素来播放音频,允许用户启用视觉替代方案。可以使用 track
元素和 WebVTT 文件 提供章节标题以帮助导航。当然,只需在 audio
元素附近的散文部分中链接到它们,即可提供成绩单或其他文本替代方案。 [WEBVTT]
audio
元素是一个 媒体元素,其 媒体数据 表面上是音频数据。
src
、crossorigin
、preload
、autoplay
、loop
、muted
和 controls
属性是 所有媒体元素共有的属性。
audio = new Audio([ url ])
所有当前引擎都支持。
提供了一个遗留工厂函数来创建 HTMLAudioElement
对象(除了来自 DOM 的工厂方法,例如 createElement()
):Audio(src)
。调用时,遗留工厂函数必须执行以下步骤
令 document 为 当前全局对象 的 关联的 Document
。
使用 "preload
" 和 "auto
" 设置 audio 的属性值。
如果给定 src,则使用 "src
" 和 src 设置 audio 的属性值。(这将 导致用户代理在返回之前调用 对象的 资源选择算法。)
返回 audio。
track
元素所有当前引擎都支持。
所有当前引擎都支持。
kind
— 文本轨道的类型src
— 资源的地址srclang
— 文本轨道的语言label
— 用户可见的标签default
— 如果没有其他 文本轨道 更合适,则启用该轨道[Exposed =Window ]
interface HTMLTrackElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString kind ;
[CEReactions ] attribute USVString src ;
[CEReactions ] attribute DOMString srclang ;
[CEReactions ] attribute DOMString label ;
[CEReactions ] attribute boolean default ;
const unsigned short NONE = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED = 2;
const unsigned short ERROR = 3;
readonly attribute unsigned short readyState ;
readonly attribute TextTrack track ;
};
track
元素允许作者为 媒体元素 指定显式外部定时 文本轨道。它本身 不表示 任何内容。
kind
属性是一个 枚举属性,具有以下关键字和状态
关键字 | 状态 | 简要说明 |
---|---|---|
字幕
| 字幕 | 对话的转录或翻译,适用于有音频但用户无法理解的情况(例如,用户不理解媒体资源音频轨道的语言)。叠加在视频上。 |
字幕
| 字幕 | 对话、音效、相关音乐提示和其他相关音频信息的转录或翻译,适用于音频不可用或不清楚的情况(例如,音频被静音、被环境噪音淹没或用户失聪)。叠加在视频上;并以适合听力障碍者的方式进行标记。 |
描述
| 描述 | 针对媒体资源视频部分的文本描述,旨在在视觉部分被遮挡、不可用或无法使用时进行音频合成(例如,用户在驾驶时没有屏幕地与应用程序交互,或用户失明)。以音频形式合成。 |
章节
| 章节元数据 | 旨在从脚本中使用的轨道。不会由用户代理显示。 |
元数据
| 元数据 |
该属性的缺失值默认值为字幕状态,其无效值默认值为元数据状态。
src
属性提供了文本轨道数据的URL。该值必须是可能由空格包围的有效非空URL。此属性必须存在。
该元素有一个关联的轨道URL(一个字符串),最初为空字符串。
当元素的
属性被设置时,运行以下步骤src
令trackURL
为失败。
令value
为元素的
属性值。src
如果value
不是空字符串,则将trackURL
设置为给定value
的URL的编码解析和序列化结果,相对于元素的节点文档。
如果它不是失败,则将元素的轨道URL设置为trackURL
;否则设置为空字符串。
如果元素的轨道URL标识WebVTT资源,并且元素的
属性不在章节元数据或元数据状态,则WebVTT文件必须是使用提示文本的WebVTT文件。[WEBVTT]kind
srclang
属性提供了文本轨道数据的语言。该值必须是有效的BCP 47语言标签。如果元素的
属性处于字幕状态,则此属性必须存在。[BCP47]kind
如果元素具有
属性且其值不是空字符串,则元素的轨道语言为该属性的值。否则,元素没有轨道语言。srclang
label
属性提供了轨道的用户可读标题。当用户代理在其用户界面中列出字幕、字幕和音频描述轨道时,会使用此标题。
如果存在
属性,则其值不能是空字符串。此外,同一个媒体元素的label
元素子元素不能有两个,它们的track
属性处于相同状态,它们的kind
属性都缺失或具有表示相同语言的值,并且它们的srclang
属性也都缺失或都具有相同的值。label
如果元素具有
属性且其值不是空字符串,则元素的轨道标签为该属性的值。否则,元素的轨道标签为空字符串。label
default
属性是一个布尔属性,如果指定,则表示如果用户的首选项没有指示其他轨道更合适,则应启用该轨道。
每个媒体元素必须只有一个
元素子元素,其track
属性处于字幕或字幕状态,并且其kind
属性已指定。default
每个媒体元素必须只有一个
元素子元素,其track
属性处于描述状态,并且其kind
属性已指定。default
每个媒体元素必须只有一个
元素子元素,其track
属性处于章节元数据状态,并且其kind
属性已指定。default
元素的数量没有限制,其track
属性处于元数据状态,并且其kind
属性已指定。default
track.readyState
返回文本轨道就绪状态,由以下列表中的数字表示
track.track
readyState
属性必须返回对应于
元素的文本轨道的文本轨道就绪状态的数值,如下列表定义track
NONE
(数值0)LOADING
(数值1)LOADED
(数值2)ERROR
(数值3)track
IDL属性必须在获取时返回
元素的文本轨道对应的track
对象。TextTrack
所有当前引擎都支持。
src
、srclang
、label
和default
IDL属性必须反映相同名称的相应内容属性。kind
IDL属性必须反映相同名称的内容属性,仅限于已知值。
此视频有多种语言的字幕
< 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 >
HTMLMediaElement对象(在本规范中,
和audio
)简称为媒体元素。video
所有当前引擎都支持。
enum CanPlayTypeResult { "" /* empty string */, " maybe " , " probably " };
typedef (MediaStream or MediaSource or Blob ) MediaProvider ;
[Exposed =Window ]
interface HTMLMediaElement : HTMLElement {
// error state
readonly attribute MediaError ? error ;
// network state
[CEReactions ] attribute USVString src ;
attribute MediaProvider ? srcObject ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString ? crossOrigin ;
const unsigned short NETWORK_EMPTY = 0;
const unsigned short NETWORK_IDLE = 1;
const unsigned short NETWORK_LOADING = 2;
const unsigned short NETWORK_NO_SOURCE = 3;
readonly attribute unsigned short networkState ;
[CEReactions ] attribute DOMString preload ;
readonly attribute TimeRanges buffered ;
undefined load ();
CanPlayTypeResult canPlayType (DOMString type );
// ready state
const unsigned short HAVE_NOTHING = 0;
const unsigned short HAVE_METADATA = 1;
const unsigned short HAVE_CURRENT_DATA = 2;
const unsigned short HAVE_FUTURE_DATA = 3;
const unsigned short HAVE_ENOUGH_DATA = 4;
readonly attribute unsigned short readyState ;
readonly attribute boolean seeking ;
// playback state
attribute double currentTime ;
undefined fastSeek (double time );
readonly attribute unrestricted double duration ;
object getStartDate ();
readonly attribute boolean paused ;
attribute double defaultPlaybackRate ;
attribute double playbackRate ;
attribute boolean preservesPitch ;
readonly attribute TimeRanges played ;
readonly attribute TimeRanges seekable ;
readonly attribute boolean ended ;
[CEReactions ] attribute boolean autoplay ;
[CEReactions ] attribute boolean loop ;
Promise <undefined > play ();
undefined pause ();
// controls
[CEReactions ] attribute boolean controls ;
attribute double volume ;
attribute boolean muted ;
[CEReactions ] attribute boolean defaultMuted ;
// tracks
[SameObject ] readonly attribute AudioTrackList audioTracks ;
[SameObject ] readonly attribute VideoTrackList videoTracks ;
[SameObject ] readonly attribute TextTrackList textTracks ;
TextTrack addTextTrack (TextTrackKind kind , optional DOMString label = "", optional DOMString language = "");
};
所有媒体元素都适用媒体元素属性,包括 src
、crossorigin
、preload
、autoplay
、loop
、muted
和 controls
。这些属性在本节中定义。
媒体元素用于向用户呈现音频数据或视频和音频数据。在本节中,这被称为媒体数据,因为本节同样适用于音频或视频的媒体元素。术语媒体资源用于指代完整的媒体数据集合,例如完整的视频文件或完整的音频文件。
一个媒体资源具有关联的来源,该来源可以是“none
”、“multiple
”、“rewritten
”或一个来源。它最初设置为“none
”。
一个媒体资源可以有多个音频和视频轨道。对于媒体元素,媒体资源的视频数据仅为当前选定的轨道(如果有)的数据,由元素的videoTracks
属性在事件循环上次到达步骤 1时给出,并且媒体资源的音频数据是所有当前启用的轨道(如果有)混合的结果,由元素的audioTracks
属性在事件循环上次到达步骤 1时给出。
audio
和 video
元素都可用于音频和视频。两者之间的主要区别在于 audio
元素没有用于视觉内容(如视频或字幕)的播放区域,而 video
元素则有。
每个媒体元素都有一个唯一的媒体元素事件任务源。
要使用媒体元素 element 和一系列步骤 steps 来排队一个媒体元素任务,请在媒体元素的媒体元素事件任务源上排队一个元素任务,并给出 element 和 steps。
所有当前引擎都支持。
media.error
所有当前引擎都支持。
返回一个MediaError
对象,表示元素的当前错误状态。
如果没有任何错误,则返回 null。
所有媒体元素都具有关联的错误状态,该状态记录自上次调用元素的资源选择算法以来元素遇到的最后一个错误。error
属性在获取时必须返回为该最后一个错误创建的MediaError
对象,或者如果没有任何错误则返回 null。
[Exposed =Window ]
interface MediaError {
const unsigned short MEDIA_ERR_ABORTED = 1;
const unsigned short MEDIA_ERR_NETWORK = 2;
const unsigned short MEDIA_ERR_DECODE = 3;
const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
readonly attribute unsigned short code ;
readonly attribute DOMString message ;
};
media.error.code
所有当前引擎都支持。
返回当前错误的错误代码,来自下面的列表。
media.error.message
所有当前引擎都支持。
返回关于遇到的错误情况的特定信息诊断消息。该消息和消息格式在不同的用户代理之间通常不统一。如果没有此类消息可用,则返回空字符串。
每个MediaError
对象都有一个消息(一个字符串)和一个代码,该代码是以下代码之一
MEDIA_ERR_ABORTED
(数值 1)MEDIA_ERR_NETWORK
(数值 2)MEDIA_ERR_DECODE
(数值 3)MEDIA_ERR_SRC_NOT_SUPPORTED
(数值 4)src
属性或分配的媒体提供程序对象指示的媒体资源不合适。要创建一个 MediaError
,给定一个错误代码(上述值之一),返回一个新的MediaError
对象,其代码为给定的错误代码,其消息为包含用户代理能够提供的关于错误情况原因的任何详细信息的字符串,或者如果用户代理无法提供此类详细信息则为空字符串。此消息字符串不得仅包含通过提供的错误代码即可获得的信息;例如,它不应仅仅是将代码翻译成字符串格式。如果除了错误代码提供的之外没有其他信息可用,则必须将消息设置为空字符串。
媒体元素上的src
内容属性提供了要显示的媒体资源(视频、音频)的URL。如果存在,该属性必须包含一个有效的非空 URL,可能包含空格。
如果在媒体元素上指定了itemprop
属性,则还必须指定src
属性。
媒体元素上的crossorigin
内容属性是一个CORS 设置属性。
如果使用src
属性创建了媒体元素,则用户代理必须立即调用媒体元素的资源选择算法。
如果设置或更改了媒体元素的src
属性,则用户代理必须调用媒体元素的媒体元素加载算法。(移除src
属性不会这样做,即使存在source
元素。)
所有当前引擎都支持。
所有当前引擎都支持。
crossOrigin
IDL 属性必须反映crossorigin
内容属性,仅限于已知值。
媒体提供者对象是一个可以表示媒体资源的对象,独立于 URL。MediaStream
对象、MediaSource
对象和 Blob
对象都是媒体提供者对象。
每个媒体元素可以有一个分配的媒体提供者对象,它也是一个媒体提供者对象。当创建媒体元素时,它没有分配的媒体提供者对象。
media.srcObject [ = source ]
仅在一个引擎中受支持。
允许将媒体元素分配给媒体提供者对象。
media.currentSrc
所有当前引擎都支持。
如果存在,则返回当前媒体资源的 URL。
当没有媒体资源或它没有 URL 时,返回空字符串。
currentSrc
IDL 属性最初必须设置为空字符串。它的值由下面定义的资源选择算法更改。
srcObject
IDL 属性,在获取时,必须返回元素的分配的媒体提供者对象(如果有),否则返回 null。在设置时,它必须将元素的分配的媒体提供者对象设置为新值,然后调用元素的媒体元素加载算法。
有三种方法可以指定媒体资源:srcObject
IDL 属性、src
内容属性和 source
元素。IDL 属性优先,其次是内容属性,最后是元素。
媒体资源可以用其类型(特别是 MIME 类型)来描述,在某些情况下带有 codecs
参数。(是否允许 codecs
参数取决于 MIME 类型。)[RFC6381]
类型通常是不完整的描述;例如,“video/mpeg
”除了容器类型之外什么也没有说明,即使像“video/mp4; codecs="avc1.42E01E, mp4a.40.2"
”这样的类型也不包含诸如实际比特率(仅最大比特率)的信息。因此,给定一个类型,用户代理通常只能知道它是否可能能够播放该类型的媒体(置信度各不相同),或者它是否绝对不能播放该类型的媒体。
用户代理知道无法呈现的类型是指描述用户代理绝对不支持的资源的类型,例如因为它无法识别容器类型或不支持列出的编解码器。
MIME 类型“application/octet-stream
”(无参数)永远不会是用户代理知道无法呈现的类型。当它用于标记潜在的媒体资源时,用户代理必须将该类型视为等同于缺少任何显式的内容类型元数据。
只有 MIME 类型“application/octet-stream
”(无参数)在此处被特殊处理;如果出现任何参数,则将其视为任何其他 MIME 类型。这与未知 MIME 类型参数应被忽略的规则有所不同。
media.canPlayType(type)
所有当前引擎都支持。
根据用户代理对播放给定类型媒体资源的信心程度,返回空字符串(否定响应)、“maybe”或“probably”。
canPlayType(type)
方法必须返回空字符串,如果 type 是用户代理知道无法呈现的类型或类型“application/octet-stream
”;如果用户代理确信该类型表示它可以呈现的媒体资源(如果与此音频或视频元素一起使用),则必须返回“probably
”;否则必须返回“maybe
”。鼓励实现者返回“maybe
”,除非可以确定该类型是否得到支持。通常,用户代理绝不应为允许 codecs
参数的类型返回“probably
”,如果该参数不存在。
此脚本测试用户代理是否支持(虚构的)新格式,以动态决定是否使用 video 元素。
< 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 >
source 元素的 type
属性允许用户代理避免下载使用它无法呈现的格式的资源。
media.networkState
所有当前引擎都支持。
返回元素当前网络活动的狀態,来自以下列表中的代码。
随着媒体元素与网络交互,它们的当前网络活动由 networkState
属性表示。在获取时,它必须返回元素的当前网络状态,该状态必须是以下值之一
NETWORK_EMPTY
(数值 0)NETWORK_IDLE
(数值 1)NETWORK_LOADING
(数值 2)NETWORK_NO_SOURCE
(数值 3)下面定义的资源选择算法准确描述了 networkState
属性何时更改值以及触发哪些事件以指示此状态的变化。
media.load()
所有当前引擎都支持。
导致元素重置并从头开始选择和加载新的媒体资源。
所有媒体元素都有一个可以自动播放标志,它必须以 true 状态开始,以及一个延迟加载事件标志,它必须以 false 状态开始。当延迟加载事件标志为 true 时,元素必须延迟其文档的加载事件。
当在媒体元素上调用 load()
方法时,用户代理必须运行媒体元素加载算法。
媒体元素具有关联的布尔值“当前是否暂停”,最初为 false。
媒体元素加载算法包含以下步骤。
将此元素的“当前是否暂停”设置为 false。
中止此元素的任何已运行的资源选择算法实例。
设 pending tasks 为来自 任务 列表,其中包含 媒体元素 的 媒体元素事件任务源 中的一个或多个 任务队列 中的所有任务。
对于 pending tasks 中的每个任务,如果该任务会 解决挂起的播放 Promise 或 拒绝挂起的播放 Promise,则立即按相应任务入队的顺序解决或拒绝这些 Promise。
从其 任务队列 中移除 pending tasks 中的每个 任务。
基本上,当媒体元素开始加载新资源时,挂起的事件和回调将被丢弃,并且正在进行的待解决/拒绝的 Promise 将立即解决/拒绝。
如果 媒体元素 的 networkState
设置为 NETWORK_LOADING
或 NETWORK_IDLE
,则 排队一个媒体元素任务,并给定 媒体元素 以 触发名为 abort
的事件,在 媒体元素 上触发。
如果 媒体元素 的 networkState
未设置为 NETWORK_EMPTY
,则
排队一个媒体元素任务,并给定 媒体元素 以 触发名为 emptied
的事件,在 媒体元素 上触发。
如果 媒体元素 正在进行获取过程,则用户代理应停止它。
如果 媒体元素 的 分配的媒体提供程序对象 是 MediaSource
对象,则 分离它。
如果 readyState
未设置为 HAVE_NOTHING
,则将其设置为该状态。
如果 paused
属性为 false,则
将 paused
属性设置为 true。
获取挂起的播放 Promise 并使用结果和 "AbortError
" DOMException
拒绝挂起的播放 Promise。
如果 seeking
为 true,则将其设置为 false。
将 当前播放位置 设置为 0。
将 官方播放位置 设置为 0。
如果这改变了 官方播放位置,则 排队一个媒体元素任务,并给定 媒体元素 以 触发名为 timeupdate
的事件,在 媒体元素 上触发。
将 时间线偏移量 设置为非数字 (NaN)。
将 duration
属性更新为非数字 (NaN)。
用户代理 不会 为此特定持续时间更改触发 durationchange
事件。
将 playbackRate
属性设置为 defaultPlaybackRate
属性的值。
此元素之前播放的任何 媒体资源 的播放停止。
媒体元素 的 资源选择算法 如下。此算法始终作为 任务 的一部分调用,但算法的第一步之一是返回并继续运行剩余步骤 并行。此外,此算法与 事件循环 机制紧密交互;特别是,它具有 同步部分(作为 事件循环 算法的一部分触发)。此类部分中的步骤用 ⌛ 标记。
将元素的 networkState
属性设置为 NETWORK_NO_SOURCE
值。
将元素的 显示海报标志 设置为 true。
等待稳定状态,允许调用此算法的 任务 继续。 同步部分 包含此算法的其余所有步骤,直到算法说明 同步部分 已结束。(同步部分 中的步骤用 ⌛ 标记。)
⌛ 如果 媒体元素 的 被解析器阻塞 标志为 false,则 填充挂起文本轨道的列表。
⌛ 如果 媒体元素 有 分配的媒体提供程序对象,则令 mode 为 object。
⌛ 否则,如果 媒体元素 没有 分配的媒体提供程序对象,但有 src
属性,则令 mode 为 attribute。
⌛ 否则,如果 媒体元素 没有 分配的媒体提供程序对象 且没有 src
属性,但有 source
元素子级,则令 mode 为 children,并令 candidate 为 树序 中的第一个这样的 source
元素子级。
⌛ 否则,媒体元素 没有 分配的媒体提供程序对象,既没有 src
属性,也没有 source
元素子级
⌛ 将 networkState
设置为 NETWORK_EMPTY
。
结束 同步部分 并返回。
⌛ 将 媒体元素 的 networkState
设置为 NETWORK_LOADING
。
⌛ 排队一个媒体元素任务,并给定 媒体元素 以 触发名为 loadstart
的事件,在 媒体元素 上触发。
从以下列表中运行相应的步骤
⌛ 将 currentSrc
属性设置为空字符串。
使用 分配的媒体提供程序对象 运行 资源获取算法。如果该算法在不中止 此 算法的情况下返回,则加载失败。
媒体提供程序失败:到达此步骤表示媒体资源加载失败。 获取挂起的播放 Promise,并 排队一个媒体元素任务,并给定 媒体元素 以使用结果运行 专用媒体源失败步骤。
等待上一步排队的 任务 执行完成。
返回。在该算法再次触发之前,元素不会尝试加载其他资源。
⌛ 令 urlRecord 为根据给定的 src
属性值(相对于 媒体元素 的 节点文档,在 src
属性上次更改时)编码解析 URL 的结果。
⌛ 如果 urlRecord 不是失败,则将 currentSrc
属性设置为将 URL 序列化器 应用于 urlRecord 的结果。
如果 urlRecord 不是失败,则使用 urlRecord 运行 资源获取算法。如果该算法在不中止此算法的情况下返回,则加载失败。
Failed with attribute:到达此步骤表示媒体资源加载失败或 urlRecord 为失败。 获取挂起的播放 Promise 并根据 媒体元素 排队一个媒体元素任务,以使用结果运行 专用媒体源失败步骤。
等待上一步排队的 任务 执行完成。
返回。在该算法再次触发之前,元素不会尝试加载其他资源。
⌛ 令 pointer 为 媒体元素 的子列表中两个相邻节点定义的位置,将列表的开头(如果存在,则在列表中的第一个子节点之前)和列表的结尾(如果存在,则在列表中的最后一个子节点之后)视为其自身的节点。一个节点是 pointer 之前的节点,另一个节点是 pointer 之后的节点。最初,令 pointer 为 candidate 节点和下一个节点(如果存在)之间或列表的末尾(如果它是最后一个节点)之间的位置。
当节点 插入 和 移除 到 媒体元素 中时,必须按如下方式更新 pointer
其他更改不会影响 pointer。
⌛ 处理候选者:如果 candidate 没有 src
属性,或者其 src
属性的值为空字符串,则结束 同步段,并跳至下面 failed with elements 步骤。
⌛ 如果 candidate 有一个 media
属性,其值不 匹配环境,则结束 同步段,并跳至下面 failed with elements 步骤。
⌛ 令 urlRecord 为根据给定的 candidate 的 src
属性值(相对于 candidate 的 节点文档,在 src
属性上次更改时)编码解析 URL 的结果。
⌛ 如果 urlRecord 为失败,则结束 同步段,并跳至下面 failed with elements 步骤。
⌛ 如果 candidate 有一个 type
属性,其值在解析为 MIME 类型(包括 codecs
参数描述的任何编解码器,对于定义该参数的类型)时,表示 用户代理知道无法呈现的类型,则结束 同步段,并跳至下面 failed with elements 步骤。
⌛ 将 currentSrc
属性设置为将 URL 序列化器 应用于 urlRecord 的结果。
使用 urlRecord 运行 资源获取算法。如果该算法在不中止此算法的情况下返回,则加载失败。
Failed with elements:根据 媒体元素 排队一个媒体元素任务,以在 candidate 上 触发一个名为 error
的事件。
⌛ 查找下一个候选者:令 candidate 为 null。
⌛ 搜索循环:如果 pointer 之后的节点是列表的末尾,则跳至下面的 waiting 步骤。
⌛ 如果 pointer 之后的节点是 source
元素,则令 candidate 为该元素。
⌛ 提前 pointer,以便 pointer 之前的节点现在是之前 pointer 之后的节点,而 pointer 之后的节点是之前 pointer 之后的节点之后的节点(如果存在)。
⌛ 如果 candidate 为 null,则跳回 search loop 步骤。否则,跳回 process candidate 步骤。
⌛ Waiting:将元素的 networkState
属性设置为 NETWORK_NO_SOURCE
值。
⌛ 将元素的 显示海报标志 设置为 true。
⌛ 根据 媒体元素 排队一个媒体元素任务,以将元素的 延迟加载事件标志 设置为 false。这将停止 延迟加载事件。
等待直到 pointer 之后的节点成为除列表末尾之外的节点。(此步骤可能会无限期等待。)
⌛ 将 networkState
重新设置为 NETWORK_LOADING
。
⌛ 跳回上面 find next candidate 步骤。
具有 Promise 列表 promises 的 专用媒体源失败步骤 为以下步骤
将 error
属性设置为使用 MEDIA_ERR_SRC_NOT_SUPPORTED
创建 MediaError
的结果。
将元素的 networkState
属性设置为 NETWORK_NO_SOURCE
值。
将元素的 显示海报标志 设置为 true。
拒绝挂起的播放 Promise,使用 promises 和一个 "NotSupportedError
" DOMException
。
要 验证媒体响应,给定一个 响应 response、一个 媒体资源 resource,以及 "entire resource
" 或一个 (数字, 数字或 "until end
") 元组 byteRange
如果 response 是一个 网络错误,则返回 false。
如果 byteRange 是 "entire resource
",则返回 true。
令 internalResponse 为 response 的 不安全响应。
如果 internalResponse 的 状态 为 200,则返回 true。
如果 internalResponse 的 状态 不是 206,则返回 false。
如果从 internalResponse 提取内容范围值 的结果为失败,则返回 false。
请注意,提取的值不会被使用,特别是不会与 byteRange 进行比较。因此,此步骤充当 `Content-Range
` 标头的语法验证,但是,如果响应上的 `Content-Range
` 值与请求上的 `Range
` 值不匹配,则不视为失败。
令 origin 为 "rewritten
",如果 internalResponse 的 URL 为 null;否则为 internalResponse 的 URL 的 源。
令 previousOrigin 为 resource 的 源。
如果以下任何一项为真
previousOrigin 为 "none
";
origin 和 previousOrigin 均为 "rewritten
";或
则将 resource 的 源 设置为 origin。
否则,如果 response 为 CORS 跨源,则返回 false。
否则,将 resource 的 源 设置为 "multiple
"。
这确保了带有范围标头的透明响应不会通过与来自不同源的其他响应拼接在一起而泄露信息。
返回 true。
对于 媒体元素 和给定的 URL 记录 或 媒体提供程序对象,资源获取算法 如下
如果算法使用 媒体提供程序对象 或 URL 记录 调用,并且该记录的 Blob URL 条目 是一个 Blob URL 条目,其 对象 是一个 媒体提供程序对象,则令 mode 为 local。否则,令 mode 为 remote。
如果 mode 为 remote,则令 当前媒体资源 为由传递给此算法的 URL 记录 给出的资源;否则,令 当前媒体资源 为由 媒体提供程序对象 给出的资源。无论哪种方式,当前媒体资源 现在都是元素的 媒体资源。
移除 媒体元素 的 挂起文本轨道列表 中的所有 媒体资源特定的文本轨道(如果有)。
从以下列表中运行相应的步骤
可选地,运行以下子步骤。如果用户代理打算在用户明确请求资源之前不尝试获取资源(例如,作为实现 preload
属性的 none
关键字的一种方式),则这是预期的行为。
将 networkState
设置为 NETWORK_IDLE
。
在给定的 媒体元素 上排队一个媒体元素任务,以 触发名为 suspend
的事件。
等待任务运行。
等待 实现定义的 事件(例如,用户请求媒体元素开始播放)。
将 networkState
设置为 NETWORK_LOADING
。
令 request 为给定 当前媒体资源 的 URL 记录、destination 和 媒体元素 的 crossorigin
内容属性的当前状态 创建潜在 CORS 请求 的结果。
将 request 的 发起者类型 设置为 destination。
令 byteRange(为 "entire resource
" 或一个 (数字, 数字或 "until end
") 元组)为满足 媒体数据 中缺失数据所需的字节范围。此值是 实现定义的,并且可能依赖于编解码器、网络状况或其他启发式方法。用户代理可以确定完全获取资源,在这种情况下,byteRange 将为 "entire resource
",从字节偏移量获取到末尾,在这种情况下,byteRange 将为 (数字, "until end
"),或者获取两个字节偏移量之间的范围,在这种情况下,byteRange 将为一个 (数字, 数字) 元组,表示这两个偏移量。
如果 byteRange 不是 "entire resource
",则
如果 byteRange[1] 为 "until end
",则 向 request 添加范围标头,给定 byteRange[0]。
否则, 向 request 添加范围标头,给定 byteRange[0] 和 byteRange[1]。
获取 request,并将 processResponse 设置为给定 响应 response 的以下步骤
令 updateMedia 为 在给定的 媒体元素 上排队一个媒体元素任务,以运行下面 媒体数据处理步骤列表 中的第一个合适步骤。(为此使用了一个新任务,以便以下描述的工作相对于合适的 媒体元素事件任务源 而不是使用 网络任务源 进行。)
令 processEndOfMedia 为以下步骤:如果获取过程已在没有错误的情况下完成,包括解码媒体数据,并且如果所有数据都可以在没有网络访问的情况下提供给用户代理,则用户代理必须继续执行下面的 最终步骤。这可能永远不会发生,例如,当流式传输无限资源(如网络广播)时,或者如果资源长于用户代理缓存数据的能力。
如果给定 当前媒体资源 和 byteRange 验证 response 的结果为 false,则中止这些步骤。
否则,根据 updateMedia、processEndOfMedia、一个空算法和 global,增量读取 response 的 主体。
使用通过这种方式获得的 response 的 不安全响应 的内容来更新 媒体数据。response 可以是 CORS 同源 或 CORS 跨源;这会影响 媒体数据 中引用的字幕是否在 API 中公开,以及对于 video
元素,当视频绘制在 canvas
上时,该 canvas
是否会被污染。
媒体元素停顿超时 是一个 实现定义的 时间长度,应该大约为三秒。当一个正在积极尝试获取 媒体数据 的 媒体元素 在持续时间等于 媒体元素停顿超时 的时间内未能接收任何数据时,用户代理必须根据 媒体元素 排队一个媒体元素任务 以
用户代理可以允许用户选择性地阻止或减缓 媒体数据 下载。当 媒体元素 的下载被完全阻止时,用户代理必须表现得好像它已停顿(而不是表现得好像连接已关闭)。下载速度也可能由用户代理自动限制,例如,为了平衡下载与共享相同带宽的其他连接。
用户代理可以决定在任何时候不下载更多内容,例如,在缓冲一小时媒体资源的五分钟后,在等待用户决定是否播放资源时,在等待交互式资源的用户输入时,或者当用户离开页面时。当 媒体元素 的下载被暂停时,用户代理必须根据 媒体元素 排队一个媒体元素任务,以将 networkState
设置为 NETWORK_IDLE
并在元素上 触发一个名为 suspend
的事件。如果并且当资源的下载恢复时,用户代理必须根据 媒体元素 排队一个媒体元素任务,以将 networkState
设置为 NETWORK_LOADING
。在这些任务排队之间,加载被暂停(因此,如上所述,progress
事件不会触发)。
preload
属性提供了一个提示,关于作者认为在没有 autoplay
属性的情况下,多少缓冲是可取的。
当用户代理决定完全暂停下载时,例如,如果它正在等待用户开始播放然后再下载任何其他内容,用户代理必须根据 媒体元素 排队一个媒体元素任务,以将元素的 延迟加载事件标志 设置为 false。这会停止 延迟加载事件。
尽管上述步骤给出了发出请求的算法,但用户代理可以使用除这些确切方法之外的其他方法,尤其是在遇到错误条件时。例如,用户代理可以重新连接到服务器或切换到流协议。只有当用户代理放弃尝试获取资源时,用户代理才必须认为资源有错误,并进入上述步骤的错误分支。
为了确定 媒体资源 的格式,用户代理必须使用 专门用于嗅探音频和视频的规则。
在加载未暂停(见下文)期间,每 350 毫秒(±200 毫秒)或每接收一个字节,以频率 最低 者为准,根据 媒体元素 排队一个媒体元素任务 以
虽然用户代理可能仍然需要网络访问才能获取 媒体资源 的部分内容,但用户代理必须保持在此步骤。
例如,如果用户代理已丢弃视频的前半部分,即使 播放已结束,用户代理也将保持在此步骤,因为用户始终有可能返回到开头。事实上,在这种情况下,一旦 播放结束,用户代理最终将触发一个 suspend
事件,如前所述。
如果存在,由 当前媒体资源 描述的资源包含 媒体数据。它是 CORS 同源。
如果 当前媒体资源 是一个原始数据流(例如,来自 File
对象),则为了确定 媒体资源 的格式,用户代理必须使用 专门用于嗅探音频和视频的规则。否则,如果数据流是预解码的,则格式由相关规范给出。
每当 当前媒体资源 的新数据可用时,根据 媒体元素 排队一个媒体元素任务,以运行下面 媒体数据处理步骤列表 中的第一个合适的步骤。
当 当前媒体资源 永久耗尽(例如,Blob
的所有字节都已处理)时,如果没有解码错误,则用户代理必须继续执行下面的 最终步骤。这可能永远不会发生,例如,如果 当前媒体资源 是一个 MediaStream
。
媒体数据处理步骤列表 如下
DNS 错误、HTTP 4xx 和 5xx 错误(以及其他协议中的等效错误)以及在用户代理确定 当前媒体资源 是否可用之前发生的任何其他严重网络错误,以及使用不受支持的容器格式或对所有数据使用不受支持的编解码器的文件,必须导致用户代理执行以下步骤
用户代理应取消获取过程。
中止此子算法,返回到 资源选择算法。
创建一个 AudioTrack
对象来表示音频轨道。
使用新的 AudioTrack
对象更新 媒体元素 的 audioTracks
属性的 AudioTrackList
对象。
令 enable 为 unknown。
如果 媒体资源 或 当前媒体资源 的 URL 指示要启用的特定一组音频轨道,或者如果用户代理具有有助于选择特定音频轨道以改善用户体验的信息,则:如果此音频轨道是要启用的轨道之一,则将 enable 设置为 true,否则,将 enable 设置为 false。
这可以通过 媒体片段语法 触发,但它也可以例如通过用户代理选择 5.1 环绕声音频轨道而不是立体声音频轨道来触发。
如果 enable 仍然为 unknown,则如果 媒体元素 还没有启用的音频轨道,则将 enable 设置为 true,否则,将 enable 设置为 false。
如果 enable 为 true,则启用此音频轨道,否则,不启用此音频轨道。
触发一个名为 addtrack
的事件,事件目标为此 AudioTrackList
对象,使用 TrackEvent
,其中 track
属性初始化为新的 AudioTrack
对象。
创建一个 VideoTrack
对象来表示视频轨道。
将新的VideoTrack
对象添加到媒体元素的videoTracks
属性的VideoTrackList
对象中。
令 enable 为 unknown。
如果媒体资源或当前媒体资源的URL指示要启用特定的视频轨道集,或者如果用户代理拥有有助于选择特定视频轨道以改善用户体验的信息,则:如果此视频轨道是第一个此类视频轨道,则将enable设置为true,否则将enable设置为false。
这可能再次由媒体片段语法触发。
如果enable仍然为unknown,则如果媒体元素还没有selected视频轨道,则将enable设置为true,否则将enable设置为false。
如果enable为true,则选择此轨道并取消选择之前选择的任何视频轨道,否则,不要选择此视频轨道。如果取消选择其他轨道,则将触发change
事件。
在VideoTrackList
对象上触发一个名为addtrack
的事件,使用TrackEvent
,并将track
属性初始化为新的VideoTrack
对象。
这表示资源可用。用户代理必须按照以下子步骤操作
将时间线偏移量更新为与上一步中建立的媒体时间线中的零时间对应的日期和时间,如果有的话。如果媒体资源没有给出明确的时间和日期,则时间线偏移量必须设置为非数字 (NaN)。
使用资源最后一帧的时间(如果已知)更新duration
属性,该时间位于上面建立的媒体时间线上。如果未知(例如,原则上无限的流),则将duration
属性更新为正无穷大。
用户代理将排队一个媒体元素任务,给定媒体元素,以触发一个名为durationchange
的事件,在此时在元素上触发。
对于video
元素,设置videoWidth
和videoHeight
属性,并排队一个媒体元素任务,给定媒体元素,以触发一个名为resize
的事件,在媒体元素上触发。
如果尺寸随后发生变化,将触发更多resize
事件。
将readyState
属性设置为HAVE_METADATA
。
将readyState
属性设置为新值时,将触发loadedmetadata
DOM 事件。
令jumped为false。
令初始播放位置为零。
如果媒体资源或当前媒体资源的URL指示特定的开始时间,则将初始播放位置设置为该时间,并且如果jumped仍然为false,则跳转到该时间。
如果没有启用的音频轨道,则启用一个音频轨道。这将导致触发change
事件。
如果没有选中的视频轨道,则选择一个视频轨道。这将导致触发change
事件。
一旦readyState
属性达到HAVE_CURRENT_DATA
,在loadeddata
事件触发后,将元素的delaying-the-load-event标志设置为false。这将停止延迟加载事件。
试图减少网络使用量,同时仍然获取每个媒体资源的元数据的用户代理也会在此处停止缓冲,遵循之前描述的规则,这些规则涉及networkState
属性切换到NETWORK_IDLE
值以及触发suspend
事件。
用户代理必须确定媒体资源的持续时间,并在播放前完成此步骤。
将networkState
设置为NETWORK_IDLE
,并在媒体元素上触发一个名为suspend
的事件。
如果用户代理曾经丢弃任何媒体数据,然后需要恢复网络活动以再次获取它,则它必须排队一个媒体元素任务,给定媒体元素,以将networkState
设置为NETWORK_LOADING
。
如果用户代理可以保持媒体资源加载,则算法将继续执行其下面的最后一步,该步骤将中止算法。
在用户代理确定当前媒体资源是否可用(即,一旦媒体元素的readyState
属性不再为HAVE_NOTHING
)后发生的致命网络错误必须导致用户代理执行以下步骤
用户代理应取消获取过程。
将error
属性设置为使用MediaError
创建的结果,其中MEDIA_ERR_NETWORK
。
将元素的networkState
属性设置为NETWORK_IDLE
值。
将元素的delaying-the-load-event标志设置为false。这将停止延迟加载事件。
中止整体资源选择算法。
在用户代理确定当前媒体资源是否可用(即,媒体元素的readyState
属性不再为HAVE_NOTHING
)之后发生的解码媒体数据的致命错误,必须导致用户代理执行以下步骤。
用户代理应取消获取过程。
将error
属性设置为使用MEDIA_ERR_DECODE
创建的 MediaError
的结果。
将元素的networkState
属性设置为NETWORK_IDLE
值。
中止整体资源选择算法。
媒体数据获取过程被用户中止,例如,因为用户按下了“停止”按钮,用户代理必须执行以下步骤。如果在这些步骤运行时调用了load()
方法本身,则不会遵循这些步骤,因为上面的步骤处理了这种特定的中止类型。
用户代理应取消获取过程。
将error
属性设置为使用MEDIA_ERR_ABORTED
创建的 MediaError
的结果。
如果媒体元素的readyState
属性的值等于HAVE_NOTHING
,则将元素的networkState
属性设置为NETWORK_EMPTY
值,将元素的显示海报标志设置为true,并在元素上触发名为emptied
的事件。
否则,将元素的networkState
属性设置为NETWORK_IDLE
值。
中止整体资源选择算法。
服务器返回部分可用但无法最佳渲染的数据必须导致用户代理仅渲染其可以处理的部分,并忽略其余部分。
如果媒体数据是CORS 同源,则使用相关数据运行公开媒体资源特定文本轨道的步骤。
跨源视频不会公开其字幕,因为这会允许攻击,例如恶意站点读取用户内网上的机密视频的字幕。
最后一步:如果用户代理曾经到达此步骤(这只能在整个资源加载并保持可用时发生):中止整体资源选择算法。
当媒体元素需要忘记媒体元素的媒体资源特定轨道时,用户代理必须从媒体元素的文本轨道列表中删除所有媒体资源特定文本轨道,然后清空媒体元素的audioTracks
属性的AudioTrackList
对象,然后清空媒体元素的videoTracks
属性的VideoTrackList
对象。在此过程中不会触发任何事件(特别是不会触发removetrack
事件);调用此算法的算法触发的error
和emptied
事件可以替代使用。
preload
属性是一个枚举属性,具有以下关键字和状态
关键字 | 状态 | 简要说明 |
---|---|---|
auto
| 自动 | 提示用户代理,用户代理可以在不危及服务器的情况下优先考虑用户的需求,包括乐观地下载整个资源。 |
(空字符串) | ||
none
| 无 | 提示用户代理,作者要么不期望用户需要媒体资源,要么服务器希望最大程度地减少不必要的流量。此状态不提供有关如果缓冲开始(例如,用户点击“播放”后)应如何积极地实际下载媒体资源的提示。 |
元数据
| 元数据 | 提示用户代理,作者不期望用户需要媒体资源,但获取资源元数据(尺寸、轨道列表、持续时间等),甚至可能获取前几帧是合理的。如果用户代理精确地仅获取元数据,则媒体元素的readyState 属性将设置为HAVE_METADATA ;但通常,也会获取一些帧,并且可能为HAVE_CURRENT_DATA 或HAVE_FUTURE_DATA 。当媒体资源正在播放时,提示用户代理带宽将被视为稀缺,例如建议限制下载速度,以便以仍然保持一致播放的最低速度获取媒体数据。 |
属性的缺少值默认值和无效值默认值均为实现定义,尽管元数据状态被建议作为在减少服务器负载和提供最佳用户体验之间的折衷方案。
即使媒体资源正在缓冲或播放,也可以更改属性;上面表格中的描述应考虑到这一点。
作者可能会将属性从“none
”或“metadata
”动态切换到“auto
”,一旦用户开始播放。例如,在一个包含许多视频的页面上,这可能用于指示许多视频在未被请求时不应下载,但一旦请求了一个视频,则应积极地下载它。
preload
属性旨在向用户代理提供一个提示,告知作者认为哪种方式会导致最佳的用户体验。例如,基于明确的用户偏好或基于可用的连接,该属性可能完全被忽略。
preload
IDL 属性必须反映同名内容属性,仅限于已知值。
autoplay
属性可以覆盖preload
属性(因为如果媒体播放,它自然需要先缓冲,无论preload
属性提供的提示如何)。但是,同时包含两者并不算错误。
media.buffered
所有当前引擎都支持。
返回一个TimeRanges
对象,该对象表示用户代理已缓冲的媒体资源的范围。
buffered
属性必须返回一个新的静态规范化的 TimeRanges
对象,该对象表示用户代理已缓冲的媒体资源的范围(如果有),在评估属性时。用户代理必须准确地确定可用的范围,即使对于只能通过繁琐检查才能确定的媒体流也是如此。
通常这将是一个固定在零点的单个范围,但如果例如,用户代理使用 HTTP 范围请求来响应搜索,则可能存在多个范围。
用户代理可能会丢弃先前缓冲的数据。
因此,在某个时间点包含在buffered
属性返回的对象的范围内的某个时间位置最终可能不包含在稍后时间由同一属性返回的对象的范围中。
每次都返回一个新对象对于属性 getter 来说是一个不好的模式,这里之所以保留是因为更改它成本较高。新的 API 不应复制此模式。
media.duration
所有当前引擎都支持。
返回媒体资源的长度(单位:秒),假设媒体资源的起始时间为零。
如果持续时间不可用,则返回 NaN。
对于无界流,返回 Infinity。
media.currentTime [ = value ]
所有当前引擎都支持。
返回官方播放位置(单位:秒)。
可以设置此属性,以跳转到指定时间。
一个媒体资源有一个媒体时间线,它将时间(单位:秒)映射到媒体资源中的位置。时间线的原点是其最早定义的位置。时间线的持续时间是其最后定义的位置。
建立媒体时间线:如果媒体资源以某种方式指定了一个显式时间线,其原点不是负数(即为每一帧提供一个特定的时间偏移量,并为第一帧提供一个零或正的偏移量),则媒体时间线应为该时间线。(媒体资源是否可以指定时间线取决于媒体资源的格式。)如果媒体资源指定了一个显式的开始时间和日期,则该时间和日期应被视为媒体时间线中的零点;时间线偏移量将是时间和日期,通过getStartDate()
方法公开。
如果媒体资源具有不连续的时间线,则用户代理必须将资源开始时使用的时间线扩展到整个资源,以便媒体资源的媒体时间线从最早可能的位置(如下所述)开始线性增加,即使底层媒体数据具有乱序甚至重叠的时间码。
例如,如果两个片段已连接到一个视频文件中,但视频格式公开了这两个片段的原始时间,则视频数据可能会公开一个时间线,例如,00:15..00:29,然后是 00:05..00:38。但是,用户代理不会公开这些时间;相反,它会将时间公开为 00:15..00:29 和 00:29..01:02,作为一个单独的视频。
在媒体资源没有显式时间线的罕见情况下,媒体时间线上的零时间应对应于媒体资源的第一帧。在媒体资源没有任何显式时间信息(甚至没有帧持续时间)的更罕见情况下,用户代理必须以实现定义的方式自行确定每一帧的时间。
没有显式时间线但有显式帧持续时间的文件格式的一个示例是动画 GIF 格式。没有任何显式时间信息的格式的一个示例是 JPEG-push 格式(multipart/x-mixed-replace
带有 JPEG 帧,通常用作 MJPEG 流的格式)。
如果在没有时间信息的情况下,用户代理仍然能够跳转到服务器最初提供的第一帧之前的某个点,则零时间应对应于媒体资源的最早可跳转时间;否则,它应对应于从服务器接收到的第一帧(用户代理开始接收流的媒体资源中的点)。
在撰写本文时,尚无已知的格式缺少显式帧时间偏移量,但仍然支持跳转到服务器发送的第一帧之前的帧。
考虑来自电视广播公司的流,它在 10 月一个阳光明媚的星期五下午开始流式传输,并且始终向连接的用户代理发送相同媒体时间线上的媒体数据,其零时间设置为该流的开始。几个月后,连接到此流的用户代理会发现他们收到的第一帧的时间有数百万秒。 getStartDate()
方法将始终返回广播开始的日期;这将允许控制器在其滑块中显示实际时间(例如,“下午 2:30”),而不是相对于广播开始的时间(“8 个月、4 小时、12 分钟和 23 秒”)。
考虑一个流,它承载一个带有几个连接片段的视频,由一个服务器广播,该服务器不允许用户代理请求特定时间,而是以预定的顺序流式传输视频数据,并且始终将交付的第一帧识别为时间为零的帧。如果用户代理连接到此流并接收定义为覆盖 2010-03-20 23:15:00 UTC 到 2010-03-21 00:05:00 UTC 和 2010-02-12 14:25:00 UTC 到 2010-02-12 14:35:00 UTC 时间戳的片段,它将使用从 0 秒开始并扩展到 3600 秒(一小时)的媒体时间线公开此内容。假设流服务器在第二个剪辑结束时断开连接,则duration
属性将返回 3600。 getStartDate()
方法将返回一个Date
对象,其时间对应于 2010-03-20 23:15:00 UTC。但是,如果不同的用户代理五分钟后连接,它将(大概)接收覆盖 2010-03-20 23:20:00 UTC 到 2010-03-21 00:05:00 UTC 和 2010-02-12 14:25:00 UTC 到 2010-02-12 14:35:00 UTC 时间戳的片段,并将使用从 0 秒开始并扩展到 3300 秒(五十五分钟)的媒体时间线公开此内容。在这种情况下, getStartDate()
方法将返回一个Date
对象,其时间对应于 2010-03-20 23:20:00 UTC。
在这两个示例中,seekable
属性将提供控制器希望在其 UI 中实际显示的范围;通常,如果服务器不支持跳转到任意时间,则这将是从用户代理连接到流的时刻到用户代理获取的最新帧的时间范围;但是,如果用户代理开始丢弃早期信息,则实际范围可能会更短。
无论如何,用户代理必须确保使用已建立的媒体时间线的最早可能的位置(如下所述)大于或等于零。
媒体时间线还具有关联的时钟。使用哪个时钟由用户代理定义,并且可能取决于媒体资源,但它应该近似于用户的挂钟。
媒体元素有一个当前播放位置,它最初(即在没有媒体数据的情况下)必须为零秒。当前播放位置是媒体时间线上的一个时间。
媒体元素还有一个官方播放位置,它最初必须设置为零秒。官方播放位置是当前播放位置的近似值,在脚本运行期间保持稳定。
媒体元素还有一个默认播放开始位置,它最初必须设置为零秒。此时间用于允许即使在媒体加载之前也能跳转到元素。
每个媒体元素都有一个显示海报标志。创建媒体元素时,必须将此标志设置为 true。此标志用于控制用户代理何时为video
元素显示海报帧而不是显示视频内容。
currentTime
属性在获取时必须返回媒体元素的默认播放开始位置,除非该值为零,在这种情况下,它必须返回元素的官方播放位置。返回的值必须以秒为单位表示。在设置时,如果媒体元素的readyState
为HAVE_NOTHING
,则它必须将媒体元素的默认播放开始位置设置为新值;否则,它必须将官方播放位置设置为新值,然后跳转到新值。新值必须解释为以秒为单位。
如果媒体资源是流媒体资源,则用户代理可能无法在资源从其缓冲区过期后获取资源的某些部分。类似地,某些媒体资源可能具有媒体时间线,该时间线不是从零开始的。最早可能的位置是用户代理可以再次获取的流或资源中最早的位置。它也是媒体时间线上的一个时间点。
最早可能的位置在 API 中没有明确公开;它对应于seekable
属性的TimeRanges
对象的第一个范围的开始时间(如果有),否则对应于当前播放位置。
当最早可能的位置发生变化时:如果当前播放位置在最早可能的位置之前,则用户代理必须跳转到最早可能的位置;否则,如果用户代理在过去 15 到 250 毫秒内没有在元素上触发timeupdate
事件,并且尚未运行此类事件的事件处理程序,则用户代理必须将媒体元素任务排队,并提供媒体元素,以便触发名为timeupdate
的事件。
由于上述要求以及资源获取算法中当片段的元数据已知时触发的要求,当前播放位置永远不会小于最早可能的位置。
如果在任何时间用户代理了解到音频或视频轨道已结束,并且与该轨道相关的所有媒体数据对应于媒体时间线中早于最早可能的位置的部分,则用户代理可以将媒体元素任务排队,并提供媒体元素以执行以下步骤
从audioTracks
属性的AudioTrackList
对象或videoTracks
属性的VideoTrackList
对象中删除该轨道(视情况而定)。
触发名为removetrack
的事件,在媒体元素上述的AudioTrackList
或VideoTrackList
对象上,使用TrackEvent
,并将track
属性初始化为表示该轨道的AudioTrack
或VideoTrack
对象。
duration
属性必须返回媒体资源结束时间(以秒为单位),时间基于媒体时间线。如果没有媒体数据可用,则属性必须返回非数字(NaN)值。如果媒体资源不知道是否有边界(例如流媒体广播或没有宣布结束时间的直播事件),则属性必须返回正无穷大值。
用户代理必须在播放媒体数据的任何部分之前以及在将readyState
设置为大于或等于HAVE_METADATA
的值之前确定媒体资源的持续时间,即使这样做需要获取资源的多个部分。
当媒体资源的长度更改为已知值(例如,从未知更改为已知,或从先前确定的长度更改为新长度)时,用户代理必须将媒体元素任务排队,并提供媒体元素,以便触发名为durationchange
的事件,该事件在媒体元素上触发。(加载新的媒体资源时,如果持续时间被重置,则不会触发此事件。)如果持续时间发生变化,导致当前播放位置最终大于媒体资源的结束时间,则用户代理还必须跳转到媒体资源的结束时间。
如果“无限”流由于某种原因结束,则持续时间将从正无穷大更改为流中最后一帧或样本的时间,并且将触发durationchange
事件。类似地,如果用户代理最初估计了媒体资源的持续时间而不是精确地确定它,并且后来根据新信息修改了估计,则持续时间将发生变化,并且将触发durationchange
事件。
一些视频文件还具有一个明确的日期和时间,对应于媒体时间线中的零时间,称为时间线偏移量。最初,时间线偏移量必须设置为非数字(NaN)。
getStartDate()
方法必须返回一个新的Date
对象,表示当前时间线偏移量。
loop
属性是一个布尔属性,如果指定,则表示媒体元素在到达末尾时将跳转回媒体资源的开头。
所有当前引擎都支持。
loop
IDL 属性必须反映同名内容属性。
media.readyState
所有当前引擎都支持。
返回一个值,该值表示元素相对于呈现当前播放位置的当前状态,来自以下列表中的代码。
媒体元素具有就绪状态,该状态描述了它们在当前播放位置处准备呈现的程度。可能的值如下;在任何特定时间,媒体元素的就绪状态是描述元素状态的最大值
HAVE_NOTHING
(数值 0)没有关于媒体资源的信息可用。没有当前播放位置的数据可用。媒体元素的networkState
属性设置为NETWORK_EMPTY
始终处于HAVE_NOTHING
状态。
HAVE_METADATA
(数值 1)已获取了足够的资源,可以获得资源的持续时间。在视频
元素的情况下,还可以获得视频的尺寸。没有媒体数据可用于立即当前播放位置。
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
(至少包括当前帧和下一帧)之间的差异可以忽略不计(在极端情况下,只有一帧)。只有当页面提供“逐帧”导航的界面时,这种区别才真正重要。
当媒体元素的networkState
不是NETWORK_EMPTY
时的就绪状态发生变化时,用户代理必须按照下面给出的步骤操作。
应用以下列表中第一个适用的子步骤集。
HAVE_NOTHING
,而新的就绪状态是HAVE_METADATA
给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为loadedmetadata
的事件。
HAVE_METADATA
,而新的就绪状态是HAVE_CURRENT_DATA
或更高如果这是自上次调用load()
算法以来,此媒体元素第一次发生这种情况,则用户代理必须给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为loadeddata
的事件。
如果新的就绪状态是HAVE_FUTURE_DATA
或HAVE_ENOUGH_DATA
,则还必须运行下面的相关步骤。
HAVE_FUTURE_DATA
或更高,而新的就绪状态是HAVE_CURRENT_DATA
或更低如果媒体元素在其readyState
属性更改为低于HAVE_FUTURE_DATA
的值之前是可能正在播放的,并且该元素尚未结束播放,并且播放尚未因错误停止、因用户交互暂停或因带内内容暂停,则用户代理必须给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为timeupdate
的事件,并且给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为waiting
的事件。
HAVE_CURRENT_DATA
或更低,而新的就绪状态是HAVE_FUTURE_DATA
用户代理必须给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为canplay
的事件。
HAVE_ENOUGH_DATA
如果之前的就绪状态是HAVE_CURRENT_DATA
或更低,则用户代理必须给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为canplay
的事件,并且如果元素的paused
属性为false,则对该元素发出正在播放的通知。
用户代理必须给定媒体元素,排队一个媒体元素任务,以便在该元素上触发一个名为canplaythrough
的事件。
如果该元素不符合自动播放条件,则用户代理必须中止这些子步骤。
用户代理可以运行以下子步骤。
paused
属性设置为false。play
的事件。或者,如果该元素是video
元素,则用户代理可以开始观察该元素是否与视口相交。当该元素开始与视口相交时,如果该元素仍然符合自动播放条件,则运行上面的子步骤。可选地,当该元素停止与视口相交时,如果可以自动播放标志仍然为true且autoplay
属性仍然指定,则运行以下子步骤。
pause
的事件。只要可以自动播放标志为true,播放和暂停的子步骤就可以多次运行,因为元素开始或停止与视口相交。
用户代理不需要支持自动播放,建议用户代理尊重用户的相关偏好。强烈建议作者使用autoplay
属性而不是使用脚本强制视频播放,以便用户可以根据需要覆盖此行为。
媒体元素的准备就绪状态可能在这些状态之间不连续地跳转。例如,媒体元素的状态可以从HAVE_METADATA
直接跳转到HAVE_ENOUGH_DATA
,而无需经过HAVE_CURRENT_DATA
和HAVE_FUTURE_DATA
状态。
在获取时,readyState
IDL 属性必须返回上面描述的值,该值描述了媒体元素的当前准备就绪状态。
autoplay
属性是一个布尔属性。当存在时,用户代理(如本文档中描述的算法)将在其能够做到这一点且不会停止的情况下自动开始播放媒体资源。
强烈建议作者使用autoplay
属性,而不是使用脚本触发自动播放,因为这允许用户在不需要时覆盖自动播放,例如,当使用屏幕阅读器时。还鼓励作者考虑完全不使用自动播放行为,而是让用户代理等待用户显式启动播放。
所有当前引擎都支持。
autoplay
IDL 属性必须反映同名内容属性。
media.paused
所有当前引擎都支持。
如果播放已暂停,则返回 true;否则返回 false。
media.ended
所有当前引擎都支持。
如果播放已到达媒体资源的末尾,则返回 true。
media.defaultPlaybackRate [ = value ]
HTMLMediaElement/defaultPlaybackRate
所有当前引擎都支持。
返回默认播放速率,用于用户未快进或倒退浏览媒体资源时。
可以设置,以更改默认播放速率。
默认速率对播放没有直接影响,但如果用户切换到快进模式,当他们返回正常播放模式时,预计播放速率将恢复到默认播放速率。
media.playbackRate [ = value ]
所有当前引擎都支持。
返回当前播放速率,其中 1.0 为正常速度。
可以设置,以更改播放速率。
media.preservesPitch
HTMLMediaElement/preservesPitch
如果playbackRate
不为 1.0,则返回 true,表示使用音调保持算法。默认值为 true。
可以设置为 false,以便媒体资源的音频音调根据playbackRate
上下变化。这对于美观和性能原因很有用。
media.played
返回一个TimeRanges
对象,该对象表示用户代理已播放的媒体资源的范围。
media.play()
所有当前引擎都支持。
media.pause()
所有当前引擎都支持。
paused
属性表示媒体元素是否已暂停。该属性最初必须为 true。
如果readyState
属性处于HAVE_NOTHING
状态、HAVE_METADATA
状态或HAVE_CURRENT_DATA
状态,或者如果元素已因用户交互而暂停或因带内内容而暂停,则媒体元素为被阻止的媒体元素。
当paused
属性为 false,元素未结束播放,播放未因错误而停止,并且元素不是被阻止的媒体元素时,则称媒体元素为可能正在播放。
由于元素可能正在播放且其readyState
属性更改为低于HAVE_FUTURE_DATA
的值,因此可能会触发waiting
DOM 事件触发。
当以下所有条件都为真时,则称媒体元素为可自动播放
如果用户代理和系统允许在当前上下文中播放媒体,则称媒体元素为允许播放。
例如,用户代理可能仅在媒体元素的Window
对象具有短暂激活时才允许播放,但可以例外,允许在静音时播放。
当以下条件满足时,则称媒体元素已结束播放
元素的readyState
属性为HAVE_METADATA
或更高,并且
或者
或者
ended
属性必须返回 true,如果上次事件循环到达步骤 1时,媒体元素已结束播放且播放方向为向前,否则返回 false。
当元素的readyState
属性为HAVE_METADATA
或更高,并且用户代理在处理媒体数据期间遇到非致命错误,并且由于该错误,无法在当前播放位置播放内容时,则称媒体元素已因错误而停止。
当paused
属性为 false,readyState
属性为HAVE_FUTURE_DATA
或HAVE_ENOUGH_DATA
,并且用户代理已到达媒体资源中用户必须进行选择才能继续播放的点时,则称媒体元素已因用户交互而暂停。
当一个媒体元素由于可能正在播放,因用户交互而暂停播放时,用户代理必须排队一个媒体元素任务,并根据媒体元素在该元素上触发一个名为timeupdate
的事件。
当媒体元素的paused
属性为false,readyState
属性为HAVE_FUTURE_DATA
或HAVE_ENOUGH_DATA
,并且用户代理已暂停媒体资源的播放以播放时间锚定到媒体资源且长度不为零的内容,或播放时间锚定到媒体资源的一部分但长度超过该部分的内容时,则称该媒体元素因嵌入内容而暂停。
例如,当用户代理正在播放来自外部 WebVTT 文件的音频描述,并且为提示生成的合成语音时长超过了文本轨道提示开始时间和文本轨道提示结束时间之间的时间时,媒体元素就会因嵌入内容而暂停。
当当前播放位置到达媒体资源的末尾,并且播放方向为向前时,用户代理必须执行以下步骤。
根据媒体元素排队一个媒体元素任务,并执行以下步骤。
在媒体元素上触发一个名为timeupdate
的事件。
如果媒体元素已结束播放,播放方向为向前,并且paused为false,则
将paused
属性设置为true。
获取挂起的播放 Promise,并使用结果和一个"AbortError
"DOMException
拒绝挂起的播放 Promise。
当当前播放位置到达媒体资源的最早可能的位置,并且播放方向为向后时,用户代理只需根据媒体元素排队一个媒体元素任务,在该元素上触发一个名为timeupdate
的事件。
这里的“到达”并不意味着当前播放位置需要在正常播放过程中发生变化;例如,它可能是通过跳转实现的。
defaultPlaybackRate
属性指定了媒体资源播放的期望速度,以其固有速度的倍数表示。该属性是可变的:获取它必须返回上次设置的值,如果尚未设置,则返回 1.0;设置该属性必须将其设置为新值。
当用户代理向用户公开用户界面时,会使用defaultPlaybackRate
。
playbackRate
属性指定了有效的播放速率,即媒体资源播放的速度,以其固有速度的倍数表示。如果它不等于defaultPlaybackRate
,则意味着用户正在使用快速转发或慢动作播放等功能。该属性是可变的:获取它必须返回上次设置的值,如果尚未设置,则返回 1.0;设置时,用户代理必须执行以下步骤。
如果用户代理不支持给定的值,则抛出一个"NotSupportedError
"DOMException
。
将playbackRate
设置为新值,如果元素可能正在播放,则更改播放速度。
当defaultPlaybackRate
或playbackRate
属性的值发生更改(无论是通过脚本设置还是由用户代理直接更改,例如响应用户控制)时,用户代理必须根据媒体元素排队一个媒体元素任务,在媒体元素上触发一个名为ratechange
的事件。用户代理必须平滑地处理属性更改,并且不得因响应而引入任何可感知的播放间隙或静音。
preservesPitch
获取器的步骤是,如果在播放期间使用了保音调算法,则返回 true。设置器的步骤是相应地打开或关闭保音调算法,而不会出现任何可感知的播放间隙或静音。默认情况下,必须使用此类保音调算法(即,获取器将最初返回 true)。
played
属性必须返回一个新的静态规范化的 TimeRanges
对象,该对象表示在评估该属性时,通过正常播放期间当前播放位置的通常单调递增到达的媒体资源的媒体时间线上的点范围(如果有)。
每次都返回一个新对象对于属性 getter 来说是一个不好的模式,这里之所以保留是因为更改它成本较高。新的 API 不应复制此模式。
每个媒体元素都有一个挂起的播放 Promise 列表,该列表最初必须为空。
要为媒体元素获取挂起的播放 Promise,用户代理必须执行以下步骤。
令promises为一个空的 Promise 列表。
将媒体元素的挂起的播放 Promise 列表复制到promises。
要使用 Promise 列表promises为媒体元素解析挂起的播放 Promise,用户代理必须使用 undefined 解析promises中的每个 Promise。
要使用 Promise 列表promises和异常名称error为媒体元素拒绝挂起的播放 Promise,用户代理必须使用error拒绝promises中的每个 Promise。
要为媒体元素通知正在播放,用户代理必须执行以下步骤。
获取挂起的播放 Promise,并令promises为结果。
根据元素排队一个媒体元素任务,并执行以下步骤。
使用promises解析挂起的播放 Promise。
当在媒体元素上调用play()
方法时,用户代理必须执行以下步骤。
如果媒体元素的error
属性不为 null,并且其code为MEDIA_ERR_SRC_NOT_SUPPORTED
,则返回一个被拒绝的 Promise,其中包含一个"NotSupportedError
" DOMException
。
令promise为一个新的 Promise,并将promise添加到挂起的播放 Promise 列表中。
返回promise。
媒体元素的内部播放步骤如下所示
如果媒体元素的networkState
属性的值为NETWORK_EMPTY
,则调用媒体元素的资源选择算法。
如果播放已结束并且播放方向为向前,则跳转到媒体资源的最早可能的位置。
这将导致用户代理排队一个媒体元素任务,给定媒体元素,以在媒体元素上触发一个名为timeupdate
的事件。
将paused
的值更改为 false。
排队一个媒体元素任务,给定媒体元素,以在元素上触发一个名为play
的事件。
如果媒体元素的readyState
属性的值为HAVE_NOTHING
、HAVE_METADATA
或HAVE_CURRENT_DATA
,则排队一个媒体元素任务,给定媒体元素,以在元素上触发一个名为waiting
的事件。
否则,媒体元素的readyState
属性的值为HAVE_FUTURE_DATA
或HAVE_ENOUGH_DATA
:对元素通知正在播放。
否则,如果媒体元素的readyState
属性的值为HAVE_FUTURE_DATA
或HAVE_ENOUGH_DATA
,则获取挂起的播放 Promise,并排队一个媒体元素任务,给定媒体元素,以使用结果解析挂起的播放 Promise。
媒体元素已经在播放。但是,promise可能会在排队的任务运行之前被拒绝。
当调用pause()
方法时,以及当用户代理需要暂停媒体元素时,用户代理必须运行以下步骤
如果媒体元素的networkState
属性的值为NETWORK_EMPTY
,则调用媒体元素的资源选择算法。
媒体元素的内部暂停步骤如下所示
如果媒体元素的paused
属性为 false,则运行以下步骤
将paused
的值更改为 true。
获取挂起的播放 Promise,并令promises为结果。
排队一个媒体元素任务,给定媒体元素以及以下步骤
在元素上触发一个名为timeupdate
的事件。
使用promises和一个"AbortError
" DOMException
拒绝挂起的播放 Promise。
如果元素的playbackRate
为正或零,则播放方向为向前。否则,为向后。
当媒体元素可能正在播放并且其Document
为一个完全激活的 Document
时,其当前播放位置必须以元素的playbackRate
单位的媒体时间/单位时间的媒体时间轴时钟单调递增。(本规范始终将其称为增加,但如果元素的playbackRate
为负,则该增加实际上可能是减少。)
元素的playbackRate
可以为 0.0,在这种情况下,当前播放位置不会移动,尽管播放未暂停(paused
不会变为 true,并且不会触发pause
事件)。
本规范未定义用户代理如何实现适当的播放速率——根据协议和可用媒体,用户代理可能会与服务器协商,让服务器以适当的速率提供媒体数据,从而(除了更改速率和服务器更新流的播放速率之间的这段时间之外)客户端实际上不必丢弃或插值任何帧。
任何时候用户代理提供稳定状态时,都必须将官方播放位置设置为当前播放位置。
在播放方向为向后时,任何相应的音频都必须静音。当元素的playbackRate
过低或过高以至于用户代理无法有效播放音频时,相应的音频也必须静音。如果元素的playbackRate
不为 1.0 且preservesPitch
为 true,则用户代理必须应用音调调整以保留音频的原始音调。否则,用户代理必须加快或减慢音频速度,而无需任何音调调整。
当一个媒体元素处于可能正在播放状态时,其播放的音频数据必须与当前播放位置同步,并且音量为该元素的有效媒体音量。用户代理必须播放在事件循环上次到达步骤 1时启用的音频轨道的音频。
当一个媒体元素不处于可能正在播放状态时,不得为该元素播放音频。
媒体元素在可能正在播放但不在文档中时,不得播放任何视频,但应播放任何音频组件。媒体元素不得仅因为对其的所有引用都已删除而停止播放;只有当媒体元素处于无法再由该元素播放任何音频的状态时,才能对该元素进行垃圾回收。
即使某个元素不再存在显式引用,也可能播放音频,即使该元素尚未积极播放:例如,它可能已取消暂停但由于等待内容缓冲而处于停滞状态,或者它可能仍在缓冲,但具有一个suspend
事件监听器开始播放。即使媒体资源没有音频轨道的媒体元素,如果它有一个更改媒体资源的事件监听器,最终也可能会再次播放音频。
每个媒体元素都有一个新引入的提示列表,该列表最初为空。每当将文本轨道提示添加到文本轨道的提示列表中,而该文本轨道又位于媒体元素的文本轨道列表中时,该提示必须添加到媒体元素的新引入的提示列表中。每当将文本轨道添加到媒体元素的文本轨道列表中时,该文本轨道的提示列表中的所有提示都必须添加到媒体元素的新引入的提示列表中。当媒体元素的新引入的提示列表添加了新的提示,而媒体元素的显示海报标志未设置时,用户代理必须运行时间流逝步骤。
当从文本轨道的提示列表中删除文本轨道提示,以及每当从媒体元素的文本轨道列表中删除文本轨道时,如果媒体元素的显示海报标志未设置,则用户代理必须运行时间流逝步骤。
当媒体元素的当前播放位置发生变化(例如,由于播放或查找)时,用户代理必须运行时间流逝步骤。为了支持依赖于提示事件触发时间准确性的用例(例如,将字幕与视频中的镜头切换同步),用户代理应尽可能接近提示在媒体时间轴上的位置触发提示事件,理想情况下在 20 毫秒内。如果在步骤运行期间当前播放位置发生变化,则用户代理必须等待步骤完成,然后必须立即重新运行步骤。因此,这些步骤会尽可能频繁或根据需要运行。
如果一次迭代花费的时间很长,这会导致用户代理匆忙向前“赶上”而跳过持续时间较短的提示,因此这些提示将不会出现在activeCues
列表中。
时间流逝步骤如下
令当前提示为提示列表,初始化为包含媒体元素的所有 或显示的文本轨道(而非禁用的文本轨道)的所有提示,这些提示的开始时间小于或等于当前播放位置,并且结束时间大于当前播放位置。
如果自上次运行此算法以来,当前播放位置仅通过在正常播放期间的常规单调递增而发生变化,则令错过的提示为其他提示中提示列表,这些提示的开始时间大于或等于上次时间,并且结束时间小于或等于当前播放位置。否则,令错过的提示为空列表。
如果时间是通过在正常播放期间当前播放位置的常规单调递增达到的,并且用户代理在过去 15 到 250 毫秒内尚未在该元素上触发timeupdate
事件,并且尚未运行此类事件的事件处理程序,则用户代理必须排队一个媒体元素任务,其中给定媒体元素,以便在该元素上触发一个名为timeupdate
的事件。(在其他情况下,例如显式查找,相关事件会在更改当前播放位置的整个过程中触发。)
因此,事件的触发频率不应快于约 66Hz 或慢于 4Hz(假设事件处理程序运行时间不超过 250 毫秒)。鼓励用户代理根据系统负载和每次处理事件的平均成本来调整事件的频率,以便 UI 更新的频率不高于用户代理在解码视频时可以舒适地处理的频率。
如果当前提示中的所有提示都已设置其文本轨道提示活动标志,其他提示中的任何提示都未设置其文本轨道提示活动标志,并且错过的提示为空,则返回。
如果时间是通过在正常播放期间当前播放位置的常规单调递增达到的,并且其他提示中存在已设置其文本轨道提示退出暂停标志的提示,并且这些提示要么已设置其文本轨道提示活动标志,要么也位于错过的提示中,则立即暂停媒体元素。
在其他情况下,例如显式查找,即使该提示已设置其文本轨道提示退出暂停标志,也不会通过超过提示的结束时间来暂停播放。
令事件为任务列表,最初为空。此列表中的每个任务都将与文本轨道、文本轨道提示和时间相关联,这些信息用于在排队任务之前对列表进行排序。
令受影响的轨道为文本轨道列表,最初为空。
当以下步骤说明为文本轨道提示目标准备一个名为事件的事件,时间为时间时,用户代理必须运行以下步骤
对于missed cues 中的每个文本轨道提示,准备一个名为enter
的事件,用于具有文本轨道提示开始时间 的TextTrackCue
对象。
对于other cues 中的每个文本轨道提示,如果其文本轨道提示激活标志 已设置或在missed cues 中,则准备一个名为exit
的事件,用于具有文本轨道提示结束时间 和文本轨道提示开始时间 中较晚者时间的TextTrackCue
对象。
对于current cues 中的每个文本轨道提示,如果其文本轨道提示激活标志 未设置,则准备一个名为enter
的事件,用于具有文本轨道提示开始时间 的TextTrackCue
对象。
按时间升序对events 中的任务 进行排序(较早时间的任务 优先)。
进一步按与这些任务 关联的文本轨道提示 的相对文本轨道提示顺序 对events 中具有相同时间的任务 进行排序。
最后,按将触发enter
事件的任务 放在触发exit
事件的任务 之前的方式,对具有相同时间和相同文本轨道提示顺序 的events 中的任务 进行排序。
对于events 中的每个任务,按列表顺序排队一个媒体元素任务,并给出媒体元素。
对于affected tracks 中的每个文本轨道,按列表顺序排队一个媒体元素任务,并给出媒体元素,以在TextTrack
对象上触发名为cuechange
的事件;如果文本轨道 具有相应的track
元素,则还需在track
元素上触发名为cuechange
的事件。
设置current cues 中所有提示 的文本轨道提示激活标志,并取消设置other cues 中所有提示 的文本轨道提示激活标志。
运行affected tracks 中每个文本轨道(正在显示)的更新文本轨道渲染的规则,如果文本轨道 的文本轨道语言 不是空字符串,则将其作为后备语言。例如,对于基于 WebVTT 的文本轨道,更新 WebVTT 文本轨道显示的规则。 [WEBVTT]
对于上述算法的目的,只有当文本轨道提示 列在文本轨道 的文本轨道提示列表 中时,才将其视为该文本轨道 的一部分,而不仅仅是与文本轨道 关联。
如果媒体元素 的节点文档 停止成为完全活动 文档,则播放将停止,直到文档再次处于活动状态。
当媒体元素 从Document
中移除 时,用户代理必须运行以下步骤
media.seeking
如果用户代理当前正在查找,则返回 true。
media.seekable
所有当前引擎都支持。
返回一个TimeRanges
对象,该对象表示用户代理可以查找到的媒体资源 的范围。
media.fastSeek(time)
尽快查找给定time 附近的位置,以速度换取精度。(要查找精确的时间,请使用currentTime
属性)。
如果未加载媒体资源,则此操作无效。
seeking
属性最初必须具有值 false。
fastSeek(time)
方法必须查找 time 给定的时间,并设置近似速度标志。
当用户代理需要查找 媒体资源 中的特定新播放位置 时,可以选择设置近似速度标志,这意味着用户代理必须运行以下步骤。此算法与事件循环 机制紧密交互;特别是,它有一个同步部分(作为事件循环 算法的一部分触发)。该部分中的步骤用⌛标记。
如果媒体元素 的readyState
为HAVE_NOTHING
,则返回。
如果元素的seeking
IDL 属性为 true,则此算法的另一个实例已经在运行。中止该算法的其他实例,而无需等待其正在运行的步骤完成。
将seeking
IDL 属性设置为 true。
如果查找是响应 DOM 方法调用或 IDL 属性设置而触发的,则继续执行脚本。这些步骤的其余部分必须并行 运行。除了用⌛标记的步骤外,它们可以随时被此算法的另一个实例调用而中止。
如果新播放位置 小于最早可能的位置,则将其改为该位置。
如果(可能已更改的)新的播放位置不在seekable
属性中给出的任何范围内,则将其设置为seekable
属性中给出的范围内最接近新的播放位置的位置。如果两个位置都满足该约束(即新的播放位置正好位于seekable
属性中两个范围的中间),则使用最接近当前播放位置的位置。如果seekable
属性中未给出任何范围,则将seeking
IDL 属性设置为 false 并返回。
如果设置了approximate-for-speed标志,则将新的播放位置调整为允许播放立即恢复的值。如果此步骤之前的新的播放位置早于当前播放位置,则调整后的新的播放位置也必须早于当前播放位置。类似地,如果此步骤之前的新的播放位置晚于当前播放位置,则调整后的新的播放位置也必须晚于当前播放位置。
例如,用户代理可以捕捉到附近的关键帧,这样它就不必在恢复播放之前花费时间解码然后丢弃中间帧。
将当前播放位置设置为新的播放位置。
如果媒体元素在开始查找之前是可能正在播放的,但查找导致其readyState
属性更改为低于HAVE_FUTURE_DATA
的值,则将在该元素上触发waiting
事件将被触发。
此步骤设置当前播放位置,因此可以立即触发其他条件,例如关于播放何时“到达媒体资源的末尾”(循环处理逻辑的一部分)的规则,甚至在用户代理实际能够呈现该位置的媒体数据之前(如下一步骤中确定)。
currentTime
属性返回官方播放位置,而不是当前播放位置,因此在脚本执行之前更新,与该算法分开。
等待用户代理确定新的播放位置的媒体数据是否可用,如果可用,则等待其解码足够的数据以回放该位置。
⌛ 将seeking
IDL 属性设置为 false。
⌛ 运行时间推移步骤。
⌛ 将媒体元素任务排队,给定媒体元素以触发名为timeupdate
的事件在该元素上。
seekable
属性必须返回一个新的静态规范化的TimeRanges
对象,该对象表示用户代理能够跳转到的媒体资源的范围(如果有),在评估属性时。
如果用户代理可以跳转到媒体资源中的任何位置,例如,因为它是一个简单的电影文件,并且用户代理和服务器支持 HTTP Range 请求,则该属性将返回一个具有一个范围的对象,其开始时间为第一帧的时间(最早可能的位置,通常为零),其结束时间与第一帧的时间加上duration
属性的值相同(这将等于最后一帧的时间,并且可能为正无穷大)。
该范围可能会不断变化,例如,如果用户代理正在缓冲无限流上的滑动窗口。例如,这是 DVR 观看直播电视时看到的行为。
每次都返回一个新对象对于属性 getter 来说是一个不好的模式,这里之所以保留是因为更改它成本较高。新的 API 不应复制此模式。
用户代理应采用非常宽松和乐观的态度来对待可跳转的内容。用户代理还应尽可能缓冲最近的内容以使跳转速度更快。
例如,考虑一个在不支持 HTTP Range 请求的 HTTP 服务器上提供的较大的视频文件。浏览器可以通过仅缓冲当前帧和为后续帧获取的数据来实现此功能,永不允许跳转,除非通过重新启动播放跳转到最开始。但是,这将是一个糟糕的实现。高质量的实现将缓冲最后几分钟的内容(或者更多,如果可用存储空间足够),允许用户回跳并重新观看令人惊讶的内容而没有任何延迟,并且此外允许通过从头开始重新加载文件进行任意跳转(如果需要),这将比较慢但仍然比必须从字面上重新启动视频并一直观看它才能到达较早的未缓冲位置更方便。
媒体资源可能是内部脚本化的或交互式的。因此,媒体元素可以以非线性方式播放。如果发生这种情况,用户代理必须假装在当前播放位置以不连续的方式更改时(以便触发相关事件)使用了跳转的算法。
媒体资源可以有多个嵌入式音频和视频轨道。例如,除了主视频和音频轨道外,媒体资源可以包含外语配音对话、导演评论、音频描述、备用角度或手语叠加。
media.audioTracks
所有当前引擎都支持。
返回一个AudioTrackList
对象,表示媒体资源中可用的音频轨道。
media.videoTracks
所有当前引擎都支持。
返回一个VideoTrackList
对象,表示媒体资源中可用的视频轨道。
audioTracks
属性的媒体元素必须返回一个实时AudioTrackList
对象,表示媒体元素的媒体资源中可用的音频轨道。
videoTracks
属性的媒体元素必须返回一个实时VideoTrackList
对象,表示媒体元素的媒体资源中可用的视频轨道。
每个媒体元素只有一个AudioTrackList
对象和一个VideoTrackList
对象,即使将另一个媒体资源加载到该元素中:这些对象会被重复使用。(但是AudioTrack
和VideoTrack
对象不会。)
AudioTrackList
和VideoTrackList
对象所有当前引擎都支持。
所有当前引擎都支持。
所有当前引擎都支持。
上一节中定义的属性使用AudioTrackList
和VideoTrackList
接口。
所有当前引擎都支持。
所有当前引擎都支持。
[Exposed =Window ]
interface AudioTrackList : EventTarget {
readonly attribute unsigned long length ;
getter AudioTrack (unsigned long index );
AudioTrack ? getTrackById (DOMString id );
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
[Exposed =Window ]
interface AudioTrack {
readonly attribute DOMString id ;
readonly attribute DOMString kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
attribute boolean enabled ;
};
[Exposed =Window ]
interface VideoTrackList : EventTarget {
readonly attribute unsigned long length ;
getter VideoTrack (unsigned long index );
VideoTrack ? getTrackById (DOMString id );
readonly attribute long selectedIndex ;
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
[Exposed =Window ]
interface VideoTrack {
readonly attribute DOMString id ;
readonly attribute DOMString kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
attribute boolean selected ;
};
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。
可以设置,以更改轨道是否被选中。可以选择零个或一个视频轨道;在先前轨道被选中的情况下选择新轨道将取消选择先前轨道。
AudioTrackList
对象表示一个包含零个或多个音频轨道的动态列表,其中可以同时启用零个或多个音频轨道。每个音频轨道都由一个AudioTrack
对象表示。
VideoTrackList
对象表示一个包含零个或多个视频轨道的动态列表,其中一次只能选择零个或一个视频轨道。每个视频轨道都由一个VideoTrack
对象表示。
AudioTrackList
和VideoTrackList
对象中的轨道必须保持一致的顺序。如果媒体资源采用定义顺序的格式,则必须使用该顺序;否则,顺序必须是轨道在媒体资源中声明的相对顺序。使用的顺序称为列表的自然顺序。
因此,这些对象中的每个轨道都有一个索引;第一个索引为0,每个后续轨道都比前一个轨道多1。如果媒体资源动态添加或删除音频或视频轨道,则轨道的索引将动态更改。如果媒体资源完全更改,则所有先前的轨道将被删除并替换为新的轨道。
AudioTrackList
length
和VideoTrackList
length
属性获取器必须返回获取时其对象表示的轨道数。
AudioTrackList
和VideoTrackList
对象的支持的属性索引在任何时刻都是从零到各自对象表示的轨道数减一的数字(如果表示任何轨道)。如果AudioTrackList
或VideoTrackList
对象不表示任何轨道,则它没有支持的属性索引。
要确定AudioTrackList
或VideoTrackList
对象list中给定索引index的索引属性的值,用户代理必须返回AudioTrack
或VideoTrack
对象,该对象表示list中的第index个轨道。
AudioTrackList
getTrackById(id)
和VideoTrackList
getTrackById(id)
方法必须返回AudioTrackList
或VideoTrackList
对象(分别)中第一个标识符等于id参数值的AudioTrack
或VideoTrack
对象(在列表的自然顺序中,如上所述)。当没有轨道与给定参数匹配时,这些方法必须返回null。
AudioTrack
和VideoTrack
对象表示媒体资源的特定轨道。每个轨道都可以具有标识符、类别、标签和语言。轨道的这些方面在轨道的整个生命周期中都是永久的;即使轨道从媒体资源的AudioTrackList
或VideoTrackList
对象中删除,这些方面也不会改变。
此外,每个AudioTrack
对象都可以启用或禁用;这是音频轨道的启用状态。当创建AudioTrack
时,其启用状态必须设置为false(禁用)。资源获取算法可以覆盖此设置。
类似地,每个VideoTrackList
对象可以选中一个VideoTrack
对象,这是视频轨道的选择状态。当创建VideoTrack
时,其选择状态必须设置为false(未选中)。资源获取算法可以覆盖此设置。
AudioTrack
id
和VideoTrack
id
属性必须返回轨道的标识符(如果存在),否则返回空字符串。如果媒体资源采用支持媒体片段语法的格式,则对于特定轨道返回的标识符必须与在轨道维度中使用轨道名称作为此类片段的名称启用轨道的标识符相同。[INBAND]
例如,在Ogg文件中,这将是轨道的Name头字段。[OGGSKELETONHEADERS]
AudioTrack
kind
和VideoTrack
kind
属性必须返回轨道的类别(如果存在),否则返回空字符串。
轨道的类别是在下表的第一列中给出的字符串,该字符串根据表中第二列和第三列中的定义最适合该轨道,由媒体资源中轨道中包含的元数据确定。某行第三列中的单元格说明第一列单元格中给出的类别适用于什么;如果类别适用于音频轨道,则它只适用于音频轨道,如果类别适用于视频轨道,则它只适用于视频轨道。只有在类别适用于音频时,才必须为AudioTrack
对象返回类别,并且只有在类别适用于视频时,才必须为VideoTrack
对象返回类别。
对于Ogg文件,轨道的Role头字段提供相关元数据。对于DASH媒体资源,Role
元素传达信息。对于WebM,目前只有FlagDefault
元素映射到值。 将媒体容器中的带内媒体资源轨道源入HTML提供了更多详细信息。[OGGSKELETONHEADERS] [DASH] [WEBMCG] [INBAND]
类别 | 定义 | 适用于... | 示例 |
---|---|---|---|
"alternative " | 主音轨的可选替代方案,例如歌曲的不同版本(音频)或不同的视角(视频)。 | 音频和视频。 | Ogg: "audio/alternate" 或 "video/alternate";DASH: "alternate",不包含 "main" 和 "commentary" 角色,并且对于音频,不包含 "dub" 角色(其他角色忽略)。 |
"captions " | 带有嵌入式字幕的主视频音轨版本。(用于旧内容;新内容将使用文本音轨。) | 仅视频。 | DASH: "caption" 和 "main" 角色同时存在(其他角色忽略)。 |
"descriptions " | 视频音轨的音频描述。 | 仅音频。 | Ogg: "audio/audiodesc"。 |
"main " | 主要的音频或视频音轨。 | 音频和视频。 | Ogg: "audio/main" 或 "video/main";WebM:设置 "FlagDefault" 元素;DASH: "main" 角色,不包含 "caption"、"subtitle" 和 "dub" 角色(其他角色忽略)。 |
"main-desc " | 主要的音频音轨,混合了音频描述。 | 仅音频。 | MPEG-2 TS 中的 AC3 音频:bsmod=2 且 full_svc=1。 |
"sign " | 音频音轨的手语翻译。 | 仅视频。 | Ogg: "video/sign"。 |
"subtitles " | 带有嵌入式字幕的主视频音轨版本。(用于旧内容;新内容将使用文本音轨。) | 仅视频。 | DASH: "subtitle" 和 "main" 角色同时存在(其他角色忽略)。 |
"translation " | 主音频音轨的翻译版本。 | 仅音频。 | Ogg: "audio/dub"。DASH: "dub" 和 "main" 角色同时存在(其他角色忽略)。 |
"commentary " | 主要音频或视频音轨的解说,例如导演解说。 | 音频和视频。 | DASH: "commentary" 角色,不包含 "main" 角色(其他角色忽略)。 |
" "(空字符串) | 没有明确的类型,或者音轨元数据提供的类型未被用户代理识别。 | 音频和视频。 |
和 AudioTrack
label
属性必须返回音轨的标签(如果存在),否则返回空字符串。 [INBAND]VideoTrack
label
和 AudioTrack
language
属性必须返回音轨语言的 BCP 47 语言标签(如果存在),否则返回空字符串。如果用户代理无法将该语言表示为 BCP 47 语言标签(例如,因为媒体资源格式中的语言信息是自由格式字符串,没有定义的解释),则该方法必须返回空字符串,就像音轨没有语言一样。 [INBAND]VideoTrack
language
属性在获取时,如果音轨当前已启用,则必须返回 true,否则返回 false。在设置时,如果新值为 true,则必须启用音轨,否则禁用它。(如果音轨不再位于 AudioTrack
enabled
对象中,则启用或禁用音轨的效果仅限于更改 AudioTrackList
对象上属性的值。)AudioTrack
每当
中已禁用的音频音轨被启用时,以及每当已启用的音频音轨被禁用时,用户代理都必须根据 AudioTrackList
媒体元素
排队一个媒体元素任务,以便在
对象上触发名为 AudioTrackList
的事件。change
在 媒体时间轴
上的特定位置没有数据或在该位置不存在的音频音轨,必须被解释为在时间轴上的该点静音。
属性必须返回当前选定音轨的索引(如果有)。如果 VideoTrackList
selectedIndex
对象当前不表示任何音轨,或者没有音轨被选中,则它必须返回 −1。VideoTrackList
属性在获取时,如果音轨当前已选中,则必须返回 true,否则返回 false。在设置时,如果新值为 true,则必须选中音轨,否则取消选中它。如果音轨位于 VideoTrack
selected
中,则该列表中的所有其他 VideoTrackList
对象都必须取消选中。(如果音轨不再位于 VideoTrack
对象中,则选中或取消选中音轨的效果仅限于更改 VideoTrackList
对象上属性的值。)VideoTrack
每当
中先前未选中的音轨被选中时,以及每当 VideoTrackList
中选定的音轨被取消选中而没有新的音轨被选中代替时,用户代理都必须根据 VideoTrackList
媒体元素
排队一个媒体元素任务,以便在
对象上触发名为 VideoTrackList
的事件。此 任务 必须在触发 change
事件(如果有)的任务之前排队。resize
在 媒体时间轴
上的特定位置没有数据的视频音轨,必须被解释为在时间轴上的该点为 透明黑色,其尺寸与该位置之前最后一帧的尺寸相同,或者如果该位置在该音轨的所有数据之前,则其尺寸与该音轨第一帧的尺寸相同。在当前位置完全不存在的音轨必须被视为存在但没有数据。
例如,如果视频的音轨仅在播放一小时后才引入,并且用户选择了该音轨然后返回开头,则用户代理将表现得好像该音轨从 媒体资源的开头开始,但直到一小时后才显示。
以下是所有实现
和 AudioTrackList
接口的对象都必须支持的事件处理程序(及其对应的事件处理程序事件类型),作为事件处理程序 IDL 属性VideoTrackList
事件处理程序 | 事件处理程序事件类型 |
---|---|
onchange 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox31+Safari7+Chrome33+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | change
|
onaddtrack 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | addtrack
|
onremovetrack AudioTrackList/removetrack_event 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? TextTrackList/removetrack_event 所有当前引擎都支持。 Firefox31+Safari7+Chrome33+ Opera20+Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android20+ VideoTrackList/removetrack_event 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | removetrack
|
和 audioTracks
属性允许脚本选择应播放哪个音轨,但也可以通过在 媒体资源 的 URL 的 片段 中指定特定音轨来声明式地选择特定的音轨。 片段 的格式取决于 媒体资源 的 MIME 类型。 [RFC2046] [URL]videoTracks
在此示例中,使用支持 媒体片段语法 的格式的视频以这样一种方式嵌入,即启用标记为“替代”的备用视角,而不是默认视频音轨。
< video src = "myvideo#track=Alternative" ></ video >
一个 媒体元素 可以有一组关联的 文本轨道,称为该 媒体元素 的 文本轨道列表。这些 文本轨道 按如下顺序排序。
使用 addTextTrack()
方法添加的任何 文本轨道,按照添加顺序排序,最早添加的排在最前面。
任何 媒体资源特定的文本轨道(与 媒体资源 中的数据对应的 文本轨道),按照 媒体资源 的格式规范定义的顺序。
一个 文本轨道 包含以下内容:
这决定了用户代理如何处理该轨道。类型用字符串表示。可能的字符串包括:
字幕
字幕
描述
章节
元数据
这是一个面向用户的、可读的字符串,用于识别该轨道。
对于与 track
元素对应的 文本轨道,轨道的标签 可以动态更改。
当 文本轨道标签 为空字符串时,用户代理应根据文本轨道的其他属性(例如文本轨道的类型和语言)自动生成一个合适的标签,用于其用户界面。此自动生成的标签不会在 API 中公开。
这是一个从 媒体资源 中提取的字符串,专门用于带内元数据轨道,使此类轨道能够分发到文档中的不同脚本。
例如,在网络上流式传输的传统电视台广播并增强了特定于网络的交互功能,可以包含用于广告定位、游戏节目期间的琐事游戏数据、体育比赛期间的玩家状态、美食节目期间的食谱信息等的元数据文本轨道。随着每个节目开始和结束,新的轨道可能会被添加到流中或从流中移除,并且在添加每个轨道时,用户代理可以使用此属性的值将其绑定到专用的脚本模块。
除了带内元数据文本轨道之外,带内元数据轨道分发类型 为空字符串。不同媒体格式如何填充此值在 公开媒体资源特定文本轨道的步骤 中进行了描述。
这是一个字符串(BCP 47 语言标签),表示文本轨道提示的语言。 [BCP47]
以下状态之一:
表示尚未获取文本轨道的提示。
表示文本轨道正在加载,并且到目前为止没有遇到致命错误。解析器可能仍会向轨道添加更多提示。
表示文本轨道已加载,且没有致命错误。
表示文本轨道已启用,但当用户代理尝试获取它时,以某种方式失败(例如,无法 解析 URL、网络错误、未知的文本轨道格式)。一些或所有提示可能丢失,并且将无法获取。
当轨道被获取时,文本轨道的就绪状态 会动态更改。
以下状态之一:
表示文本轨道未处于活动状态。除了在 DOM 中公开轨道外,用户代理会忽略该文本轨道。没有提示处于活动状态,不会触发任何事件,并且用户代理不会尝试获取轨道的提示。
表示文本轨道处于活动状态,但用户代理未主动显示提示。如果尚未尝试获取轨道的提示,则用户代理会立即尝试获取。用户代理维护了一个哪些提示处于活动状态的列表,并相应地触发事件。
表示文本轨道处于活动状态。如果尚未尝试获取轨道的提示,则用户代理会立即尝试获取。用户代理维护了一个哪些提示处于活动状态的列表,并相应地触发事件。此外,对于 类型 为 字幕
或 隐藏字幕
的文本轨道,提示将根据需要叠加在视频上;对于 类型 为 描述
的文本轨道,用户代理会以非视觉方式向用户提供提示;对于 类型 为 章节
的文本轨道,用户代理会向用户提供一种机制,用户可以通过选择提示导航到 媒体资源 中的任何点。
文本轨道提示 的列表,以及 更新文本轨道渲染的规则。例如,对于 WebVTT,更新 WebVTT 文本轨道显示的规则。 [WEBVTT]
每个 媒体元素 都包含一个 待处理文本轨道列表(最初必须为空),一个 被解析器阻塞 标志(最初必须为 false),以及一个 已执行自动轨道选择 标志(最初也必须为 false)。
当用户代理需要 填充媒体元素的待处理文本轨道列表 时,用户代理必须将元素的 待处理文本轨道列表 中添加每个 文本轨道,这些文本轨道在元素的 文本轨道列表 中,其 文本轨道模式 不是 禁用,且 文本轨道就绪状态 为 加载中。
每当 track
元素的父节点发生更改时,用户代理必须从其所在的任何 待处理文本轨道列表 中移除对应的 文本轨道。
每当 文本轨道 的 文本轨道就绪状态 更改为 已加载 或 加载失败 时,用户代理必须将其从其所在的任何 待处理文本轨道列表 中移除。
当 媒体元素 由 HTML 解析器 或 XML 解析器 创建时,用户代理必须将元素的 被解析器阻塞 标志设置为 true。当 媒体元素 从 打开元素堆栈 中弹出 HTML 解析器 或 XML 解析器 时,用户代理必须 尊重用户对自动文本轨道选择的偏好、填充待处理文本轨道列表,并将元素的 被解析器阻塞 标志设置为 false。
当 媒体元素 的 待处理文本轨道列表 为空且元素的 被解析器阻塞 标志为 false 时,文本轨道 处于 就绪 状态。
每个 媒体元素 都包含一个 待处理文本轨道更改通知标志,最初必须未设置。
每当 媒体元素 的 文本轨道列表 中的 文本轨道 的 文本轨道模式 值发生更改时,用户代理必须为 媒体元素 运行以下步骤。
如果 媒体元素 的 待处理文本轨道更改通知标志 已设置,则返回。
设置 媒体元素 的 待处理文本轨道更改通知标志。
为给定的媒体元素排队一个媒体元素任务,以运行以下步骤。
取消设置 媒体元素 的 待处理文本轨道更改通知标志。
触发名为 change
的事件,在 媒体元素 的 textTracks
属性的 TextTrackList
对象上。
一个文本轨道提示是文本轨道中时间敏感数据的单位,例如,对于字幕和隐藏式字幕,它对应于在特定时间出现并在另一个时间消失的文本。
每个文本轨道提示由以下部分组成:
一个任意字符串。
以秒和秒的分数表示的时间,描述了提示所应用的媒体数据范围的开始。
一个布尔值,指示当到达提示所应用的范围的末尾时,是否要暂停媒体资源的播放。
根据格式需要添加的字段,包括提示的实际数据。例如,WebVTT 有一个文本轨道提示书写方向等等。[WEBVTT]
一个无界文本轨道提示是一个文本轨道提示结束时间设置为正无穷大的文本轨道提示。一个活动的无界文本轨道提示不能通过在正常播放期间当前播放位置的通常单调递增而变得不活动(例如,对于没有宣布结束时间的直播事件中的章节的元数据提示)。
文本轨道提示开始时间和文本轨道提示结束时间可以为负。(但是,当前播放位置永远不能为负,因此完全在时间零之前的提示不能处于活动状态。)
每个文本轨道提示都有一个对应的TextTrackCue
对象(更准确地说,是一个继承自TextTrackCue
的对象——例如,WebVTT 提示使用VTTCue
接口)。可以通过此TextTrackCue
API动态更改文本轨道提示的内存表示。[WEBVTT]
一个文本轨道提示与更新文本轨道渲染的规则相关联,如特定类型的文本轨道提示的规范中所定义。当表示提示的对象使用addCue()
方法添加到TextTrack
对象时,这些规则会专门使用。
此外,每个文本轨道提示都有两部分动态信息:
此标志最初必须未设置。该标志用于确保在提示变为活动或非活动时适当地触发事件,并确保渲染正确的提示。
每当文本轨道提示从其文本轨道的文本轨道提示列表中移除时;每当文本轨道本身从其媒体元素的文本轨道列表中移除或其文本轨道模式更改为禁用时;以及每当媒体元素的readyState
更改回HAVE_NOTHING
时,用户代理必须同步取消设置此标志。当以这种方式为文本轨道(在相关事件之前显示)中的一个或多个提示取消设置标志时,用户代理必须在为所有受影响的提示取消设置标志后,应用这些文本轨道的更新文本轨道渲染的规则。例如,对于基于 WebVTT 的文本轨道,更新 WebVTT 文本轨道显示的规则。[WEBVTT]
这用作渲染模型的一部分,以使提示保持一致的位置。它最初必须为空。每当文本轨道提示活动标志取消设置时,用户代理必须清空文本轨道提示显示状态。
文本轨道提示在媒体元素的文本轨道中彼此之间按文本轨道提示顺序排序,其确定方式如下:首先按其文本轨道对提示进行分组,这些组的排序顺序与其文本轨道在媒体元素的文本轨道列表中出现的顺序相同;然后,在每个组内,提示必须按其开始时间排序,最早的排在最前面;然后,任何具有相同开始时间的提示必须按其结束时间排序,最新的排在最前面;最后,任何具有相同结束时间的提示必须按其上次添加到各自的文本轨道提示列表的顺序排序,最早的排在最前面(例如,对于来自 WebVTT 文件的提示,这最初将是提示在文件中列出的顺序)。[WEBVTT]
一个媒体资源特定文本轨道是一个文本轨道,它对应于在媒体资源中找到的数据。
处理和渲染此类数据的规则由相关规范定义,例如,如果媒体资源是视频,则由视频格式的规范定义。一些传统格式的详细信息可以在从媒体容器到 HTML 的带内媒体资源轨道的来源中找到。[INBAND]
当媒体资源包含用户代理识别并支持作为等效于文本轨道的数据时,用户代理运行具有相关数据的公开媒体资源特定文本轨道的步骤,如下所示。
将相关数据与新的文本轨道及其对应的新的TextTrack
对象关联。该文本轨道是媒体资源特定文本轨道。
根据相关规范中定义的相关数据的语义,设置新文本轨道的类型、标签和语言。如果该数据中没有标签,则必须将标签设置为空字符串。
将文本轨道提示列表与适用于所讨论格式的更新文本轨道渲染的规则关联。
如果新文本轨道的类型是章节
或元数据
,则如下设置文本轨道带内元数据轨道分派类型,基于媒体资源的类型:
CodecID
元素的值。[WEBMCG]mett
"、一个 U+0020 空格字符和 stsd 盒的第一个 `mett` 盒的第一个 `mime_format` 字段的值的拼接,如果该字段在该盒中不存在,则为空字符串。否则,如果 stsd 盒没有 `mett` 盒但有 `metx` 盒,则 文本轨道带内元数据轨道分发类型 必须设置为字符串 "metx
"、一个 U+0020 空格字符和 stsd 盒的第一个 `metx` 盒的第一个 `namespace` 字段的值的拼接,如果该字段在该盒中不存在,则为空字符串。 [MPEG4]将新的 文本轨道 的 模式 设置为与用户偏好和数据相关规范要求一致的模式。
例如,如果没有其他活动的字幕,并且这是一个强制字幕轨道(一个提供音频轨道主要语言字幕的字幕轨道,但仅限于实际上使用其他语言的音频),则这些字幕可能会在此处激活。
在 媒体元素 的 textTracks
属性的 TextTrackList
对象上 触发一个名为 addtrack
的事件,使用 TrackEvent
,并将 track
属性初始化为 文本轨道 的 TextTrack
对象。
当创建 track
元素时,必须将其与一个新的 文本轨道(其值设置为如下定义)及其对应的新的 TextTrack
对象关联。
文本轨道类型 根据下表中元素的 kind
属性的状态确定;对于第一列单元格中给出的状态,类型 是第二列中给出的字符串
状态 | 字符串 |
---|---|
字幕 | 字幕
|
字幕 | 字幕
|
描述 | 描述
|
章节元数据 | 章节
|
元数据 | 元数据
|
文本轨道语言 是元素的 轨道语言(如果存在),否则为空字符串。
当设置、更改或删除 kind
、label
和 srclang
属性时, 文本轨道 必须根据上述定义进行相应的更新。
对 轨道 URL 的更改在下面的算法中处理。
文本轨道就绪状态 最初为 未加载, 文本轨道模式 最初为 已禁用。
文本轨道提示列表 最初为空。当解析引用的文件时,它会动态修改。与该列表关联的是 更新文本轨道渲染规则,这些规则适用于相关格式;对于 WebVTT,这是 更新 WebVTT 文本轨道显示的规则。 [WEBVTT]
当 track
元素的父元素发生更改,并且新父元素是 媒体元素 时,用户代理必须将 track
元素对应的 文本轨道 添加到 媒体元素 的 文本轨道列表,然后 排队一个媒体元素任务,给定 媒体元素 以 触发一个名为 addtrack
的事件,在 媒体元素 的 textTracks
属性的 TextTrackList
对象上,使用 TrackEvent
,并将 track
属性初始化为 文本轨道 的 TextTrack
对象。
当 track
元素的父元素发生更改,并且旧父元素是 媒体元素 时,用户代理必须从 媒体元素 的 文本轨道列表 中删除 track
元素对应的 文本轨道,然后 排队一个媒体元素任务,给定 媒体元素 以 触发一个名为 removetrack
的事件,在 媒体元素 的 textTracks
属性的 TextTrackList
对象上,使用 TrackEvent
,并将 track
属性初始化为 文本轨道 的 TextTrack
对象。
当将对应于 track
元素的 文本轨道 添加到 媒体元素 的 文本轨道列表 时,用户代理必须 排队一个媒体元素任务,给定 媒体元素 以对 媒体元素 运行以下步骤
如果元素的 blocked-on-parser 标志为真,则返回。
如果元素的 did-perform-automatic-track-selection 标志为真,则返回。
对该元素 遵循用户对自动文本轨道选择的偏好。
当用户代理需要对 媒体元素 遵循用户对自动文本轨道选择的偏好 时,用户代理必须运行以下步骤
对 subtitles
和 captions
执行自动文本轨道选择。
执行自动文本轨道选择 用于 描述
。
如果在媒体元素的文本轨道列表中存在任何文本轨道,其文本轨道类型为章节
或元数据
,并且对应于具有已设置default
属性的track
元素,且其文本轨道模式设置为disabled,则将所有此类轨道的文本轨道模式设置为 。
将元素的did-perform-automatic-track-selection标志设置为true。
当以上步骤说明要对一个或多个文本轨道类型 执行自动文本轨道选择时,意味着要运行以下步骤
令candidates为一个列表,该列表包含媒体元素的文本轨道列表中的文本轨道,其文本轨道类型为传递给算法的类型之一(如果有),按照文本轨道列表中给出的顺序。
如果candidates为空,则返回。
如果用户已表示对启用来自candidates的轨道的兴趣,该兴趣基于其文本轨道类型、文本轨道语言和文本轨道标签,则将其文本轨道模式设置为showing。
例如,用户可以设置浏览器首选项,其效果为“我尽可能想要法语字幕”或“如果字幕轨道标题中包含‘评论’,则启用它”或“如果提供了音频描述轨道,则启用一个,理想情况下使用瑞士德语,否则使用标准瑞士德语或标准德语”。
否则,如果candidates中存在任何文本轨道,其对应于具有已设置default
属性的track
元素,且其文本轨道模式设置为disabled,则将第一个此类轨道的文本轨道模式设置为showing。
当对应于track
元素的文本轨道遇到以下任何情况时,用户代理必须为该文本轨道及其track
元素启动track
处理模型
当用户代理需要为文本轨道及其track
元素启动track
处理模型时,它必须运行以下算法。此算法与事件循环机制紧密交互;特别是,它有一个同步部分(作为事件循环算法的一部分触发)。该部分中的步骤用⌛标记。
运行这些步骤的其余部分并行,允许导致这些步骤运行的任何操作继续。
⌛ 如果track
元素的父元素为媒体元素,则令corsAttributeState为父媒体元素的crossorigin
内容属性的状态。否则,令corsAttributeState为无CORS。
如果URL不是空字符串,则
令request为给定URL、“track
”和corsAttributeState,以及已设置相同来源回退标志的结果,创建潜在的CORS请求。
将request的发起者类型设置为“track
”。
获取request。
获取算法在网络任务源上排队的任务必须确定资源的类型。如果资源的类型不是受支持的文本轨道格式,则加载将失败,如下所述。否则,必须将资源的数据传递给相应的解析器(例如,WebVTT解析器),并在接收时进行处理,并使用文本轨道提示列表作为该解析器的输出。[WEBVTT]
在这些网络任务源任务期间,相应的解析器将增量更新文本轨道提示列表,因为每个此类任务都将使用从网络接收到的任何数据运行)。
本规范目前没有说明是否以及如何检查文本轨道的MIME类型,或者是否以及如何使用实际文件数据执行文件类型嗅探。实现者在这方面存在不同的意图,因此尚不清楚正确的解决方案是什么。在没有任何要求的情况下,HTTP规范中关于遵循Content-Type头的严格要求仍然适用(“Content-Type指定基础数据的媒体类型。”…“当且仅当媒体类型未由Content-Type字段给出时,接收方可以尝试通过检查其内容和/或用于识别资源的URI的名称扩展名来猜测媒体类型。”)。
如果由于任何原因导致获取失败(网络错误、服务器返回错误代码、CORS失败等),或者如果URL为空字符串,则在DOM操作任务源上排队一个元素任务,给定媒体元素,首先将文本轨道就绪状态更改为加载失败,然后在track
元素上触发一个名为error
的事件。
如果获取没有失败,但资源的类型不是受支持的文本轨道格式,或者文件未成功处理(例如,相关格式为 XML 格式,并且文件包含 XML 要求检测并向应用程序报告的格式错误),则在发现上述问题的任务中,排队到网络任务源的任务必须将文本轨道就绪状态更改为加载失败,并在轨道
元素上触发名为error
的事件。
如果获取没有失败,并且文件已成功处理,则在完成数据解析后,网络任务源 排队的最后一个任务必须将文本轨道就绪状态更改为loaded,并在轨道
元素上触发名为load
的事件。
如果在获取进行期间,出现以下任一情况:
…那么用户代理必须中止获取,丢弃该算法生成的任何挂起的任务(特别是,在 URL 更改的那一刻之后,不再向文本轨道提示列表添加任何提示),然后在DOM 操作任务源上排队一个元素任务,该任务首先将轨道
元素的文本轨道就绪状态更改为加载失败,然后触发名为error
的事件。
跳转到标记为top的步骤。
每当轨道
元素的src
属性被设置、更改或删除时,用户代理必须立即清空该元素的文本轨道的文本轨道提示列表。(这还会导致上述算法停止添加从使用先前给定 URL 获取的资源中获取的提示,如果有的话。)
特定格式的文本轨道提示如何被解释以供 HTML 用户代理处理,由该格式定义。在没有此类规范的情况下,本节提供了一些约束条件,在这些约束条件内,实现可以尝试一致地公开此类格式。
为了支持 HTML 的文本轨道模型,每个定时数据单元都转换为一个文本轨道提示。如果格式的功能到文本轨道提示各个方面的映射(如本规范中所定义)未定义,则实现必须确保映射与上述定义的文本轨道提示各个方面的定义以及以下约束条件一致。
如果格式没有明显的类似于每个提示标识符的模拟,则应将其设置为空字符串。
应设置为 false。
所有当前引擎都支持。
[Exposed =Window ]
interface TextTrackList : EventTarget {
readonly attribute unsigned long length ;
getter TextTrack (unsigned long index );
TextTrack ? getTrackById (DOMString id );
attribute EventHandler onchange ;
attribute EventHandler onaddtrack ;
attribute EventHandler onremovetrack ;
};
media.textTracks.length
所有当前引擎都支持。
media.textTracks[ n ]
textTrack = media.textTracks.getTrackById(id)
所有当前引擎都支持。
返回具有给定标识符的TextTrack
对象,如果没有任何轨道具有该标识符,则返回 null。
TextTrackList
对象表示以给定顺序动态更新的文本轨道列表。
媒体元素的textTracks
属性必须返回一个TextTrackList
对象,该对象表示媒体元素的文本轨道列表中文本轨道的TextTrack
对象,顺序与文本轨道列表中的顺序相同。
所有当前引擎都支持。
TextTrackList
对象的length
属性必须返回TextTrackList
对象所表示的列表中文本轨道的数量。
TextTrackList
对象在任何时刻的受支持的属性索引是从零到TextTrackList
对象所表示的列表中文本轨道的数量减一,如果有的话。如果列表中没有文本轨道,则没有受支持的属性索引。
要确定TextTrackList
对象的索引属性的值,对于给定的索引index,用户代理必须返回TextTrackList
对象所表示的列表中的第index个文本轨道。
getTrackById(id)
方法必须返回TextTrackList
对象中第一个TextTrack
,其id
IDL 属性将返回一个等于id参数的值。当没有轨道与给定参数匹配时,该方法必须返回 null。
所有当前引擎都支持。
enum TextTrackMode { " disabled " , " hidden " , " showing " };
enum TextTrackKind { " subtitles " , " captions " , " descriptions " , " chapters " , " metadata " };
[Exposed =Window ]
interface TextTrack : EventTarget {
readonly attribute TextTrackKind kind ;
readonly attribute DOMString label ;
readonly attribute DOMString language ;
readonly attribute DOMString id ;
readonly attribute DOMString inBandMetadataTrackDispatchType ;
attribute TextTrackMode mode ;
readonly attribute TextTrackCueList ? cues ;
readonly attribute TextTrackCueList ? activeCues ;
undefined addCue (TextTrackCue cue );
undefined removeCue (TextTrackCue cue );
attribute EventHandler oncuechange ;
};
textTrack = media.addTextTrack(kind [, label [, language ] ])
textTrack.kind
所有当前引擎都支持。
返回文本轨道种类字符串。
textTrack.label
所有当前引擎都支持。
返回文本轨道标签(如果有),否则返回空字符串(表示如果将对象公开给用户,则可能需要从对象的其他属性生成自定义标签)。
textTrack.language
所有当前引擎都支持。
返回文本轨道语言字符串。
textTrack.id
所有当前引擎都支持。
返回给定轨道的 ID。
对于嵌入式轨道,这是一个可与片段一起使用的 ID,前提是格式支持媒体片段语法,并且可与getTrackById()
方法一起使用。
textTrack.inBandMetadataTrackDispatchType
TextTrack/inBandMetadataTrackDispatchType
返回文本轨道带内元数据轨道分发类型字符串。
textTrack.mode [ = value ]
所有当前引擎都支持。
返回文本轨道模式,由以下列表中的字符串表示
可以设置,以更改模式。
textTrack.cues
所有当前引擎都支持。
返回文本轨道提示列表,作为TextTrackCueList
对象。
textTrack.activeCues
所有当前引擎都支持。
返回来自文本轨道提示列表中当前处于活动状态(即,在当前播放位置之前开始并在其之后结束)的文本轨道提示,作为TextTrackCueList
对象。
textTrack.addCue(cue)
所有当前引擎都支持。
将给定的提示添加到textTrack的文本轨道提示列表中。
textTrack.removeCue(cue)
所有当前引擎都支持。
从textTrack的文本轨道提示列表中删除给定的提示。
媒体元素的addTextTrack(kind, label, language)
方法在调用时,必须运行以下步骤
创建一个新的TextTrack
对象。
创建一个与新对象对应的新的文本轨道,并将其文本轨道类型设置为kind,其文本轨道标签设置为label,其文本轨道语言设置为language,其文本轨道就绪状态设置为文本轨道已加载状态,其文本轨道模式设置为 模式,并且其文本轨道提示列表设置为一个空列表。
最初,文本轨道提示列表与任何更新文本轨道渲染的规则都不相关。当向其中添加文本轨道提示时,文本轨道提示列表将永久设置相应的规则。
给定媒体元素,将媒体元素任务排队以在媒体元素的textTracks
属性的TextTrackList
对象上触发一个名为addtrack
的事件,使用TrackEvent
,其中track
属性初始化为新的文本轨道的TextTrack
对象。
返回新的TextTrack
对象。
kind
属性必须返回TextTrack
对象所表示的文本轨道的文本轨道类型。
label
属性必须返回TextTrack
对象所表示的文本轨道的文本轨道标签。
language
属性必须返回TextTrack
对象所表示的文本轨道的文本轨道语言。
id
属性返回轨道的标识符(如果存在),否则返回空字符串。对于与track
元素对应的轨道,轨道的标识符是元素的id
属性的值(如果存在)。对于嵌入式轨道,轨道的标识符由媒体资源指定。如果媒体资源采用支持媒体片段语法的格式,则为特定轨道返回的标识符必须与启用该轨道(如果用作此类片段的轨道维度的轨道名称)的相同标识符。
inBandMetadataTrackDispatchType
属性必须返回TextTrack
对象所表示的文本轨道的文本轨道带内元数据轨道分发类型。
mode
属性在获取时,必须返回与TextTrack
对象所表示的文本轨道的文本轨道模式相对应的字符串,如下面的列表定义
disabled
"hidden
"showing
"在设置时,如果新值不等于属性当前将返回的值,则必须按如下方式处理新值
disabled
"showing
"如果TextTrack
对象所表示的文本轨道的文本轨道模式不是文本轨道禁用模式,则cues
属性必须返回一个实时TextTrackCueList
对象,该对象表示TextTrack
对象所表示的文本轨道的文本轨道提示列表的子集,其结束时间发生在脚本开始时的最早可能位置或之后,按照文本轨道提示顺序。否则,它必须返回 null。对于每个TextTrack
对象,当返回对象时,每次都必须返回相同的TextTrackCueList
对象。
脚本开始时的最早可能位置是事件循环上次到达步骤 1 时的最早可能位置。
如果文本轨道模式的文本轨道(TextTrack
对象表示的)不是文本轨道禁用模式,则activeCues
属性必须返回一个实时的TextTrackCueList
对象,该对象表示文本轨道(TextTrack
对象表示的)的文本轨道提示列表的子集,其活动标志在脚本开始时已设置,并按照文本轨道提示顺序排列。否则,它必须返回null。对于每个TextTrack
对象,当返回对象时,每次都必须返回相同的TextTrackCueList
对象。
当脚本开始时,文本轨道提示的活动标志已设置,如果其文本轨道提示活动标志在上一次事件循环到达步骤1时已设置。
TextTrack
对象的addCue(cue)
方法在调用时,必须执行以下步骤
如果文本轨道提示列表还没有任何关联的更新文本轨道渲染的规则,则将文本轨道提示列表与适用于cue的更新文本轨道渲染的规则关联。
如果文本轨道提示列表的关联更新文本轨道渲染的规则与适用于cue的更新文本轨道渲染的规则不相同,则抛出"InvalidStateError
"DOMException
。
TextTrack
对象的removeCue(cue)
方法在调用时,必须执行以下步骤
如果给定的cue不在TextTrack
对象的文本轨道的文本轨道提示列表中,则抛出"NotFoundError
"DOMException
。
在这个例子中,一个audio
元素用于播放来自包含许多音效的音频文件的特定音效。提示用于暂停音频,以便即使浏览器忙于运行某些脚本,音频也能在剪辑结束时准确结束。如果页面依赖脚本暂停音频,则如果浏览器无法在指定的确切时间运行脚本,则可能会听到下一段剪辑的开头。
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();
}
所有当前引擎都支持。
[Exposed =Window ]
interface TextTrackCueList {
readonly attribute unsigned long length ;
getter TextTrackCue (unsigned long index );
TextTrackCue ? getCueById (DOMString id );
};
cuelist.length
返回列表中的提示数量。
cuelist[index]
cuelist.getCueById(id)
返回第一个文本轨道提示(按文本轨道提示顺序),其文本轨道提示标识符为id。
如果没有任何提示具有给定的标识符,或者参数为空字符串,则返回null。
TextTrackCueList
对象表示一个动态更新的文本轨道提示列表,并按照给定的顺序排列。
所有当前引擎都支持。
length
属性必须返回TextTrackCueList
对象表示的列表中的提示数量。
TextTrackCueList
对象的支持的属性索引在任何时刻都是从零到TextTrackCueList
对象表示的列表中的提示数量减一,如果有的话。如果没有提示在列表中,则没有支持的属性索引。
要确定给定索引index的索引属性的值,用户代理必须返回TextTrackCueList
对象表示的列表中的第index个文本轨道提示。
所有当前引擎都支持。
当getCueById(id)
方法使用除空字符串以外的参数调用时,必须返回TextTrackCueList
对象表示的列表中的第一个文本轨道提示,其文本轨道提示标识符为id(如果有),否则返回null。如果参数为空字符串,则该方法必须返回null。
所有当前引擎都支持。
[Exposed =Window ]
interface TextTrackCue : EventTarget {
readonly attribute TextTrack ? track ;
attribute DOMString id ;
attribute double startTime ;
attribute unrestricted double endTime ;
attribute boolean pauseOnExit ;
attribute EventHandler onenter ;
attribute EventHandler onexit ;
};
cue.track
cue.id [ = value ]
返回文本轨道提示标识符。
可以设置。
cue.startTime [ = value ]
返回文本轨道提示开始时间,单位为秒。
可以设置。
cue.endTime [ = value ]
返回文本轨道提示结束时间,单位为秒。
对于无界文本轨道提示,返回正无穷大。
可以设置。
cue.pauseOnExit [ = value ]
如果文本轨道提示退出暂停标志已设置,则返回true,否则返回false。
可以设置。
所有当前引擎都支持。
track
属性在获取时,必须返回文本轨道的TextTrack
对象,文本轨道提示(TextTrackCue
对象表示的)在其提示列表中找到自身,如果存在;否则返回null。
所有当前引擎都支持。
id
属性在获取时,必须返回文本轨道提示(TextTrackCue
对象表示的)的文本轨道提示标识符。在设置时,文本轨道提示标识符必须设置为新值。
所有当前引擎都支持。
startTime
属性在获取时,必须返回文本轨道提示(TextTrackCue
对象表示的)的文本轨道提示开始时间,单位为秒。在设置时,文本轨道提示开始时间必须设置为新值,并解释为秒;然后,如果TextTrackCue
对象的文本轨道提示在文本轨道的提示列表中,并且该文本轨道在媒体元素的文本轨道列表中,并且媒体元素的显示海报标志未设置,则为该媒体元素运行时间推移步骤。
所有当前引擎都支持。
获取endTime
属性时,必须返回文本轨道提示结束时间,以秒或正无穷大表示。该文本轨道提示由TextTrackCue
对象表示。设置时,如果新值为负无穷大或非数字 (NaN) 值,则抛出TypeError异常。否则,必须将文本轨道提示结束时间设置为新值。然后,如果TextTrackCue
对象的文本轨道提示位于文本轨道的提示列表中,并且该文本轨道位于媒体元素的文本轨道列表中,并且媒体元素的显示海报标志未设置,则为该媒体元素运行时间推移步骤。
所有当前引擎都支持。
获取pauseOnExit
属性时,如果文本轨道提示的文本轨道提示退出暂停标志已设置,则必须返回true;否则返回false。设置时,如果新值为true,则必须设置文本轨道提示退出暂停标志;否则必须取消设置。
以下是所有实现TextTrackList
接口的对象必须支持的事件处理程序(及其对应的事件处理程序事件类型),作为事件处理程序 IDL 属性。
事件处理程序 | 事件处理程序事件类型 |
---|---|
onchange | change
|
onaddtrack | addtrack
|
onremovetrack | removetrack
|
以下是所有实现TextTrack
接口的对象必须支持的事件处理程序(及其对应的事件处理程序事件类型),作为事件处理程序 IDL 属性。
事件处理程序 | 事件处理程序事件类型 |
---|---|
oncuechange 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | cuechange
|
以下是所有实现TextTrackCue
接口的对象必须支持的事件处理程序(及其对应的事件处理程序事件类型),作为事件处理程序 IDL 属性。
事件处理程序 | 事件处理程序事件类型 |
---|---|
onenter 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | enter
|
onexit 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | exit
|
本节为非规范性内容。
文本轨道可用于存储与媒体数据相关的交互式或增强型视图数据。
例如,显示体育广播的页面可以包含有关当前比分的信息。假设正在直播机器人比赛。图像可以叠加分数,如下所示
为了使分数显示在用户跳转到视频任意点时都能正确呈现,元数据文本轨道提示需要尽可能长,以适应分数。例如,在上图中,可能有一个提示持续整个比赛时间,显示比赛编号,一个提示持续到蓝方联盟得分变化时结束,一个提示持续到红方联盟得分变化时结束。如果视频只是直播事件的流,则右下角的时间可能会自动从当前视频时间派生,而不是基于提示。但是,如果视频只是精彩片段,那么这可能也会在提示中给出。
以下显示了这部分内容在 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
事件受速率限制。)
需要使用URL来识别AudioTrack
kind
或VideoTrack
kind
IDL 属性的返回值,或识别文本轨道类型的其他规范或格式,必须使用about:html-kind
URL。
controls
属性是一个布尔属性。如果存在,则表示作者未提供脚本控制,并希望用户代理提供其自己的控件集。
如果属性存在,或者脚本被禁用用于媒体元素,则用户代理应向用户公开用户界面。此用户界面应包括开始播放、暂停播放、跳转到内容中的任意位置(如果内容支持任意跳转)、更改音量、更改隐藏字幕或嵌入式手语轨道的显示、选择不同的音频轨道或打开音频描述以及以更适合用户的方式显示媒体内容(例如全屏视频或独立的可调整大小的窗口)等功能。还可以提供其他控件。
但是,即使属性不存在,用户代理也可能会提供控件来影响媒体资源的播放(例如播放、暂停、跳转、轨道选择和音量控件),但此类功能不应干扰页面的正常渲染。例如,此类功能可以在媒体元素的上下文菜单、平台媒体键或遥控器中公开。用户代理可以通过向用户公开用户界面(就像controls
属性存在一样)来简单地实现此功能。
如果用户代理通过在媒体元素上显示控件来向用户公开用户界面,则用户代理应在用户代理与该界面交互时禁止任何用户交互事件。(例如,如果用户单击视频的播放控件,则mousedown
事件等不会同时在页面上的元素上触发。)
在可能的情况下(具体而言,用于开始、停止、暂停和恢复播放、跳转、更改播放速率、快进或倒带、列出、启用和禁用文本轨道以及静音或更改音频音量),用户代理公开的用户界面功能必须使用上面描述的 DOM API 实现,以便例如所有相同的事件都会触发。
快进或倒带等功能必须仅通过更改playbackRate
属性(而不是defaultPlaybackRate
属性)来实现。
跳转必须通过跳转到媒体元素的媒体时间线中请求的位置来实现。对于跳转到任意位置会很慢的媒体资源,建议用户代理在响应用户操作近似位置界面(如跳转条)时跳转时使用近似速度标志。
所有当前引擎都支持。
controls
IDL 属性必须反映同名内容属性。
media.volume [ = value ]
所有当前引擎都支持。
返回当前播放音量,以 0.0 到 1.0 之间的数字表示,其中 0.0 最安静,1.0 最响。
可以设置以更改音量。
如果新值不在 0.0 .. 1.0 范围内,则抛出"IndexSizeError
" DOMException
。
media.muted [ = value ]
所有当前引擎都支持。
如果音频被静音,则返回 true,覆盖volume
属性;如果volume
属性正在生效,则返回 false。
可以设置以更改音频是否静音。
媒体元素具有播放音量,它是一个介于 0.0(静音)到 1.0(最大音量)之间的分数。最初,音量应为 1.0,但用户代理可能会在会话之间(基于每个站点或其他方式)记住上次设置的值,因此音量可能从其他值开始。
volume
IDL 属性必须返回任何音频部分的播放音量。在设置时,如果新值在 0.0 到 1.0(包括 0.0 和 1.0)的范围内,则媒体元素的播放音量必须设置为新值。如果新值超出 0.0 到 1.0(包括 0.0 和 1.0)的范围,则在设置时,必须抛出一个"IndexSizeError
" DOMException
。
一个媒体元素也可以被静音。如果任何东西正在使元素静音,则该元素处于静音状态。(例如,当播放方向向后时,元素处于静音状态。)
muted
IDL 属性必须返回最后设置的值。当创建媒体元素时,如果元素具有指定的muted
内容属性,则 muted
IDL 属性应设置为 true;否则,用户代理可以将值设置为用户的首选值(例如,跨会话、基于每个站点或其他方式记住最后设置的值)。当 muted
IDL 属性设置为 true 时,媒体元素必须处于静音状态。
无论何时 volume
和 muted
IDL 属性将返回的值发生更改,用户代理都必须为媒体元素排队一个任务,以便在媒体元素上触发一个名为 volumechange
的事件。然后,如果媒体元素 不允许播放,则用户代理必须为媒体元素运行内部暂停步骤。
用户代理具有关联的音量锁定(一个布尔值)。其值是实现定义的,并确定播放音量是否生效。
元素的有效媒体音量 如下确定
如果用户已指示用户代理要覆盖元素的音量,则返回用户所需的音量。
如果用户代理的音量锁定为 true,则返回系统音量。
如果元素的音频输出已静音,则返回零。
返回 volume
,相对于 0.0 到 1.0 的范围进行解释,其中 0.0 为静音,1.0 为最大音量设置,介于两者之间的值音量逐渐增大。该范围不一定是线性的。最大音量设置可能低于系统的最大可能设置;例如,用户可以设置最大音量。
muted
内容属性在媒体元素上是一个布尔属性,它控制媒体资源音频输出的默认状态,可能会覆盖用户偏好。
所有当前引擎都支持。
defaultMuted
IDL 属性必须反映 muted
内容属性。
此属性没有动态效果(它只控制元素的默认状态)。
此视频(广告)自动播放,但为了避免打扰用户,它在没有声音的情况下播放,并允许用户打开声音。如果未静音,用户代理可以在没有用户交互的情况下暂停视频。
< video src = "adverts.cgi?kind=video" controls autoplay loop muted ></ video >
所有当前引擎都支持。
实现 TimeRanges
接口的对象表示时间范围(时段)列表。
[Exposed =Window ]
interface TimeRanges {
readonly attribute unsigned long length ;
double start (unsigned long index );
double end (unsigned long index );
};
media
.length
所有当前引擎都支持。
返回对象中的范围数。
time
= media
.start(index
)
所有当前引擎都支持。
返回具有给定索引的范围的起始时间。
如果索引超出范围,则抛出"IndexSizeError
" DOMException
。
time
= media
.end(index
)
所有当前引擎都支持。
返回具有给定索引的范围的结束时间。
如果索引超出范围,则抛出"IndexSizeError
" DOMException
。
length
IDL 属性必须返回对象表示的范围数。
start(index)
方法必须返回对象表示的第 index
个范围的起始位置,以秒为单位,从对象覆盖的时间线的开始算起。
end(index)
方法必须返回对象表示的第 index
个范围的结束位置,以秒为单位,从对象覆盖的时间线的开始算起。
如果使用大于或等于对象表示的范围数的 index
参数调用这些方法,则必须抛出"IndexSizeError
" DOMException
。
当 TimeRanges
对象被称为标准化的 TimeRanges
对象时,它表示的范围必须遵守以下标准
换句话说,此类对象中的范围是有序的,不重叠,也不接触(相邻范围折叠成一个更大的范围)。范围可以为空(仅引用时间中的一个时刻),例如,指示在用户代理已丢弃整个媒体资源(除了当前帧之外)的情况下,当前仅缓冲一帧,当媒体元素暂停时。
TimeRanges
对象中的范围必须是包含的。
因此,范围的结束将等于后续相邻(接触但不重叠)范围的开始。类似地,覆盖以零为锚点的整个时间线的范围将具有等于零的开始和等于时间线持续时间的结束。
媒体元素的 buffered
、seekable
和 played
IDL 属性返回的对象使用的时间线必须是该元素的媒体时间线。
TrackEvent
接口所有当前引擎都支持。
[Exposed =Window ]
interface TrackEvent : Event {
constructor (DOMString type , optional TrackEventInit eventInitDict = {});
readonly attribute (VideoTrack or AudioTrack or TextTrack )? track ;
};
dictionary TrackEventInit : EventInit {
(VideoTrack or AudioTrack or TextTrack )? track = null ;
};
event
.track
所有当前引擎都支持。
返回事件相关的轨道对象(TextTrack
、AudioTrack
或 VideoTrack
)。
track
属性必须返回其初始化的值。它表示事件的上下文信息。
本节为非规范性内容。
以下事件在媒体元素上触发,作为上述处理模型的一部分
事件名称 | 接口 | 触发时机... | 前提条件 |
---|---|---|---|
loadstart
HTMLMediaElement/loadstart_event 所有当前引擎都支持。 Firefox6+Safari4+Chrome3+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android未知Safari iOS3+Chrome Android未知WebView Android未知Samsung Internet未知Opera Android12.1+ | 事件
| 用户代理开始查找媒体数据,作为资源选择算法的一部分。 | networkState 等于 NETWORK_LOADING |
progress
HTMLMediaElement/progress_event 所有当前引擎都支持。 Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android未知Safari iOS3+Chrome Android未知WebView Android未知Samsung Internet未知Opera Android12.1+ | 事件
| 用户代理正在获取媒体数据。 | networkState 等于 NETWORK_LOADING |
暂停
HTMLMediaElement/suspend_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理目前有意不获取媒体数据。 | networkState 等于 NETWORK_IDLE |
中止
所有当前引擎都支持。 Firefox9+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android未知Safari iOS3+Chrome Android未知WebView Android未知Samsung Internet未知Opera Android12.1+ | 事件
| 用户代理在媒体数据完全下载之前停止了获取,但并非由于错误。 | error 是一个代码为 MEDIA_ERR_ABORTED 的对象。networkState 等于 NETWORK_EMPTY 或 NETWORK_IDLE ,具体取决于下载何时中止。 |
错误
所有当前引擎都支持。 Firefox6+Safari3.1+Chrome3+ Opera11.6+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | 事件
| 在获取媒体数据时发生错误,或者资源类型不是受支持的媒体格式。 | error 是一个代码为 MEDIA_ERR_NETWORK 或更高的对象。networkState 等于 NETWORK_EMPTY 或 NETWORK_IDLE ,具体取决于下载何时中止。 |
清空
HTMLMediaElement/emptied_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 一个媒体元素,其networkState 之前不处于NETWORK_EMPTY 状态,刚刚切换到该状态(可能是由于加载过程中发生的致命错误即将报告,或者因为load() 方法在资源选择算法 已经在运行时被调用)。 | networkState 为 NETWORK_EMPTY ;所有 IDL 属性都处于其初始状态。 |
停顿
HTMLMediaElement/stalled_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理正在尝试获取媒体数据,但数据意外未及时提供。 | networkState 为 NETWORK_LOADING 。 |
元数据加载完成
HTMLMediaElement/loadedmetadata_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理刚刚确定了媒体资源的持续时间和尺寸,并且文本轨道已准备就绪。 | readyState 首次变为等于 HAVE_METADATA 或更大。 |
数据加载完成
HTMLMediaElement/loadeddata_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理可以首次渲染媒体数据在当前播放位置。 | readyState 首次增加到 HAVE_CURRENT_DATA 或更大。 |
可以播放
HTMLMediaElement/canplay_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理可以恢复媒体数据的播放,但估计如果现在开始播放,媒体资源无法以当前播放速度渲染到结尾,而不必停止进一步缓冲内容。 | readyState 增加了到 HAVE_FUTURE_DATA 或更大。 |
可以流畅播放
HTMLMediaElement/canplaythrough_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 用户代理估计,如果现在开始播放,媒体资源可以以当前播放速度一直渲染到结尾,而无需停止进一步缓冲。 | readyState 首次变为等于 HAVE_ENOUGH_DATA 。 |
正在播放
HTMLMediaElement/playing_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 由于缺少媒体数据而暂停或延迟后,播放准备开始。 | readyState 新近变为 false。paused 为 false,或者 paused 新近变为 false 且 readyState 大于或等于 HAVE_FUTURE_DATA 。即使此事件触发,元素也可能仍未处于潜在播放状态,例如,如果元素因用户交互而暂停或因带内内容而暂停。 |
等待
HTMLMediaElement/waiting_event 所有当前引擎都支持。 Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | 事件
| 播放已停止,因为下一帧不可用,但用户代理预计该帧将在适当时候可用。 | readyState 小于或等于 HAVE_CURRENT_DATA ,并且 paused 为 false。 seeking 为 true,或者当前播放位置 不包含在 buffered 中的任何范围内。播放可能因其他原因停止而 paused 不为 false,但这些原因不会触发此事件(并且当这些情况解决时,也不会触发单独的 playing 事件):例如,播放已结束,或播放因错误停止,或元素已因用户交互而暂停或因带内内容而暂停。 |
正在查找
HTMLMediaElement/seeking_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| seeking IDL 属性更改为 true,并且用户代理已开始查找新位置。 | |
查找完成
所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| seeking IDL 属性在更改当前播放位置后更改为 false。 | |
结束
所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 播放已停止,因为已到达媒体资源的结尾。 | currentTime 等于媒体资源的结尾;ended 为 true。 |
持续时间更改
HTMLMediaElement/durationchange_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| duration 属性刚刚更新。 | |
时间更新
HTMLMediaElement/timeupdate_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 当前播放位置作为正常播放的一部分或以特别有趣的方式(例如不连续地)更改。 | |
播放
所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 元素不再暂停。在play() 方法返回后或autoplay 属性导致播放开始时触发。 | paused 新近变为 false。 |
暂停
所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| 元素已暂停。在pause() 方法返回后触发。 | paused 新近变为 true。 |
速率更改
HTMLMediaElement/ratechange_event 所有当前引擎都支持。 Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | 事件
| defaultPlaybackRate 或 playbackRate 属性刚刚更新。 | |
大小调整
| 事件
| videoWidth 和 videoHeight 属性之一或两者刚刚更新。 | 媒体元素 是一个 video 元素;readyState 不是 HAVE_NOTHING |
音量更改
HTMLMediaElement/volumechange_event 所有当前引擎都支持。 Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | 事件
| volume 属性或 muted 属性已更改。在相关属性的 setter 返回后触发。 |
以下事件在source
元素上触发
事件名称 | 接口 | 触发时机... |
---|---|---|
错误
| 事件
| 在获取媒体数据时发生错误,或者资源类型不是受支持的媒体格式。 |
以下事件在AudioTrackList
、VideoTrackList
和 TextTrackList
对象上触发
事件名称 | 接口 | 触发时机... |
---|---|---|
change
所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox31+Safari7+Chrome33+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | 事件
| 轨道列表中的一条或多条轨道已启用或禁用。 |
addtrack
所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | TrackEvent
| 轨道已添加到轨道列表中。 |
removetrack
AudioTrackList/removetrack_event 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? TextTrackList/removetrack_event 所有当前引擎都支持。 Firefox31+Safari7+Chrome33+ Opera20+Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android20+ VideoTrackList/removetrack_event 所有当前引擎都支持。 Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | TrackEvent
| 轨道已从轨道列表中移除。 |
事件名称 | 接口 | 触发时机... |
---|---|---|
cuechange
HTMLTrackElement/cuechange_event 所有当前引擎都支持。 Firefox68+Safari10+Chrome32+ Opera19+Edge79+ Edge (Legacy)14+Internet Explorer不支持 Firefox Android?Safari iOS?Chrome Android?WebView Android4.4.3+Samsung Internet?Opera Android19+ 所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | 事件
| 轨道中的一条或多条提示已激活或停止激活。 |
以下事件在轨道
元素上触发
事件名称 | 接口 | 触发时机... |
---|---|---|
错误
| 事件
| 在获取轨道数据或资源类型不受支持的文本轨道格式时发生错误。 |
加载
| 事件
| 轨道数据已获取并成功处理。 |
以下事件在TextTrackCue
对象上触发
事件名称 | 接口 | 触发时机... |
---|---|---|
enter
所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | 事件
| 提示已变为活动状态。 |
exit
所有当前引擎都支持。 Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (旧版)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | 事件
| 提示已停止处于活动状态。 |
视频
和音频
元素的主要安全和隐私影响来自嵌入跨源媒体的能力。威胁可能来自两个方向:从恶意内容到受害页面,以及从恶意页面到受害内容。
如果受害页面嵌入恶意内容,则威胁在于该内容可能包含尝试与嵌入该内容的文档
交互的脚本代码。为了避免这种情况,用户代理必须确保内容无法访问嵌入页面。对于使用DOM概念的媒体内容,嵌入内容必须被视为在其自身无关的顶级可遍历对象中。
例如,如果SVG动画嵌入到视频
元素中,用户代理不会授予其访问外部页面的DOM的权限。从SVG资源中脚本的角度来看,SVG文件似乎位于一个没有父级的独立顶级可遍历对象中。
如果恶意页面嵌入受害内容,则威胁在于嵌入页面可能会从内容中获取它原本无法访问的信息。API确实公开了一些信息:媒体的存在、类型、持续时间、大小及其主机的性能特征。此类信息本身就可能存在问题,但在实践中,可以使用img
元素或多或少地获取相同的信息,因此它被认为是可以接受的。
但是,如果用户代理进一步公开内容中的元数据(例如字幕),则可能会获取更多敏感信息。因此,只有在视频资源使用CORS时才会公开该信息。crossorigin
属性允许作者启用CORS。[FETCH]
如果没有此限制,攻击者可能会诱骗在公司网络中运行的用户访问某个站点,该站点尝试从公司内部网上的先前泄露位置加载视频。如果此类视频包含新产品的机密计划,那么能够读取字幕将构成严重的信息泄露。
本节为非规范性内容。
在机顶盒或手机等小型设备上播放音频和视频资源通常受限于设备中有限的硬件资源。例如,设备可能仅支持三个同时播放的视频。因此,在播放完成后释放媒体元素持有的资源是一种良好的实践,可以通过非常小心地删除对元素的所有引用并允许其被垃圾回收来实现,或者,更好的是,将元素的src
属性设置为空字符串。在设置了srcObject
的情况下,改为将srcObject
设置为null。
同样,当回放速度不完全为1.0时,硬件、软件或格式限制会导致视频帧丢失,音频变得断断续续或静音。
本节为非规范性内容。
如何准确地实现媒体元素 API的各个方面被认为是实现质量问题。
例如,在实现buffered
属性时,实现报告已缓冲范围的精确度取决于用户代理检查数据的仔细程度。由于API将范围报告为时间,但数据以字节流获取,因此接收可变比特率流的用户代理可能只能通过实际解码所有数据来确定精确时间。但是,用户代理不需要这样做;他们可以改为返回估计值(例如,基于迄今为止看到的平均比特率),这些估计值会随着更多信息的可用而进行修改。
一般来说,敦促用户代理保持保守而不是乐观。例如,如果尚未缓冲所有内容,则报告所有内容都已缓冲将是不好的。
另一个实现质量问题是在编解码器仅设计用于正向播放时反向播放视频(例如,关键帧不多,并且相隔很远,并且中间帧仅包含前一帧的增量)。用户代理可能做得不好,例如,只显示关键帧;但是,更好的实现将做更多工作,从而做得更好,例如,实际向前解码视频的一部分,存储完整的帧,然后向后播放帧。
同样,虽然实现允许随时丢弃缓冲数据(没有要求用户代理保留为媒体元素生命周期获取的所有媒体数据),但它仍然是实现质量问题:拥有足够资源保留所有数据的用户代理建议这样做,因为这可以提供更好的用户体验。例如,如果用户正在观看直播流,用户代理可以只允许用户查看直播视频;但是,更好的用户代理将缓冲所有内容并允许用户浏览早期内容、暂停它、向前和向后播放它等。
当已暂停的媒体元素从文档中移除并且在事件循环到达步骤1之前未重新插入时,建议资源受限的实现抓住此机会释放媒体元素使用的所有硬件资源(如视频平面、网络资源和数据缓冲区)。(但是,用户代理仍然必须跟踪回放位置等信息,以防以后重新开始回放。)