video elementcontrols attribute: Interactive content.src attribute: transparent.src attribute: one or more source elements, then, transparent.srcposterautoplaystartloopstartloopendendplaycountcontrolswidthheightinterface HTMLVideoElement : HTMLMediaElement {
attribute unsigned long width;
attribute unsigned long height;
readonly attribute unsigned long videoWidth;
readonly attribute unsigned long videoHeight;
attribute DOMString poster;
};
A video element represents a video or movie.
Content may be provided inside the video
element. User agents should not show this content to the user; 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 browser informing them of how
to access the video contents.
In particular, this content is not fallback content 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) 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, autoplay, start, loopstart, loopend, end, playcount, 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 URL. If the specified resource is
to be used, it must be fetched when the
element is created or when the poster attribute is set. The
poster frame is then the image obtained from that
resource, if any.
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.
The poster DOM
attribute must reflect the poster content attribute.
When no video data is available (the element's networkState attribute is
either EMPTY, LOADING, or LOADED_METADATA),
video elements represent either the poster
frame, or nothing.
When a video element is paused and the current playback position is the first
frame of video, the element represents either the frame of video
corresponding to the current
playback position or the poster frame, at the
discretion of the user agent.
Notwithstanding the above, the poster frame should be preferred over nothing, but the poster frame should not be shown again after a frame of video has been shown.
When a video element is paused at any other position, the
element represents the frame of video corresponding to the current playback position,
or, if that is not yet available (e.g. because the video is seeking
or buffering), the last frame of the video to have been
rendered.
When a video element is actively
playing, it represents the frame of video at the continuously
increasing "current"
position. When the current playback position
changes such that the last frame rendered is no longer the frame
corresponding to the current playback position in the
video, the new frame must be rendered. Similarly, any audio
associated with the video must, if played, be played synchronized
with the current playback position, at the specified
volume with the specified
mute state.
When a video element is neither actively
playing nor paused
(e.g. when seeking or stalled), the element represents the last
frame of the video to have been rendered.
Which frame in a video stream corresponds to a particular playback position is defined by the video stream's format.
In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.
The intrinsic width and height of the video are the aspect-ratio corrected dimensions given by the video data itself: the intrinsic width is the number of pixels per line of the video data multiplied by the pixel ratio given by the resource, multiplied by the resolution of the resource; the intrinsic height is the number of pixels per column of the video data multiplied by the resolution of the resource. The resolution of the resource is the physical distance intended for each pixel of video data, and assumes square pixels, with the resource's pixel ratio then adjusting the width of the pixels to the actual aspect-ratio-corrected width. In the absence of resolution information defining the mapping of pixels in the video to physical dimensions, user agents should assume that one pixel in the video corresponds to one CSS pixel. The pixel ratio of the resource is the corrected aspect ratio of the video divided by the ratio of the number of pixels per line to the number of pixels per column. In the absence of pixel ratio information in the resource, user agents should assume a default of 1.0 (square pixels).
The videoWidth DOM
attribute must return the intrinsic width of the
video in CSS pixels. The videoHeight DOM
attribute must return the intrinsic height of
the video in CSS pixels. If no video data is available, then the
attributes must return 0.
If the video's pixel ratio override's is none, then the video's adjusted width is the same as the video's intrinsic width. If the video has a pixel ratio override other than none, then the adjusted width of the video is the number of pixels per line of the video data multiplied by the video's pixel ratio override, multiplied by the resolution of the resource; the pixel ratio of the resource is thus ignored.
The video's adjusted height is the same as the video's intrinsic height.
The adjusted aspect ratio of a video is the ratio of its adjusted width to its adjusted height.
User agents may adjust the adjusted width and height of the video to ensure that each pixel of video data corresponds to at least one device pixel, so long as this doesn't affect the adjusted aspect ratio (this is especially relevant for pixel ratios that are less than 1.0).
The video element supports dimension
attributes.
Video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's adjusted aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the adjusted aspect ratio of the video, the video will be shown letterboxed. Areas of the element's playback area that do not contain the video represent nothing.
The intrinsic width of a video element's playback
area is the adjusted
width of the video resource, if that is available; otherwise
it is the intrinsic width of the poster frame, if that
is available; otherwise it is 300 CSS pixels.
The intrinsic height of a video element's playback
area is the intrinsic
height of the video resource, if that is available; otherwise
it is the intrinsic height of the poster frame, if that
is available; otherwise it is 150 CSS pixels.
The poster frame is not affected by the pixel ratio conversions.
User agents should provide controls to enable or disable the display of closed captions associated with the video stream, though such features should, again, not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners
more suitable to the user (e.g. full-screen or in an independent
resizable window). As for the other user interface features,
controls to enable this should not interfere with the page's normal
rendering unless the user agent is exposing a user interface. In such an
independent context, however, user agents may make full user
interfaces visible, with, e.g., play, pause, seeking, and volume
controls, even if the controls attribute is absent.
User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.
User agents should not provide a public API to cause videos to be shown full-screen. A script, combined with a carefully crafted video file, could trick the user into thinking a system-modal dialog had been shown, and prompt the user for a password. There is also the danger of "mere" annoyance, with pages launching full-screen videos when links are clicked or pages navigated. Instead, user-agent specific interface features may be provided to easily allow the user to obtain a full-screen playback mode.
The spec does not currently define the interaction of the "controls" attribute with the "height" and "width" attributes. This will likely be defined in the rendering section based on implementation experience. So far, browsers seem to be making the controls overlay-only, thus somewhat sidestepping the issue.
video elementsUser agents may support any video and audio codecs and container formats.
It would be helpful for interoperability if all browsers could support the same codecs. However, there are no known codecs that satisfy all the current players: we need a codec that is known to not require per-unit or per-distributor licensing, that is compatible with the open source development model, that is of sufficient quality as to be usable, and that is not an additional submarine patent risk for large companies. This is an ongoing issue and this section will be updated once more information is available.
Certain user agents might support no codecs at all, e.g. text browsers running over SSH connections.
audio elementcontrols attribute: Interactive content.src attribute: transparent.src attribute: one or more source elements, then, transparent.srcautoplaystartloopstartloopendendplaycountcontrols[NamedConstructor=Audio(),
NamedConstructor=Audio(in DOMString url)]
interface HTMLAudioElement : HTMLMediaElement {
// no members
};
An audio element represents a sound or audio
stream.
Content may be provided inside the audio
element. User agents should not show this content to the user; 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 browser informing them of how
to access the audio contents.
In particular, this content is not fallback content 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, autoplay, start, loopstart, loopend, end, playcount, and controls attributes are the attributes common to all media
elements.
When an audio element is actively
playing, it must have its audio data played synchronized with
the current playback position, at the specified volume with the specified mute state.
When an audio element is not actively
playing, audio must not play for the element.
Two constructors are provided for creating
HTMLAudioElement objects (in addition to the factory
methods from DOM Core such as createElement()): Audio() and Audio(url). When invoked as constructors,
these must return a new HTMLAudioElement object (a new
audio element). If the src argument
is present, the object created must have its src content attribute set to the
provided value, and the user agent must invoke the load() method on the object before
returning.
audio elementsUser agents may support any audio codecs and container formats.
User agents must support the WAVE container format with audio encoded using the PCM format.
source elementsrctypemediapixelratiointerface HTMLSourceElement : HTMLElement {
attribute DOMString src;
attribute DOMString type;
attribute DOMString media;
attribute float pixelRatio;
};
The source element allows authors to specify
multiple media resources for
media elements.
The src attribute
gives the address of the media resource. The value must
be a valid URL. 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. Its value must be a MIME
type. The codecs parameter may be specified
and might be necessary to specify exactly how the resource is
encoded. [RFC2046] [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. [MQ]
Either the type attribute,
the media attribute or both,
must be specified, unless this is the last source
element child of the parent element.
The pixelratio
attribute allows the author to specify the pixel ratio of anamorphic
media resources that do not
self-describe their pixel
ratio. The attribute value, if specified, must be a
valid floating point number giving the ratio of the
correct rendered width of each pixel to the actual height of each
pixel in the image. The default value, if the attribute is omitted
or cannot be parsed, is 1.0.
The only way this default is used is in deciding
what number the pixelRatio DOM attribute will
return if the content attribute is omitted or cannot be parsed. If
the content attribute is omitted or cannot be parsed, then the user
agent doesn't adjust the intrinsic width of the
video at all; the intrinsic dimensions and the pixel ratio of the video
are honoured.
If a source element is inserted into a media
element that is already in a document and whose networkState is in the EMPTY state, the user agent must
queue a task that implicitly invokes the load() method on the media
element, and ignores any resulting exceptions. The task
source for this task is the media element's own
media element new resource task source.
The DOM attributes src, type, and media must
reflect the respective content attributes of the same
name.
The DOM attribute pixelRatio must
reflect the pixelratio content
attribute.
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 EMPTY = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED_METADATA = 2;
const unsigned short LOADED_FIRST_FRAME = 3;
const unsigned short LOADED = 4;
readonly attribute unsigned short networkState;
readonly attribute float bufferingRate;
readonly attribute boolean bufferingThrottled;
readonly attribute TimeRanges buffered;
readonly attribute ByteRanges bufferedBytes;
readonly attribute unsigned long totalBytes;
void load();
// ready state
const unsigned short DATA_UNAVAILABLE = 0;
const unsigned short CAN_SHOW_CURRENT_FRAME = 1;
const unsigned short CAN_PLAY = 2;
const unsigned short CAN_PLAY_THROUGH = 3;
readonly attribute unsigned short readyState;
readonly attribute boolean seeking;
// playback state
attribute float currentTime;
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;
void play();
void pause();
// looping
attribute float start;
attribute float end;
attribute float loopStart;
attribute float loopEnd;
attribute unsigned long playCount;
attribute unsigned long currentLoop;
// cue ranges
void addCueRange(in DOMString className, in DOMString id, in float start, in float end, in boolean pauseOnExit, in CueRangeCallback enterCallback, in CueRangeCallback exitCallback);
void removeCueRanges(in DOMString className);
// controls
attribute boolean controls;
attribute float volume;
attribute boolean muted;
};
The media element attributes, src, autoplay, start, loopstart, loopend, end, playcount, 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.
Media elements use two task queues, the media element event task source for asynchronous events and callbacks, and the media element new resource task source for handling implicit loads. Unless otherwise specified, the task source for all the tasks queued in this section and its subsections is the media element event task source.
All media elements have an
associated error status, which records the last error the element
encountered since the load()
method was last invoked. The error attribute, on
getting, must return the MediaError object created for
this last error, or null if there has not been an error.
interface MediaError {
const unsigned short MEDIA_ERR_ABORTED = 1;
const unsigned short MEDIA_ERR_NETWORK = 2;
const unsigned short MEDIA_ERR_DECODE = 3;
readonly attribute unsigned short code;
};
The code
attribute of a MediaError object must return the code
for the error, which must be one of the following:
MEDIA_ERR_ABORTED (numeric value 1)MEDIA_ERR_NETWORK (numeric value 2)MEDIA_ERR_DECODE (numeric value 3)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 URL.
If the src attribute of a
media element that is already in a document and whose
networkState is in the
EMPTY state is added, changed,
or removed, the user agent must queue a task that
implicitly invokes the load()
method on the media element, and ignores any resulting
exceptions. The task source for this task is the
media element's own media element new resource
task source.
If a src
attribute is specified, the resource it specifies is the media
resource that will be used. Otherwise, the resource specified
by the first suitable source element child of the
media element is the one used.
The src DOM
attribute on media elements must
reflect the respective content attribute of the same
name.
To pick a media resource for a media element, a user agent must use the following steps:
Let the chosen resource's pixel ratio override be none.
If the media element has a src attribute, then resolve the URL given in
that attribute. If that is successful, then the resulting
absolute URL is the address of the media
resource; jump to the last step.
Otherwise, let candidate be the first
source element child in the media
element, or null if there is no such child.
Loop: this is the start of the loop that looks at the
source elements.
If candidate is not null and it has a
pixelratio attribute,
and the result of applying the rules for parsing floating
point number values to the value of that attribute is not an
error, then let the chosen resource's pixel ratio
override be that result; otherwise, reset it back to
none.
If either:
src attribute, orsrc attribute
fails, ortype attribute and that
attribute's value, when parsed as a MIME type, does not represent
a type that the user agent can render (including any codecs
described by the codec parameter), or [RFC2046] [RFC4281]media attribute and that
attribute's value, when processed according to the rules for media queries, does not match the current
environment, [MQ]...then the candidate is not suitable; go to the next step.
Otherwise, the result of resolving the URL given in that candidate element's src attribute is the address of the
media resource; jump to the last step.
Let candidate be the next
source element child in the media
element, or null if there are no more such
children.
If candidate is not null, return to the step labeled loop.
There is no media resource. Abort these steps.
Let the address of the chosen media resource be the absolute URL that was found before jumping to this step, and let its pixel ratio override be the value of the chosen resource's pixel ratio override.
The currentSrc DOM
attribute must return the empty string if the media
element's networkState has the value
EMPTY, and the absolute
URL that is the address of the chosen media
resource otherwise.
As media elements interact
with the network, they go through several states. The networkState
attribute, on getting, must return the current network state of the
element, which must be one of the following values:
EMPTY (numeric value 0)LOADING (numeric value 1)currentSrc attribute), but none
of the metadata has yet been obtained and therefore all the other
attributes are still in their initial states.LOADED_METADATA (numeric value 2)LOADED_FIRST_FRAME (numeric value 3)LOADED (numeric value 4)The algorithm for the load()
method defined below describes exactly when the networkState attribute changes
value.
All media elements have a begun flag, which must begin in the false state, a loaded-first-frame flag, which must begin in the false state, and an autoplaying flag, which must begin in the true state.
When the load()
method on a media element is invoked, the user agent
must run the following steps. Note that this algorithm might get
aborted, e.g. if the load()
method itself is invoked again.
If there are any tasks from the media element's media element new resource task source or its media element event task source in one of the task queues, then remove those tasks.
Basically, pending events, callbacks, and loads for the media element are discarded when the media element starts loading a new resource.
Any already-running instance of this algorithm for this element must be aborted. If those method calls have not yet returned, they must finish the step they are on, and then immediately return. This is not blocking; this algorithm must not wait for the earlier instances to abort before continuing.
If the element's begun flag is true, then the
begun flag must be set to false, the error attribute must be set to a new
MediaError object whose code attribute is set to MEDIA_ERR_ABORTED,
and the user agent must synchronously fire a progress
event called abort at the
media element.
The error attribute
must be set to null, the loaded-first-frame flag must
be set to false, and the autoplaying flag must be set
to true.
The playbackRate
attribute must be set to the value of the defaultPlaybackRate
attribute.
If the media element's networkState is not set to
EMPTY, then the following
substeps must be followed:
networkState
attribute must be set to EMPTY.readyState is
not set to DATA_UNAVAILABLE, it must be set
to that state.paused attribute
is false, it must be set to true.seeking is true, it
must be set to false.currentLoop DOM
attribute must be set to 0.emptied at
the media element.The user agent must pick a media resource for
the media element. If that fails, the method must
raise an INVALID_STATE_ERR exception, and abort these
steps.
The networkState
attribute must be set to LOADING.
The currentSrc attribute starts
returning the new value.
The user agent must then set the begun flag to
true and synchronously fire a progress event called
loadstart at the media
element.
The method must return, but these steps must continue.
Playback of any previously playing media resource for this element stops.
If a fetching process is in progress for the media element, the user agent should stop it.
The user agent must then begin to fetch the chosen media resource. The rate of the download may be throttled, however, in response to user preferences (including throttling it to zero until the user indicates that the download can start), or to balance the download with other connections sharing the same bandwidth.
While the fetching process is progressing, the user agent must
queue a task to fire a progress event
called progress at the element
every 350ms (±200ms) or for every byte received, whichever is
least frequent.
If at any point the user agent has received no data for more
than about three seconds, the user agent must queue a
task to fire a progress event called stalled at the element.
User agents may allow users to selectively block or slow media data downloads. When a media element's download has been blocked, the user agent must act as if it was stalled (as opposed to acting as if the connection was closed).
The user agent may use whatever means necessary to fetch the resource (within the constraints put forward by this and other specifications); for example, reconnecting to the server in the face of network errors, using HTTP partial range requests, or switching to a streaming protocol. The user agent must consider a resource erroneous only if it has given up trying to fetch it.
The networking task source tasks to process the data as it is being fetched must, when appropriate, include the relevant substeps from the following list:
DNS errors and HTTP 4xx and 5xx errors (and equivalents in other protocols) must cause the user agent to execute the following steps. User agents may also follow these steps in response to other network errors of similar severity.
error attribute
must be set to a new MediaError object whose code attribute is set to
MEDIA_ERR_NETWORK.error at the media
element.networkState attribute
must be switched to the EMPTY value and the user agent
must queue a task to fire a simple
event called emptied
at the element.The server returning a file of the wrong kind (e.g. one that
that turns out to not be pure audio when the media
element is an audio element), or the file
using unsupported codecs for all the data, must cause the user
agent to execute the following steps. User agents may also
execute these steps in response to other codec-related fatal
errors, such as the file requiring more resources to process
than the user agent can provide in real time.
error attribute
must be set to a new MediaError object whose code attribute is set to
MEDIA_ERR_DECODE.error at the media
element.networkState attribute
must be switched to the EMPTY value and the user agent
must queue a task to fire a simple
event called emptied
at the element.The fetching process is aborted by the user, e.g. because the
user navigated the browsing context to another page, the user
agent must execute the following steps. These steps are not
followed if the load()
method itself is reinvoked, as the steps above handle that
particular kind of abort.
error attribute
must be set to a new MediaError object whose code attribute is set to
MEDIA_ERR_ABORT.abort at the media
element.networkState attribute
has the value LOADING,
the element's networkState attribute
must be switched to the EMPTY value and the user agent
must queue a task to fire a simple
event called emptied
at the element. (If the networkState attribute
has a value greater than LOADING, then this doesn't
happen; the available data, if any, will be playable.)The server returning data that is partially usable but cannot be optimally rendered must cause the user agent to execute the following steps.
The user agent must follow these substeps:
The current playback position must be set to the effective start.
The networkState attribute
must be set to LOADED_METADATA.
A number of attributes, including duration, buffered, and played, become
available.
The user agent will queue a task to
fire a simple event called durationchange at the
element at this point.
The user agent must queue a task to
fire a simple event called loadedmetadata at the
element.
The user agent must follow these substeps:
The networkState attribute
must be set to LOADED_FIRST_FRAME.
The readyState attribute must
change to CAN_SHOW_CURRENT_FRAME.
The loaded-first-frame flag must be set to true.
The user agent must queue a task to
fire a simple event called loadedfirstframe at the
element.
The user agent must queue a task to
fire a simple event called canshowcurrentframe at
the element.
When the user agent has completely fetched of the entire media resource, it must move on to the next step.
If the fetching process completes without errors, the
begun flag must be set to false, the networkState attribute must
be set to LOADED, and the
user agent must queue a task to fire a progress
event called load at the
element.
If a media element whose networkState has the value
EMPTY is inserted into a document, the user
agent must queue a task that implicitly invokes the
load() method on the media
element, and ignores any resulting exceptions. The task
source for this task is the media element's own
media element new resource task source.
The bufferingRate
attribute must return the average number of bits received per second
for the current download over the past few seconds. If there is no
download in progress, the attribute must return 0.
The bufferingThrottled
attribute must return true if the user agent is intentionally
throttling the bandwidth used by the download (including when
throttling to zero to pause the download altogether), and false
otherwise.
The buffered
attribute must return a static normalized
TimeRanges object that represents the ranges of
the media resource, if any, that the user agent has
buffered, at the time the attribute is evaluated.
Typically this will be a single range anchored at the zero point, but if, e.g. the user agent uses HTTP range requests in response to seeking, then there could be multiple ranges.
The bufferedBytes
attribute must return a static normalized
ByteRanges object that represents the ranges of
the media resource, if any, that the user agent has
buffered, at the time the attribute is evaluated.
The totalBytes attribute
must return the length of the media resource, in bytes,
if it is known and finite. If it is not known, is infinite
(e.g. streaming radio), or if no media data is
available, the attribute must return 0.
User agents may discard previously buffered data.
Thus, a time or byte position included within a
range of the objects return by the buffered or bufferedBytes attributes at
one time can end up being not included in the range(s) of objects
returned by the same attributes at a later time.
The duration
attribute must return the length of the media resource,
in seconds. If no media data is available, then the
attributes must return 0. If media data is available
but the length is not known, the attribute must return the
Not-a-Number (NaN) value. If the media resource is
known to be unbounded (e.g. a streaming radio), then the attribute
must return the positive Infinity value.
When the length of the media
resource changes (e.g. from being unknown to known, or from
indeterminate to known, or from a previously established length to a
new length) the user agent must queue a task to
fire a simple event called durationchange at the
media element.
Media elements have a current playback position, which must initially be zero. The current position is a time.
The currentTime
attribute must, on getting, return the current playback
position, expressed in seconds. On setting, the user agent
must seek to the new value
(which might raise an exception).
The start
content attribute gives the offset into the media
resource at which playback is to begin. The default value is
the default start position of the media resource, or 0
if not enough media data has been obtained yet to
determine the default start position or if the resource doesn't
specify a default start position.
The effective start is the smaller of the
start DOM attribute and the end
of the media resource.
The loopstart content
attribute gives the offset into the media resource at
which playback is to begin when looping a clip. The default value of
the loopstart content
attribute is the value of the start DOM attribute.
The effective loop start is the smaller of
the loopStart DOM attribute
and the end of the media resource.
The loopend
content attribute gives an offset into the media
resource at which playback is to jump back to the loopstart, when looping the
clip. The default value of the loopend content attribute is the
value of the end DOM
attribute.
The effective loop end is the greater of
the start, loopStart, and loopEnd DOM attributes, except if
that is greater than the end of the media resource, in
which case that's its value.
The end content
attribute gives an offset into the media resource at
which playback is to end. The default value is infinity.
The effective end is the greater of the
start, loopStart, and end DOM attributes, except if that
is greater than the end of the media resource, in which
case that's its value.
The start, loopstart, loopend, and end attributes must, if specified,
contain value time
offsets. To get the time values they represent, user agents
must use the rules for parsing time offsets.
The start, loopStart, loopEnd, and end DOM attributes must
reflect the start, loopstart, loopend, and end content attributes on the
media element respectively.
The playcount content
attribute gives the number of times to play the clip. The default
value is 1.
The playCount
DOM attribute must reflect the playcount content attribute on
the media element. The value must be limited to
only positive non-zero numbers.
The currentLoop
attribute must initially have the value 0. It gives the index of the
current loop. It is changed during playback as described below.
When any of the start, loopStart, loopEnd, end, playCount, and currentLoop DOM attributes
change value (either through content attribute mutations reflecting
into the DOM attribute, if applicable, or through direct mutations
of the DOM attribute), the user agent must apply the following
steps:
If the playCount
DOM attribute's value is less than or equal to the currentLoop DOM attribute's
value, then the currentLoop DOM attribute's
value must be set to playCount-1 (which will
make the current loop the last loop).
If the media element's networkState is in the EMPTY state or the LOADING state, then the user agent
must at this point abort these steps.
If the currentLoop is zero, and the
current playback position is before the effective
start, the user agent must seek to the effective
start.
If the currentLoop is greater than
zero, and the current playback position is before the
effective loop start, the user agent must seek to the effective loop
start.
If the currentLoop is less than
playCount-1,
and the current playback position is after the
effective loop end, the user agent must seek to the effective loop
start, and increase currentLoop by 1.
If the currentLoop is equal to
playCount-1,
and the current playback position is after the
effective end, the user agent must seek to the effective end
and then the looping will end.
Media elements have a ready state, which describes to what degree they are ready to be rendered at the current playback position. The possible values are as follows; the ready state of a media element at any particular time is the greatest value describing the state of the element:
DATA_UNAVAILABLE (numeric value 0)networkState attribute
is less than LOADED_FIRST_FRAME
are always in the DATA_UNAVAILABLE
state.CAN_SHOW_CURRENT_FRAME (numeric value 1)DATA_UNAVAILABLE state. In video,
this corresponds to the user agent having data from the current
frame, but not the next frame. In audio, this corresponds to the
user agent only having audio up to the current playback
position, but no further.CAN_PLAY (numeric value 2)DATA_UNAVAILABLE state. In video,
this corresponds to the user agent having data for the current
frame and the next frame. In audio, this corresponds to the user
agent having data beyond the current playback
position.CAN_PLAY_THROUGH (numeric value 3)DATA_UNAVAILABLE state,
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 effective end of the media
resource on the last loop.When the ready state of a media element whose networkState is not EMPTY changes, the user agent must
follow the steps given below:
DATA_UNAVAILABLEThe user agent must fire a simple event called
dataunavailable at the
element.
CAN_SHOW_CURRENT_FRAMEIf the element's loaded-first-frame flag is true,
the user agent must fire a simple event called canshowcurrentframe
event.
The first time the networkState attribute
switches to this value, the loaded-first-frame flag
is false, and the event is fired by the algorithm described
above for the load()
method, in conjunction with other steps.
CAN_PLAYThe user agent must fire a simple event called
canplay.
CAN_PLAY_THROUGHThe user agent must fire a simple event called
canplaythrough event. If
the autoplaying flag is true, and the paused attribute is true, and the
media element has an autoplay attribute specified,
then the user agent must also set the paused attribute to false and
fire a simple event called play.
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 whose loaded-first-frame
flag is false can jump straight from DATA_UNAVAILABLE to CAN_PLAY_THROUGH without
passing through the CAN_SHOW_CURRENT_FRAME
and CAN_PLAY states, and
thus without firing the canshowcurrentframe and
canplay events. The only state
that is guaranteed to be reached is the CAN_SHOW_CURRENT_FRAME
state, which is reached as part of the load() method's processing.
The readyState DOM
attribute must, on getting, return the value described above that
describes the current ready state of the media
element.
The autoplay
attribute is a boolean attribute. When present, the
algorithm described herein will cause the user agent to
automatically begin playback of the media resource as
soon as it can do so without stopping.
The autoplay
DOM attribute must reflect the content attribute of the
same name.
The paused
attribute represents whether the media element is
paused or not. The attribute must initially be true.
A media element is said to be actively
playing when its paused
attribute is false, the readyState attribute is either
CAN_PLAY or CAN_PLAY_THROUGH, the
element has not ended playback, playback has not
stopped due to errors, and the element has not
paused for user interaction.
A media element is said to have ended
playback when the element's networkState attribute is
LOADED_METADATA or
greater, the current playback position is equal to the
effective end of the media resource, and the
currentLoop attribute is
equal to playCount-1.
A media element is said to have stopped due to
errors when the element's networkState attribute is
LOADED_METADATA or
greater, and the user agent encounters a non-fatal error
during the processing of the media data, and due to
that error, is not able to play the content at the current
playback position.
A media element is said to have paused for user
interaction when its paused attribute is false, the readyState attribute is either
CAN_PLAY or CAN_PLAY_THROUGH and the
user agent has reached a point in the media resource
where the user has to make a selection for the resource to
continue.
It is possible for a media element to have both ended playback and paused for user interaction at the same time.
When a media element is
actively playing and its owner Document is an active document, its current
playback position must increase monotonically at playbackRate units of media
time per unit time of wall clock time. If this value is not 1, the
user agent may apply pitch adjustments to any audio component of the
media resource.
This specification doesn't define how the user agent achieves the appropriate playback rate — depending on the protocol and media available, it is plausible that the user agent could negotiate with the server to have the server provide the media data at the appropriate rate, so that (except for the period between when the rate is changed and when the server updates the stream's playback rate) the client doesn't actually have to drop or interpolate any frames.
Media resources might be internally scripted or interactive. Thus, a media element could play in a non-linear fashion. If this happens, the user agent must act as if the algorithm for seeking was used whenever the current playback position changes in a discontinuous fashion (so that the relevant events fire).
When a media element
that is actively playing stops playing because its
readyState attribute
changes to a value lower than CAN_PLAY, without the element
having ended playback, or playback having stopped
due to errors, or playback having paused for user
interaction, or the seeking
algorithm being invoked, the user agent must queue a
task to fire a simple event called timeupdate at the element, and
queue a task to fire a simple event called
waiting at the element.
When a media element that is actively
playing stops playing because it has paused for user
interaction, the user agent must queue a task to
fire a simple event called timeupdate at the element.
When currentLoop is
less than playCount-1 and the
current playback position reaches the effective
loop end, then the user agent must increase currentLoop by 1 and seek to the effective loop
start.
When currentLoop is
equal to the playCount-1 and the
current playback position reaches the effective
end, then the user agent must follow these steps:
The user agent must stop playback.
The ended
attribute becomes true.
The user agent must queue a task to fire
a simple event called timeupdate at the element.
The user agent must queue a task to fire
a simple event called ended
at the element.
The defaultPlaybackRate
attribute gives the desired speed at which the media
resource is to play, as a multiple of its intrinsic
speed. The attribute is mutable, but on setting, if the new value is
0.0, a NOT_SUPPORTED_ERR exception must be raised
instead of the value being changed. It must initially have the value
1.0.
The playbackRate
attribute gives the speed at which the media resource
plays, as a multiple of its intrinsic speed. If it is not equal to
the defaultPlaybackRate,
then the implication is that the user is using a feature such as
fast forward or slow motion playback. The attribute is mutable, but
on setting, if the new value is 0.0, a
NOT_SUPPORTED_ERR exception must be raised instead of
the value being changed. Otherwise, the playback must change speed
(if the element is actively playing). It must initially
have the value 1.0.
When the defaultPlaybackRate or
playbackRate attributes
change value (either by being set by script or by being changed
directly by the user agent, e.g. in response to user control) the
user agent must queue a task to fire a simple
event called ratechange
at the media element.
When the play()
method on a media element is invoked, the user agent
must run the following steps.
If the media element's networkState attribute has
the value EMPTY, then the user
agent must invoke the load()
method and wait for it to return. If that raises an exception, that
exception must be reraised by the play() method.
If the playback has ended,
then the user agent must set currentLoop to zero and seek to the effective
start.
If this involved a seek, the user agent will queue a task to
fire a simple event called timeupdate at the media
element.
The playbackRate
attribute must be set to the value of the defaultPlaybackRate
attribute.
If this caused the playbackRate attribute to
change value, the user agent will
queue a task to fire a simple event
called ratechange at the
media element.
If the media element's paused attribute is true, it must
be set to false.
The media element's autoplaying flag must be set to false.
The method must then return.
If the fourth step above changed the value of paused, the user agent must
queue a task to fire a simple event
called play at the
element.
When the pause()
method is invoked, the user agent must run the following steps:
If the media element's networkState attribute has
the value EMPTY, then the user
agent must invoke the load()
method and wait for it to return. If that raises an exception, that
exception must be reraised by the pause() method.
If the media element's paused attribute is false, it must
be set to true.
The media element's autoplaying flag must be set to false.
The method must then return.
If the second step above changed the value of paused, then the user agent must
queue a task to fire a simple event
called timeupdate at the
element, and queue a task to fire a simple
event called pause at the
element.
When a media element is removed from a
Document, if the
media element's networkState attribute has a
value other than EMPTY then the
user agent must act as if the pause() method had been invoked.
Media elements that are
actively playing while not in a
Document must not play any
video, but should play any audio component. Media elements must not
stop playing just because all references to them have been removed;
only once a media element to which no references exist has reached a
point where no further audio remains to be played for that element
(e.g. because the element is paused or because the end of the clip
has been reached) may the element be garbage
collected.
If the media element's ownerDocument stops being an active
document, then the playback will stop
until the document is active again.
The ended
attribute must return true if the media element has
ended playback, and false otherwise.
The played
attribute must return a static normalized
TimeRanges object that represents the ranges of
the media resource, if any, that the user agent has so
far rendered, at the time the attribute is evaluated.
The seeking
attribute must initially have the value false.
When the user agent is required to seek to a particular new playback position in the media resource, it means that the user agent must run the following steps:
If the media element's networkState is less than
LOADED_METADATA,
then the user agent must raise an INVALID_STATE_ERR
exception (if the seek was in response to a DOM method call or
setting of a DOM attribute), and abort these steps.
If currentLoop is
0, let min be the effective
start. Otherwise, let it be the effective loop
start.
If currentLoop is
equal to playCount-1, let max be the effective end. Otherwise, let
it be the effective loop end.
If the new playback position is more than max, let it be max.
If the new playback position is less than min, let it be min.
If the (possibly now changed) new playback
position is not in one of the ranges given in the seekable attribute, then the user
agent must raise an INDEX_SIZE_ERR exception (if the
seek was in response to a DOM method call or setting of a DOM
attribute), and abort these steps.
The current playback position must be set to the given new playback position.
The seeking DOM
attribute must be set to true.
The user agent must queue a
task to fire a simple event called timeupdate at the element.
If the media element was actively
playing immediately before it started seeking, but seeking
caused its readyState
attribute to change to a value lower than CAN_PLAY, the user agent must
queue a task to fire a simple event
called waiting at the
element.
If, when it reaches this step, the user agent has still not
established whether or not the media data for the new playback position is available, and, if it is,
decoded enough data to play back that position, the user agent must
queue a task to fire a simple event
called seeking at the
element.
If the seek was in response to a DOM method call or setting of a DOM attribute, then continue the script. The remainder of these steps must be run asynchronously.
The user agent must wait until it has established whether or not the media data for the new playback position is available, and, if it is, until it has decoded enough data to play back that position.
The seeking DOM
attribute must be set to false.
The user agent must queue a task to fire
a simple event called seeked at the element.
The seekable
attribute must return a static normalized
TimeRanges object that represents the ranges of
the media resource, if any, that the user agent is able
to seek to, at the time the attribute is evaluated, notwithstanding
the looping attributes (i.e. the effective start and
effective end, etc, don't affect the seekable attribute).
If the user agent can seek to anywhere in the
media resource, e.g. because it a simple movie file and
the user agent and the server support HTTP Range requests, then the
attribute would return an object with one range, whose start is the
time of the first frame (typically zero), and whose end is the same
as the time of the first frame plus the duration attribute's value (which
would equal the time of the last frame).
Media elements have a set of cue ranges. Each cue range is made up of the following information:
The addCueRange(className, id, start, end, pauseOnExit, enterCallback, exitCallback) method must, when called,
add a cue range to the media element, that
cue range having the class name className, the
identifier id, the start time start (in seconds), the end time end (in seconds), the "pause" boolean with the same
value as pauseOnExit, the "enter" callback enterCallback, the "exit" callback exitCallback, and an "active" boolean that is true if
the current playback position is equal to or greater
than the start time and less than the end time, and false
otherwise.
The removeCueRanges(className) method must, when called,
remove all the cue ranges of the
media element which have the class name className.
When the current playback position of a media element changes (e.g. due to playback or seeking), the user agent must run the following steps. If the current playback position changes while the steps are running, then the user agent must wait for the steps to complete, and then must immediately rerun the steps. (These steps are thus run as often as possible or needed — if one iteration takes a long time, this can cause certain ranges to be skipped over as the user agent rushes ahead to "catch up".)
Let current ranges be an ordered list of cue ranges, initialized to contain all the cue ranges of the media element whose start times are less than or equal to the current playback position and whose end times are greater than the current playback position, in the order they were added to the element.
Let other ranges be an ordered list of cue ranges, initialized to contain all the cue ranges of the media element that are not present in current ranges, in the order they were added to the element.
If none of the cue ranges in current ranges have their "active" boolean set to "false" (inactive) and none of the cue ranges in other ranges