Our volunteers haven't translated this article into Română yet. Join us and help get the job done!
The HTMLMediaElement
interface adds to HTMLElement
the properties and methods needed to support basic media-related capabilities that are common to audio and video. The HTMLVideoElement
and HTMLAudioElement
elements both inherit this interface.
Properties
This interface also inherits properties from its ancestors HTMLElement
, Element
, Node
, and EventTarget
.
HTMLMediaElement.audioTracks
- Is a
AudioTrackList
that lists theAudioTrack
objects contained in the element. HTMLMediaElement.autoplay
- Is a
Boolean
that reflects theautoplay
HTML attribute, indicating whether playback should automatically begin as soon as enough media is available to do so without interruption. HTMLMediaElement.buffered
Read only- Returns a
TimeRanges
object that indicates the ranges of the media source that the browser has buffered (if any) at the moment thebuffered
property is accessed. HTMLMediaElement.controller
- Is a
MediaController
object that represents the media controller assigned to the element, ornull
if none is assigned. HTMLMediaElement.controls
- Is a
Boolean
that reflects thecontrols
HTML attribute, indicating whether user interface items for controlling the resource should be displayed. HTMLMediaElement.crossOrigin
- Is a
DOMString
indicating the CORS setting for this media element. HTMLMediaElement.currentSrc
Read only- Returns a
DOMString
with the absolute URL of the chosen media resource. HTMLMediaElement.currentTime
- Is a
double
indicating the current playback time in seconds. Setting this value seeks the media to the new time. HTMLMediaElement.defaultMuted
- Is a
Boolean
that reflects themuted
HTML attribute, which indicates whether the media element's audio output should be muted by default. HTMLMediaElement.defaultPlaybackRate
- Is a
double
indicating the default playback rate for the media. HTMLMediaElement.disableRemotePlayback
- Is a
Boolean
that sets or returns the remote playback state, indicating whether the media element is allowed to have a remote playback UI. HTMLMediaElement.duration
Read only- Returns a
double
indicating the length of the media in seconds, or 0 if no media data is available. HTMLMediaElement.ended
Read only- Returns a
Boolean
that indicates whether the media element has finished playing. HTMLMediaElement.error
Read only- Returns a
MediaError
object for the most recent error, ornull
if there has not been an error. HTMLMediaElement.initialTime
Read only- Returns a
double
that indicates the initial playback position in seconds. HTMLMediaElement.loop
- Is a
Boolean
that reflects theloop
HTML attribute, which indicates whether the media element should start over when it reaches the end. HTMLMediaElement.mediaGroup
- Is a
DOMString
that reflects themediagroup
HTML attribute, which indicates the name of the group of elements it belongs to. A group of media elements shares a commonMediaController
. HTMLMediaElement.mediaKeys
Read only- Returns a
MediaKeys
object ornull
. MediaKeys is a set of keys that an associated HTMLMediaElement can use for decryption of media data during playback. HTMLMediaElement.mozAudioCaptured
Read only- Returns a
Boolean
. Related to audio stream capture. HTMLMediaElement.mozAudioChannelType
- (Firefox OS only) Is a
String
that can be used to set the audio channel that the sound coming from an<audio>
or<video>
element will play in, on a Firefox OS device. See Using the AudioChannels API for more details. HTMLMediaElement.mozChannels
Read only- Returns a
double
representing the number of channels in the audio resource (e.g.,2
for stereo). HTMLMediaElement.mozFragmentEnd
- Is a
double
that provides access to the fragment end time if the media element has a fragment URI forcurrentSrc
, otherwise it is equal to the media duration. HTMLMediaElement.mozFrameBufferLength
-
Is a
unsigned long
that indicates the number of samples that will be returned in the framebuffer of eachMozAudioAvailable
event. This number is a total for all channels, and by default is set to be the number of channels * 1024 (e.g., 2 channels * 1024 samples = 2048 total).The
mozFrameBufferLength
property can be set to a new value for lower latency, larger amounts of data, etc. The size given must be a number between 512 and 16384. Using any other size results in an exception being thrown. The best time to set a new length is after the loadedmetadata event fires, when the audio info is known, but before the audio has started orMozAudioAvailable
events have begun firing. HTMLMediaElement.mozSampleRate
Read only- Returns a
double
representing the number of samples per second that will be played. For example, 44100 samples per second is the sample rate used by CD audio. HTMLMediaElement.muted
- Is a
Boolean
that determines whether audio is muted.true
if the audio is muted andfalse
otherwise. HTMLMediaElement.networkState
Read only- Returns a
unsigned short
(enumeration) indicating the current state of fetching the media over the network. HTMLMediaElement.paused
Read only- Returns a
Boolean
that indicates whether the media element is paused. HTMLMediaElement.playbackRate
- Is a
double
that indicates the rate at which the media is being played back. HTMLMediaElement.played
Read only- Returns a
TimeRanges
object that contains the ranges of the media source that the browser has played, if any. HTMLMediaElement.preload
- Is a
DOMString
that reflects thepreload
HTML attribute, indicating what data should be preloaded, if any. Possible values are:none
,metadata
,auto
. HTMLMediaElement.preservesPitch
- Is a
Boolean
that determines if the pitch of the sound will be preserved. If set tofalse
, the pitch will adjust to the speed of the audio. This is implemented with prefixes in Firefox (mozPreservesPitch
) and WebKit (webkitPreservesPitch
). HTMLMediaElement.readyState
Read only- Returns a
unsigned short
(enumeration) indicating the readiness state of the media. HTMLMediaElement.seekable
Read only- Returns a
TimeRanges
object that contains the time ranges that the user is able to seek to, if any. HTMLMediaElement.seeking
Read only- Returns a
Boolean
that indicates whether the media is in the process of seeking to a new position. HTMLMediaElement.sinkId
Read only- Returns a
DOMString
that is the unique ID of the audio device delivering output, or an empty string if it is using the user agent default. This ID should be one of theMediaDeviceInfo.deviceid
values returned fromMediaDevices.enumeratedDevices()
,id-multimedia
, orid-communications
. HTMLMediaElement.src
- Is a
DOMString
that reflects thesrc
HTML attribute, which contains the URL of a media resource to use. HTMLMediaElement.srcObject
- Is a
MediaStream
representing the media to play or that has played in the currentHTMLMediaElement
. HTMLMediaElement.textTracks
Read only- Returns the list of
TextTrack
objects contained in the element. HTMLMediaElement.videoTracks
Read only- Returns the list of
VideoTrack
objects contained in the element.Note: Gecko supports only single track playback, and the parsing of tracks' metadata is only available for media with the Ogg container format.
HTMLMediaElement.volume
- Is a
double
indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).
Event handler properties
HTMLMediaElement.onmozinterruptbegin
- Sets the
EventHandler
called when the media element is interrupted because of the audiochannel manager. HTMLMediaElement.onmozinterruptend
- Sets the
EventHandler
called when the interruption is concluded. HTMLMediaElement.onencrypted
- Sets the
EventHandler
called when the media is encrypted.
Methods
This interface also inherits methods from its ancestors HTMLElement
, Element
, Node
, and EventTarget
.
HTMLMediaElement.addTextTrack()
- Adds a text track (such as a track for subtitles) to a media element.
HTMLMediaElement.captureStream()
- Returns
MediaStream
, captures a stream of the media content. HTMLMediaElement.canPlayType()
- Determines whether the specified media type can be played back.
HTMLMediaElement.fastSeek()
- Directly seeks to the given time.
HTMLMediaElement.load()
- Resets the media element and restarts the media resource. Any pending events are discarded. How much media data is fetched is still affected by the
preload
attribute. This method can be useful for releasing resources after anysrc
attribute andsource
element descendants have been removed. Otherwise, it is usually unnecessary to use this method, unless required to rescansource
element children after dynamic changes. HTMLMediaElement.mozCaptureStream()
- [enter description]
HTMLMediaElement.mozCaptureStreamUntilEnded()
- [enter description]
HTMLMediaElement.mozGetMetadata()
- Returns
Object
, which contains properties that represent metadata from the playing media resource as{key: value}
pairs. A separate copy of the data is returned each time the method is called. This method must be called after the loadedmetadata event fires. HTMLMediaElement.mozLoadFrom()
- This method, available only in Mozilla's implementation, loads data from another media element. This works similarly to
load()
except that instead of running the normal resource selection algorithm, the source is simply set to theother
element'scurrentSrc
. This is optimized so this element gets access to all of theother
element's cached and buffered data; in fact, the two elements share downloaded data, so data downloaded by either element is available to both. HTMLMediaElement.pause()
- Pauses the media playback.
HTMLMediaElement.play()
- Begins playback of the media.
HTMLMediaElement.seekToNextFrame()
- Seeks to the next frame in the media. This non-standard, experimental method makes it possible to manually drive reading and rendering of media at a custom speed, or to move through the media frame-by-frame to perform filtering or other operations.
HTMLMediaElement.setMediaKeys()
- Returns
Promise
. Sets theMediaKeys
keys to use when decrypting media during playback. HTMLMediaElement.setSinkId()
- Sets the ID of the audio device to use for output and returns a
Promise
. This only works when the application is authorized to use the specified device.
Specifications
Specification | Status | Comment |
---|---|---|
WHATWG HTML Living Standard The definition of 'HTMLMediaElement' in that specification. |
Living Standard | No change from HTML5 |
HTML5 The definition of 'HTMLMediaElement' in that specification. |
Recommendation | Initial definition. |
Encrypted Media Extensions The definition of 'Encrypted Media Extensions' in that specification. |
Working Draft | Adds MediaKeys , MediaEncryptedEvent , and setMediaKeys. |
Media Capture and Streams The definition of 'HTMLMediaElement' in that specification. |
Editor's Draft | Adds sinkId and setSinkId() , and captureStream() . |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | 3.5 (1.9.1) [1] | 9 | ? | ? |
buffered property |
(Yes) | 4.0 (2.0) | 9 | ? | ? |
defaultMuted property |
(Yes) | 11.0 (11.0) | ? | ? | ? |
loop property |
(Yes) | 11.0 (11.0) | 9 | ? | ? |
seekable property |
(Yes) | 8.0 (8.0) | 9 | ? | ? |
defaultPlaybackRate property |
(Yes) | 20.0 (20.0) | 9 | ? | ? |
playbackRate property |
(Yes) | 20.0 (20.0) | 9 | ? | ? |
preservesPitch property |
(Yes)webkit | 20.0 (20.0)moz | No support | No support | No support |
preload property |
(Yes) | 4.0 (2.0)[2] | ? | ? | ? |
played property |
(Yes) | 15.0 (15.0) | ? | ? | ? |
crossOrigin property |
(Yes) | 12.0 (12.0)[3] 22.0 (22.0) |
? | ? | ? |
mozAudioChannelType property |
No support | No support | No support | No support | No support |
mozChannels , mozFrameBufferLength , mozSampleRate properties |
No support | 4.0 (2.0) | No support | No support | No support |
mozGetMetadata() |
No support | 17.0 (17.0) | No support | No support | No support |
mozLoadFrom() Obsolete since Gecko 24 |
No support | 3.6 (1.9.2) | No support | No support | No support |
mozSrcObject property |
No support | 18.0 (18.0) | No support | No support | No support |
initialTime property |
? | 9.0 (9.0)[4] | ? | ? | ? |
fastSeek method |
? | 31.0 (31.0) | ? | ? | ? |
startDate property |
? | No support[8] | ? | ? | ? |
mediaGroup and controller properties |
? | No support[9] | ? | ? | ? |
audioTracks , and videoTracks properties |
? | 33.0 (33.0) [5] | ? | ? | ? |
textTracks property |
? | Nightly build [6] | ? | ? | ? |
sinkId property and setSinkId() method |
49.0 | ? | ? | ? | ? |
seekToNextFrame() method |
? | 49 (49) [10] | ? | ? | ? |
srcObject | 52.0 | ? | ? | 39 | ? |
captureStream() |
53.0 | ? | ? | ? | ? |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | Firefox OS (Gecko) | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic support | (Yes) | (Yes) | (Yes) | (Yes) | ? | (Yes) | (Yes) | (Yes) |
buffered property |
(Yes) | (Yes) | 4.0 (2.0) | (Yes) | ? | ? | ? | (Yes) |
defaultMuted property |
(Yes) | (Yes) | 11.0 (11.0) | (Yes) | ? | ? | ? | (Yes) |
loop property |
(Yes) | (Yes) | 11.0 (11.0) | (Yes) | ? | ? | ? | (Yes) |
seekable property |
(Yes) | (Yes) | 8.0 (8.0) | (Yes) | ? | ? | ? | (Yes) |
defaultPlaybackRate property |
(Yes) | (Yes) | 20.0 (20.0) | (Yes) | ? | ? | ? | (Yes) |
playbackRate property |
(Yes) | (Yes) | 20.0 (20.0) | (Yes) | ? | ? | ? | (Yes) |
preservesPitch property |
(Yes)webkit | (Yes) | 20.0 (20.0)moz | (Yes) | No support | No support | No support | (Yes) |
preload property |
(Yes) | (Yes) | 4.0 (2.0) | (Yes) | ? | ? | ? | (Yes) |
played property |
(Yes) | (Yes) | 15.0 (15.0) | (Yes) | ? | ? | ? | (Yes) |
crossOrigin property |
(Yes) | (Yes) | 12.0 (12.0)[3] 22.0 (22.0) |
(Yes) | ? | ? | ? | (Yes) |
mozAudiochannelType |
No support | No support | No support | 1.0.1 | No support | No support | No support | No support |
mozChannels , mozFrameBufferLength , mozSampleRate properties |
No support | No support | 4.0 (2.0) | (Yes) | No support | No support | No support | No support |
mozGetMetadata() |
No support | No support | 17.0 (17.0) | (Yes) | No support | No support | No support | No support |
mozLoadFrom() |
No support | No support | 1.0 (1.9.2)[7] | (Yes) | No support | No support | No support | No support |
mozSrcObject property |
No support | No support | 18.0 (18.0) | (Yes) | No support | No support | No support | No support |
initialTime property |
? | ? | 9.0 (9.0)[4] | (Yes) | ? | ? | ? | ? |
fastSeek method |
? | ? | 31.0 (31.0) | (Yes) | ? | ? | ? | ? |
startDate property |
? | ? | No support[8] | (Yes) | ? | ? | ? | ? |
mediaGroup and controller properties |
? | ? | No support[9] | (Yes) | ? | ? | ? | ? |
audioTracks , and videoTracks properties |
? | ? | 33.0 (33.0)[5] | (Yes) | ? | ? | ? | ? |
textTracks property |
? | ? | Nightly build[6] | (Yes) | ? | ? | ? | ? |
sinkId property and setSinkId() method |
? | 49.0 | ? | ? | ? | ? | ? | 49.0 |
seekToNextFrame() method |
? | ? | 49.0 (49) [10] | ? | ? | ? | ? | ? |
srcObject | No support | 52.0 | ? | ? | ? | 39 | ? | 52.0 |
captureStream() |
No support | 53.0 | ? | ? | ? | ? | ? | 53.0 |
[1] The NETWORK_LOADED
state was removed to align with the HTML spec in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1).
[2] Previously Gecko implemented this as autobuffer
.
[3] Gecko implements this in lowercase, i.e. crossorigin
.
[4] The feature was removed in Gecko 23.0 (Firefox 23 / Thunderbird 23 / SeaMonkey 2.20).
[5] The implementation is hidden behind the media.track.enabled
preference.
[6] The implementation is hidden behind the media.webvtt.enabled
preference, defaulting there to true
.
[7] This feature was removed in 24.0 (24).
[8] Gecko doesn't implement this yet. See bug 847376.
[9] Gecko doesn't implement this yet. See bug 847377.
[10] The preference media.seekToNextFrame
must be enabled to use the seekToNextFrame()
method.
See also
- References
<video>
and<audio>
HTML elements.HTMLVideoElement
andHTMLAudioElement
interfaces, derived fromHTMLMediaElement
.
- Articles