HTMLMediaElement - 包含基本媒体功能所需的属性和方法

HTMLMediaElement 接口为 HTMLElement 添加了支持音频和视频共有的基本媒体相关功能所需的属性和方法。 HTMLVideoElement和 HTMLAudioElement 元素都继承此接口。

属性

该接口还从其祖先 HTMLElement，Element，Node 和 EventTarget 继承了属性。

HTMLMediaElement.audioTracks

一个 AudioTrackList，列出了元素中包含的 AudioTrack 对象。

HTMLMediaElement.autoplay

一个 Boolean，反映了 autoplay HTML 属性，指示一旦有足够的媒体可以不间断地播放，播放是否应该自动开始。

注意：网站自动播放音频（或带有音轨的视频）的话，可能会给用户带来不愉快的体验，因此应尽可能避免。如果您必须提供自动播放功能，您应该设置为可选的（要求用户专门启用它）。但是，如果是先创建了该元素，稍后在用户控制下设置了源地址才自动播放，则该属性会很有帮助。

HTMLMediaElement.buffered 只读

返回 TimeRanges 对象，该对象指示在访问 buffered 属性时浏览器已缓冲的媒体源的范围（如果有的话）。

HTMLMediaElement.controller

一个 MediaController 对象，表示分配给元素的媒体控制器，如果没有分配，则为 null。

HTMLMediaElement.controls

一个 Boolean，它反映了 controls HTML 属性，指示是否应显示用于控制资源的用户界面项。

HTMLMediaElement.controlsList 只读

返回 DOMTokenList，帮助用户代理在用户代理显示自己的控件集时选择要在媒体元素上显示的控件。DOMTokenList 采用三个可能值中的一个或多个：nodownload，nofullscreen 和 noremoteplayback。

HTMLMediaElement.crossOrigin

一个 DOMString，表示此媒体元素的 CORS 设置。

HTMLMediaElement.currentSrc 只读

返回一个 DOMString，表示所选媒体资源的绝对 URL。

HTMLMediaElement.currentTime

一个 double，表示当前播放时间，以秒为单位。设置此值可将媒体搜索到新的时间。

HTMLMediaElement.defaultMuted

一个 Boolean，反映了 muted HTML 属性，它指示媒体元素的音频输出是否应默认静音。

HTMLMediaElement.defaultPlaybackRate

一个 double，表示媒体的默认播放速率。

HTMLMediaElement.disableRemotePlayback

一个 Boolean，设置或返回远程回放状态，指示是否允许媒体元素具有远程回放 UI。

HTMLMediaElement.duration 只读

返回一个 double，以秒为单位表示媒体的长度，如果没有可用的媒体数据，则返回 0。

HTMLMediaElement.ended 只读

返回一个 Boolean，指示媒体元素是否已完成播放。

HTMLMediaElement.error 只读

返回一个 MediaError 对象，表示最后的错误，如果没有错误则返回 null。

HTMLMediaElement.loop

一个 Boolean，它反映了 loop HTML 属性，它指示媒体元素在到达结尾时是否应该重新开始。

HTMLMediaElement.mediaGroup

一个 DOMString，它反映了 mediagroup HTML 属性，指示了它所属的元素组的名称。一组媒体元素共享一个共同的 MediaController。

HTMLMediaElement.mediaKeys 只读

返回 MediaKeys 对象或 null。 MediaKeys 是一组密钥，关联的 HTMLMediaElement 可以在回放期间用于解密媒体数据。

HTMLMediaElement.mozAudioCaptured 只读

返回 Boolean。与音频流捕获相关。

HTMLMediaElement.mozFragmentEnd

一个 double，如果 media 元素具有 currentSrc 的片段 URI，则表示片段的结束时间，否则它等于媒体持续时间。

HTMLMediaElement.mozFrameBufferLength

一个 unsigned long ，表示将在每个 MozAudioAvailable 事件的帧缓冲区中返回的样本数。该数字是所有频道的总数，并且默认设置为频道数 * 1024（例如，2 个频道 * 1024 个样本 = 总共 2048 个）。

可以将 mozFrameBufferLength 属性设置为新值，以获得更低的延迟，更大量的数据等。给定的大小必须是介于 512 和 16384 之间的数字。使用任何其他大小会导致抛出异常。设置新长度的最佳时间是在 loadedmetadata 事件触发之后，即音频信息已知时；同时在音频开始或 MozAudioAvailable 事件触发之前。

HTMLMediaElement.mozSampleRate 只读

返回一个 double ，表示每秒将播放的样本数。例如，每秒 44100 个样本是 CD 音频使用的采样率。

HTMLMediaElement.muted

一个 Boolean，用于确定音频是否静音。如果音频被静音则为 true，否则为 false。

HTMLMediaElement.networkState 只读

返回一个 unsigned short （枚举），指示通过网络获取媒体的当前状态。

HTMLMediaElement.paused 只读

返回一个 Boolean，指示媒体元素是否已暂停。

HTMLMediaElement.playbackRate

一个 double，表示媒体播放的速率。

HTMLMediaElement.played 只读

返回一个 TimeRanges 对象，其中包含浏览器播放的媒体源范围（如果有的话）。

HTMLMediaElement.preload

一个 DOMString，它反映了 preload HTML 属性，指示应该预加载哪些数据（如果有的话）。可能的值有：none ，metadata，auto。

HTMLMediaElement.preservesPitch

一个 Boolean，用于确定是否保留声音的音高。如果设置为 false，则音高将调整为音频的速度。它需要通过 Firefox（mozPreservesPitch）和 WebKit（webkitPreservesPitch）中的前缀来调用的。

HTMLMediaElement.readyState 只读

返回一个 unsigned short （枚举），表示媒体的就绪状态。

HTMLMediaElement.seekable 只读

返回一个 TimeRanges 对象，其中包含用户可以搜索的时间范围（如果有的话）。

HTMLMediaElement.seeking 只读

返回一个 Boolean，指示媒体是否正在寻找新位置。

HTMLMediaElement.sinkId 只读

返回一个 DOMString，它是传递输出的音频设备的唯一 ID，如果使用用户代理默认值，则返回空字符串。此 ID 应该是从 MediaDevices.enumerateDevices()，id-multimedia 或 id-communications 之一返回的 MediaDeviceInfo.deviceid 值。

HTMLMediaElement.src

一个 DOMString，它反映了 src HTML 属性，其中包含要使用的媒体资源的 URL。

HTMLMediaElement.srcObject

一个 MediaStream 表示要播放的媒体或在当前 HTMLMediaElement 中播放的媒体，如果未分配，则为 null。

HTMLMediaElement.textTracks 只读

返回元素中包含的 TextTrack 对象的列表。

HTMLMediaElement.videoTracks 只读

返回元素中包含的 VideoTrack 对象的列表。

Gecko 仅支持单轨播放，并且轨道元数据的解析仅适用于具有 Ogg 容器格式的媒体。

HTMLMediaElement.volume

一个 double，表示音频音量，从 0.0（静音）到 1.0（最响亮）。

事件处理程序

HTMLMediaElement.onencrypted

设置加密媒体时调用的 EventHandler。

HTMLMediaElement.onwaitingforkey

设置在等待加密密钥时阻止播放时调用的 EventHandler。

过时的属性

这些属性已过时，即使浏览器仍支持它们，也不应使用它们。

HTMLMediaElement.initialTime 只读

返回一个 double，表示以秒为单位的初始播放位置。

HTMLMediaElement.mozChannels 只读

返回一个 double，表示音频资源中通道数（例如，立体声的 2）。

过时的事件处理程序

HTMLMediaElement.onmozinterruptbegin

设置因媒体元素因音频通道管理器而中断时调用的 EventHandler。这是 Firefox 特有的，曾经在 Firefox OS 实现，并在 Firefox 55 中被删除。

HTMLMediaElement.onmozinterruptend

设置中断结束时调用的 EventHandler。这是 Firefox 特有的，曾经在 Firefox OS 实现，并在 Firefox 55 中被删除。

方法

此接口还从其祖先 HTMLElement，Element，Node 和 EventTarget 继承了方法。

HTMLMediaElement.addTextTrack()

将文本轨道（例如字幕轨道）添加到媒体元素。

HTMLMediaElement.captureStream()

返回 MediaStream，表示捕获媒体内容的流。

HTMLMediaElement.canPlayType()

确定是否可以播放指定的媒体类型。

HTMLMediaElement.fastSeek()

直接跳转到给定的时间。

HTMLMediaElement.load()

将媒体重置到开头，并使用 src 属性或 <source> 元素从提供的源中选择最佳可用源。

HTMLMediaElement.mozCaptureStream()

暂无描述

HTMLMediaElement.mozCaptureStreamUntilEnded()

暂无描述

HTMLMediaElement.mozGetMetadata()

返回 Object，其中包含将播放媒体资源中的元数据表示为 {key: value} 对的属性。每次调用方法时都会返回单独的数据副本。此方法必须在触发 loadedmetadata 事件后才能调用。

HTMLMediaElement.pause()

暂停媒体播放。

HTMLMediaElement.play()

开始播放媒体。

HTMLMediaElement.seekToNextFrame()

跳转到媒体的下一帧。这种非标准的实验方法使得可以以自定义速度手动驱动媒体的读取和渲染，或者逐帧地移动媒体以执行过滤或其他操作。

HTMLMediaElement.setMediaKeys()

返回 Promise。设置在播放期间解密媒体时要使用的 MediaKeys 键。

HTMLMediaElement.setSinkId()

设置要用于输出的音频设备的 ID，并返回 Promise。这仅在应用程序被授权使用指定的设备时有效。

过时的方法

这些方法已过时，即使浏览器仍支持它们，也不应使用它们。

HTMLMediaElement.mozLoadFrom()

此方法仅在 Mozilla 的实现中可用：从另一个媒体元素加载数据。它和 load() 类似，不同的地方是运行的是普通的资源选择算法，将源简单的设置为 other 元素的 currentSrc，它经过优化的，因此该元素可以访问所有 other 元素的缓存和缓冲数据；事实上，这两个元素共享下载的数据，因此任何一个元素下载的数据都可用。

事件

从 GlobalEventHandlers mixin 中定义的父接口 HTMLElement 继承了方法。可以使用 addEventListener 或通过将事件监听器分配给此接口的 oneventname 属性来监听这些事件。

abort

资源未完全加载，但又不是错误导致时触发。

canplay

当用户代理可以播放媒体，但估计已经加载的数据还不足以播放媒体直到其结束，稍后需要暂停来进一步缓冲内容时触发。

canplaythrough

当用户代理可以播放媒体，并且估计已经加载了足够的数据以播放媒体直到其结束，稍后不必暂停来进一步缓冲内容时触发。

durationchange

媒体长度属性更新后触发。

emptied

媒体变空时触发；例如，当媒体已加载（或部分加载）时，调用 HTMLMediaElement.load() 方法重新加载它。

ended

当媒体（<audio> 或 <video>）结束或没有其他可用数据了，播放停止时触发。

error

由于错误而无法加载资源时触发。

loadeddata

在媒体的第一帧完成加载时触发。

loadedmetadata

加载元数据时触发

loadstart

浏览器开始加载资源时触发。

pause

在处理暂停播放请求并且活动已进入其暂停状态时触发，最常见于调用媒体的 HTMLMediaElement.pause() 方法时。

play

由于 HTMLMediaElement.play() 方法或 autoplay 属性导致 paused 属性由 true 变为 false 时触发。

playing

由于暂停或缺少数据而延迟播放之后，准备好开始播放时触发。

progress

浏览器加载资源时定期触发。

ratechange

播放速率发生变化时触发。

seeked

跳转操作完成时触发。

seeking

跳转操作开始时触发。

stalled

当用户代理尝试获取媒体数据，但数据意外地没有出现时触发。

suspend

媒体数据加载暂停时触发。

timeupdate

当 currentTime 属性指示的时间已更新时触发。

volumechange

音量发生变化时触发。

waiting

由于暂时缺少数据而暂停播放时触发。

规范

规范	状态	备注
Media Capture and Streams HTMLMediaElement 的定义	编者的草案	增加了 sinkId， setSinkId() 和 captureStream()。
Encrypted Media Extensions Encrypted Media Extensions 的定义	工作草案	增加了 MediaKeys，MediaEncryptedEvent，setMediaKeys，onencrypted 和 onwaitingforkey。
HTML Living Standard HTMLMediaElement 的定义	现行的标准	自从 HTML5 以来没有变化。
HTML5 HTMLMediaElement 的定义	推荐	初始定义。

桌面浏览器兼容性

移动浏览器兼容性

1. Firefox 尚未实现此功能。参见 bug 847377。

2. 通过 crossorigin 支持。

3. 删除了 NETWORK_LOADED 状态，从而与 Firefox 4 中的 HTML 规范保持一致。

相关链接

• 参考
  • <video> 和 <audio> HTML 元素。
  • HTMLVideoElement 和 HTMLAudioElement 接口，派生自 HTMLMediaElement。
• 文章
  • 使用 HTML5 音频和视频
  • 音频和视频元素支持的媒体格式
  • Web Audio API