video
elementaudio
elementsource
elementvideo
elementStatus: Last call for comments. ISSUE-9 (video-accessibility) blocks progress to Last Call
controls
attribute: Interactive content.src
attribute:
transparent, but with no media element descendants.src
attribute: one or more source
elements, then
transparent, but with no media element descendants.src
poster
preload
autoplay
loop
controls
width
height
interface HTMLVideoElement : HTMLMediaElement { attribute DOMString width; attribute DOMString height; readonly attribute unsigned long videoWidth; readonly attribute unsigned long videoHeight; attribute DOMString poster; };
A video
element is used for playing videos or
movies.
Content may be provided inside the video
element; it is intended for older Web browsers which do
not support video
, so that legacy video plugins can be
tried, or to show text to the users of these older browsers informing
them of how to access the video contents.
In particular, this content is not intended to address accessibility concerns. To make video content accessible to the blind, deaf, and those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as caption or subtitle tracks, audio description tracks, or sign-language overlays) into their media streams.
The video
element is a media element
whose media data is ostensibly video data, possibly
with associated audio data.
The src
, preload
, autoplay
, loop
, and controls
attributes are the attributes common to all media
elements.
The poster
attribute gives the address of an image file that the user agent can
show while no video data is available. The attribute, if present,
must contain a valid non-empty URL potentially surrounded by
spaces.
The image given by the poster
attribute, the poster
frame, is intended to be a representative frame of the video
(typically one of the first non-blank frames) that gives the user an
idea of what the video is like.
videoWidth
videoHeight
These attributes return the intrinsic dimensions of the video, or zero if the dimensions are not known.
The video
element supports dimension
attributes.
This example shows how to detect when a video has failed to play correctly:
<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
elementStatus: Last call for comments
controls
attribute: Interactive content.src
attribute:
transparent, but with no media element descendants.src
attribute: one or more source
elements, then
transparent, but with no media element descendants.src
preload
autoplay
loop
controls
[NamedConstructor=Audio(), NamedConstructor=Audio(in DOMString src)] interface HTMLAudioElement : HTMLMediaElement {};
An audio
element represents a sound or
audio stream.
Content may be provided inside the audio
element; it is intended for older Web browsers which do
not support audio
, so that legacy audio plugins can be
tried, or to show text to the users of these older browsers informing
them of how to access the audio contents.
In particular, this content is not intended to address accessibility concerns. To make audio content accessible to the deaf or to those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as transcriptions) into their media streams.
The audio
element is a media element
whose media data is ostensibly audio data.
The src
, preload
, autoplay
, loop
, and controls
attributes are the attributes common to all media
elements.
Audio
( [ url ] )Returns a new audio
element, with the src
attribute set to the value
passed in the argument, if applicable.
source
elementStatus: Last call for comments
src
type
media
interface HTMLSourceElement : HTMLElement { attribute DOMString src; attribute DOMString type; attribute DOMString media; };
The source
element allows authors to specify
multiple alternative media
resources for media
elements. It does not represent anything on its own.
The src
attribute
gives the address of the media resource. The value must
be a valid non-empty URL potentially surrounded by
spaces. This attribute must be present.
The type
attribute gives the type of the media resource, to help
the user agent determine if it can play this media
resource before fetching it. If specified, its value must be
a valid MIME type. The codecs
parameter may be specified and might be necessary to specify exactly
how the resource is encoded. [RFC4281]
The following list shows some examples of how to use the codecs=
MIME parameter in the type
attribute.
<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
<source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'>
<source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'>
<source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'>
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'>
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'>
<source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'>
<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'>
<source src='video.ogv' type='video/ogg; codecs="theora, speex"'>
<source src='audio.ogg' type='audio/ogg; codecs=vorbis'>
<source src='audio.spx' type='audio/ogg; codecs=speex'>
<source src='audio.oga' type='audio/ogg; codecs=flac'>
<source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'>
<source src='video.mkv' type='video/x-matroska; codecs="theora, vorbis"'>
The media
attribute gives the intended media type of the media
resource, to help the user agent determine if this
media resource is useful to the user before fetching
it. Its value must be a valid media query.
The default, if the media
attribute is omitted, is
"all
", meaning that by default the media
resource is suitable for all media.
If the author isn't sure if the user agents will all be able to
render the media resources provided, the author can listen to the
error
event on the last
source
element and trigger fallback behavior:
<script> function fallback(video) { // replace <video> with its contents while (video.hasChildNodes()) { if (video.firstChild instanceof HTMLSourceElement) video.removeChild(video.firstChild); else video.parentNode.insertBefore(video.firstChild, video); } video.parentNode.removeChild(video); } </script> <video controls autoplay> <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'> <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"' onerror="fallback(parentNode)"> ... </video>
Status: Last call for comments
Media elements implement the following interface:
interface HTMLMediaElement : HTMLElement { // error state readonly attribute MediaError error; // network state attribute DOMString src; readonly attribute DOMString currentSrc; 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; attribute DOMString preload; readonly attribute TimeRanges buffered; void load(); DOMString canPlayType(in 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 float currentTime; readonly attribute float startTime; readonly attribute float duration; readonly attribute boolean paused; attribute float defaultPlaybackRate; attribute float playbackRate; readonly attribute TimeRanges played; readonly attribute TimeRanges seekable; readonly attribute boolean ended; attribute boolean autoplay; attribute boolean loop; void play(); void pause(); // controls attribute boolean controls; attribute float volume; attribute boolean muted; };
The media element attributes, src
, preload
, autoplay
, loop
, and controls
, apply to all media elements. They are defined in
this section.
Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video. The term media resource is used to refer to the complete set of media data, e.g. the complete video file, or complete audio file.
Status: Last call for comments
error
Returns a MediaError
object representing the
current error state of the element.
Returns null if there is no error.
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; };
error
. code
Returns the current error's error code, from the list below.
MEDIA_ERR_ABORTED
(numeric value 1)MEDIA_ERR_NETWORK
(numeric value 2)MEDIA_ERR_DECODE
(numeric value 3)MEDIA_ERR_SRC_NOT_SUPPORTED
(numeric value 4)src
attribute was not suitable.Status: Last call for comments
The src
content
attribute on media elements gives
the address of the media resource (video, audio) to show. The
attribute, if present, must contain a valid non-empty
URL potentially surrounded by spaces.
currentSrc
Returns the address of the current media resource.
Returns the empty string when there is no media resource.
There are two ways to specify a media
resource, the src
attribute, or source
elements. The attribute overrides
the elements.
Status: Last call for comments
A media resource can be described in terms of its
type, specifically a MIME type, optionally
with a codecs
parameter. [RFC4281]
Types are usually somewhat incomplete descriptions; for example
"video/mpeg
" doesn't say anything except what
the container type is, and even a type like "video/mp4; codecs="avc1.42E01E,
mp4a.40.2"
" doesn't include information like the actual
bitrate (only the maximum bitrate). Thus, given a type, a user agent
can often only know whether it might be able to play
media of that type (with varying levels of confidence), or whether
it definitely cannot play media of that type.
A type that the user agent knows it cannot render is one that describes a resource that the user agent definitely does not support, for example because it doesn't recognize the container type, or it doesn't support the listed codecs.
The MIME type "application/octet-stream
" with no parameters is
never a type that the user agent knows it cannot
render. User agents must treat that type as equivalent to the
lack of any explicit Content-Type
metadata when it is used to label a potential media
resource.
In the absence of a
specification to the contrary, the MIME type "application/octet-stream
" when used with
parameters, e.g. "application/octet-stream;codecs=theora
", is
a type that the user agent knows it cannot render.
canPlayType
(type)Returns the empty string (a negative response), "maybe", or "probably" based on how confident the user agent is that it can play media resources of the given type.
This script tests to see if the user agent supports a
(fictional) new format to dynamically decide whether to use a
video
element or a plugin:
<section id="video"> <p><a href="playing-cats.nfv">Download video</a></p> </section> <script> var videoSection = document.getElementById('video'); var videoElement = document.createElement('video'); var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"'); if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) { // not confident of browser support // but we have a plugin // so use plugin instead videoElement = document.createElement("embed"); } else if (support == "") { // no support from browser and no plugin // do nothing videoElement = null; } if (videoElement) { while (videoSection.hasChildNodes()) videoSection.removeChild(videoSection.firstChild); videoElement.setAttribute("src", "playing-cats.nfv"); videoSection.appendChild(videoElement); } </script>
The type
attribute of the source
element allows the user agent
to avoid downloading resources that use formats it cannot
render.
Status: Last call for comments
networkState
Returns the current state of network activity for the element, from the codes in the list below.
NETWORK_EMPTY
(numeric value 0)NETWORK_IDLE
(numeric value 1)NETWORK_LOADING
(numeric value 2)NETWORK_NO_SOURCE
(numeric value 3)Status: Last call for comments
load
()Causes the element to reset and start selecting and loading a new media resource from scratch.
The preload
attribute is an enumerated attribute. The following table
lists the keywords and states for the attribute — the keywords
in the left column map to the states in the cell in the second
column on the same row as the keyword.
Keyword | State | Brief description |
---|---|---|
none
| None | Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimise unnecessary traffic. |
metadata
| Metadata | Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, first frame, track list, duration, etc) is reasonable. |
auto
| Automatic | Hints to the user agent that the user agent can put the user's needs first without risk to the server, up to and including optimistically downloading the entire resource. |
The empty string is also a valid keyword, and maps to the Automatic state. The attribute's missing value default is user-agent defined, though the Metadata state is suggested as a compromise between reducing server load and providing an optimal user experience.
The autoplay
attribute can overrride
the preload
attribute (since
if the media plays, it naturally has to buffer first, regardless of
the hint given by the preload
attribute). Including
both is not an error, however.
buffered
Returns a TimeRanges
object that represents the
ranges of the media resource that the user agent has
buffered.
Status: Last call for comments
duration
Returns the length of the media resource, in seconds.
Returns NaN if the duration isn't available.
Returns Infinity for unbounded streams.
currentTime
[ = value ]Returns the current playback position, in seconds.
Can be set, to seek to the given time.
Will throw an INVALID_STATE_ERR
exception if there
is no selected media resource. Will throw an
INDEX_SIZE_ERR
exception if the given time is not
within the ranges to which the user agent can seek.
startTime
Returns the earliest possible position, in seconds. This is the time for the start of the current clip. It might not be zero if the clip's timeline is not zero-based, or if the resource is a streaming resource (in which case it gives the earliest time that the user agent is able to seek back to).
The loop
attribute is a boolean attribute that, if specified,
indicates that the media element is to seek back to the
start of the media resource upon reaching the end.
Status: Last call for comments
readyState
Returns a value that expresses the current state of the element with respect to rendering the current playback position, from the codes in the list below.
HAVE_NOTHING
(numeric value 0)networkState
attribute are set to NETWORK_EMPTY
are always in
the HAVE_NOTHING
state.HAVE_METADATA
(numeric value 1)video
element, the dimensions of the video are also available. The API
will no longer raise an exception when seeking. No media
data is available for the immediate current playback
position.
HAVE_CURRENT_DATA
(numeric value 2)HAVE_METADATA
state, or
there is no more data to obtain in the direction of
playback. For example, in video this corresponds to the user
agent having data from the current frame, but not the next frame;
and to when playback has
ended.HAVE_FUTURE_DATA
(numeric value 3)HAVE_METADATA
state. For example, in video this corresponds to the user agent
having data for at least the current frame and the next frame. The
user agent cannot be in this state if playback has ended, as the current playback
position can never advance in this case.HAVE_ENOUGH_DATA
(numeric value 4)HAVE_FUTURE_DATA
state
are met, and, in addition, the user agent estimates that data is
being fetched at a rate where the current playback
position, if it were to advance at the rate given by the
defaultPlaybackRate
attribute, would not overtake the available data before playback
reaches the end of the media resource.It is possible for the ready state of a media
element to jump between these states discontinuously. For example,
the state of a media element can jump straight from HAVE_METADATA
to HAVE_ENOUGH_DATA
without
passing through the HAVE_CURRENT_DATA
and
HAVE_FUTURE_DATA
states.
The autoplay
attribute is a boolean attribute. When present, the
user agent will automatically begin playback of the
media resource as soon as it can do so without
stopping.
Authors are urged to use the autoplay
attribute rather than
using script to trigger automatic playback, as this allows the user
to override the automatic playback when it is not desired, e.g. when
using a screen reader. Authors are also encouraged to consider not
using the automatic playback behavior at all, and instead to let the
user agent wait for the user to start playback explicitly.
Status: Last call for comments
paused
Returns true if playback is paused; false otherwise.
ended
Returns true if playback has reached the end of the media resource.
defaultPlaybackRate
[ = value ]Returns the default rate of playback, for when the user is not fast-forwarding or reversing through the media resource.
Can be set, to change the default rate of playback.
The default rate has no direct effect on playback, but if the user switches to a fast-forward mode, when they return to the normal playback mode, it is expected that the rate of playback will be returned to the default rate of playback.
playbackRate
[ = value ]Returns the current rate playback, where 1.0 is normal speed.
Can be set, to change the rate of playback.
played
Returns a TimeRanges
object that represents the
ranges of the media resource that the user agent has
played.
play
()Sets the paused
attribute
to false, loading the media resource and beginning
playback if necessary. If the playback had ended, will restart it
from the start.
pause
()Sets the paused
attribute
to true, loading the media resource if necessary.
Status: Last call for comments
seeking
Returns true if the user agent is currently seeking.
seekable
Returns a TimeRanges
object that represents the
ranges of the media resource to which it is possible
for the user agent to seek.
Status: Last call for comments
The controls
attribute is a boolean attribute. If present, it
indicates that the author has not provided a scripted controller and
would like the user agent to provide its own set of controls.
volume
[ = value ]Returns the current playback volume, as a number in the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.
Can be set, to change the volume.
Throws an INDEX_SIZE_ERR
if the new value is not
in the range 0.0 .. 1.0.
muted
[ = value ]Returns true if audio is muted, overriding the volume
attribute, and false if the
volume
attribute is being
honored.
Can be set, to change whether the audio is muted or not.
Status: Last call for comments
Objects implementing the TimeRanges
interface
represent a list of ranges (periods) of time.
interface TimeRanges { readonly attribute unsigned long length; float start(in unsigned long index); float end(in unsigned long index); };
length
Returns the number of ranges in the object.
start
(index)Returns the time for the start of the range with the given index.
Throws an INDEX_SIZE_ERR
if the index is out of range.
end
(index)Returns the time for the end of the range with the given index.
Throws an INDEX_SIZE_ERR
if the index is out of range.
Status: Last call for comments
This section is non-normative.
The following events fire on media elements as part of the processing model described above:
Event name | Interface | Dispatched when... | Preconditions |
---|---|---|---|
loadstart
| Event
| The user agent begins looking for media data, as part of the resource selection algorithm. | networkState equals NETWORK_LOADING
|
progress
| Event
| The user agent is fetching media data. | networkState equals NETWORK_LOADING
|
suspend
| Event
| The user agent is intentionally not currently fetching media data, but does not have the entire media resource downloaded. | networkState equals NETWORK_IDLE
|
abort
| Event
| The user agent stops fetching the media data before it is completely downloaded, but not due to an error. | error is an object with the code MEDIA_ERR_ABORTED .
networkState equals either NETWORK_EMPTY or NETWORK_IDLE , depending on when the download was aborted.
|
error
| Event
| An error occurs while fetching the media data. | error is an object with the code MEDIA_ERR_NETWORK or higher.
networkState equals either NETWORK_EMPTY or NETWORK_IDLE , depending on when the download was aborted.
|
emptied
| Event
| A media element whose networkState was previously not in the NETWORK_EMPTY state has just switched to that state (either because of a fatal error during load that's about to be reported, or because the load() method was invoked while the resource selection algorithm was already running).
| networkState is NETWORK_EMPTY ; all the IDL attributes are in their initial states.
|
stalled
| Event
| The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. | networkState is NETWORK_LOADING .
|
play
| Event
| Playback has begun. Fired after the play() method has returned, or when the autoplay attribute has caused playback to begin.
| paused is newly false.
|
pause
| Event
| Playback has been paused. Fired after the pause() method has returned.
| paused is newly true.
|
loadedmetadata
| Event
| The user agent has just determined the duration and dimensions of the media resource | readyState is newly equal to HAVE_METADATA or greater for the first time.
|
loadeddata
| Event
| The user agent can render the media data at the current playback position for the first time. | readyState newly increased to HAVE_CURRENT_DATA or greater for the first time.
|
waiting
| Event
| Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course. | readyState is newly equal to or less than HAVE_CURRENT_DATA , and paused is false. Either seeking is true, or the current playback position is not contained in any of the ranges in buffered . It is possible for playback to stop for two other reasons without paused being false, but those two reasons do not fire this event: maybe playback ended, or playback stopped due to errors.
|
playing
| Event
| Playback has started. | readyState is newly equal to or greater than HAVE_FUTURE_DATA , paused is false, seeking is false, or the current playback position is contained in one of the ranges in buffered .
|
canplay
| Event
| The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content. | readyState newly increased to HAVE_FUTURE_DATA or greater.
|
canplaythrough
| Event
| The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering. | readyState is newly equal to HAVE_ENOUGH_DATA .
|
seeking
| Event
| The seeking IDL attribute changed to true and the seek operation is taking long enough that the user agent has time to fire the event.
| |
seeked
| Event
| The seeking IDL attribute changed to false.
| |
timeupdate
| Event
| The current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. | |
ended
| Event
| Playback has stopped because the end of the media resource was reached. | currentTime equals the end of the media resource; ended is true.
|
ratechange
| Event
| Either the defaultPlaybackRate or the playbackRate attribute has just been updated.
| |
durationchange
| Event
| The duration attribute has just been updated.
| |
volumechange
| Event
| Either the volume attribute or the muted attribute has changed. Fired after the relevant attribute's setter has returned.
|