Error codes

media . error

Returns a MediaError object representing the current error state of the element.

Returns null if there is no error.

All media elements have an associated error status, which records the last error the element encountered since its resource selection algorithm 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;
  const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
  readonly attribute unsigned short code;
};

media . error . code

Returns the current error's error code, from the list below.

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)

The fetching process for the media resource was aborted by the user agent at the user's request.

MEDIA_ERR_NETWORK (numeric value 2)

A network error of some description caused the user agent to stop fetching the media resource, after the resource was established to be usable.

MEDIA_ERR_DECODE (numeric value 3)

An error of some description occurred while decoding the media resource, after the resource was established to be usable.

MEDIA_ERR_SRC_NOT_SUPPORTED (numeric value 4)

The media resource indicated by the src attribute or assigned media provider object was not suitable.

Location of the media resource

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.

If the itemprop attribute is specified on the media element, then the src attribute must also be specified.

The crossorigin content attribute on media elements is a CORS settings attribute.

If a media element is created with a src attribute, the user agent must immediately invoke the media element's resource selection algorithm.

If a src attribute of a media element is set or changed, the user agent must invoke the media element's media element load algorithm. (Removing the src attribute does not do this, even if there are source elements present.)

The src IDL attribute on media elements must reflect the content attribute of the same name.

The crossOrigin IDL attribute must reflect the crossorigin content attribute.

A media provider object is an object that can represent a media resource, separate from a URL. MediaStream objects, MediaSource objects, Blob objects, and File objects are all media provider objects.

Each media element can have an assigned media provider object, which is a media provider object. When a media element is created, it has no assigned media provider object.

media . srcObject [ = source ]

Allows the media element to be assigned a media provider object.

media . currentSrc

Returns the address of the current media resource, if any.

Returns the empty string when there is no media resource, or it doesn't have an address.

The currentSrc IDL attribute must initially be set to the empty string. Its value is changed by the resource selection algorithm defined below.

The srcObject IDL attribute, on getting, must return the element's assigned media provider object, if any, or null otherwise. On setting, it must set the element's assigned media provider object to the new value, and then invoke the element's media element load algorithm.

There are three ways to specify a media resource: the srcObject IDL attribute, the src content attribute, and source elements. The IDL attribute takes priority, followed by the content attribute, followed by the elements.

MIME types

A media resource can be described in terms of its type, specifically a MIME type, in some cases with a codecs parameter. (Whether the codecs parameter is allowed or not depends on the MIME type.) [[!RFC6381]]

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 recognise 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.

Only the MIME type "application/octet-stream" with no parameters is special-cased here; if any parameter appears with it, it will be treated just like any other MIME type. This is a deviation from the rule that unknown MIME type parameters should be ignored.

media . 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.

The canPlayType(type) method must return the empty string if type is a type that the user agent knows it cannot render or is the type "application/octet-stream"; it must return "probably" if the user agent is confident that the type represents a media resource that it can render if used in with this audio or video element; and it must return "maybe" otherwise. Implementors are encouraged to return "maybe" unless the type can be confidently established as being supported or not. Generally, a user agent should never return "probably" for a type that allows the codecs parameter if that parameter is not present.

<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 Plugin" 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.

Network states

media . networkState

Returns the current state of network activity for the element, from the codes in the list below.

As media elements interact with the network, their current network activity is represented by the networkState attribute. On getting, it must return the current network state of the element, which must be one of the following values:

NETWORK_EMPTY (numeric value 0)

The element has not yet been initialised. All attributes are in their initial states.

NETWORK_IDLE (numeric value 1)

The element's resource selection algorithm is active and has selected a resource, but it is not actually using the network at this time.

NETWORK_LOADING (numeric value 2)

The user agent is actively trying to download data.

NETWORK_NO_SOURCE (numeric value 3)

The element's resource selection algorithm is active, but it has not yet found a resource to use.

The resource selection algorithm defined below describes exactly when the networkState attribute changes value and what events fire to indicate changes in this state.

Loading the media resource

media . load()

Causes the element to reset and start selecting and loading a new media resource from scratch.

All media elements have an autoplaying flag, which must begin in the true state, and a delaying-the-load-event flag, which must begin in the false state. While the delaying-the-load-event flag is true, the element must delay the load event of its document.

When the load() method on a media element is invoked, the user agent must run the media element load algorithm.

The media element load algorithm consists of the following steps.

1. Abort any already-running instance of the resource selection algorithm for this element.

2. If there are any tasks from the media element's media element event task source in one of the task queues, then remove those tasks.

   Basically, pending events and callbacks for the media element are discarded when the media element starts loading a new resource.

3. If the media element's networkState is set to NETWORK_LOADING or NETWORK_IDLE, queue a task to fire a simple event named abort at the media element.

4. If the media element's networkState is not set to NETWORK_EMPTY, then run these substeps:

   1. Queue a task to fire a simple event named emptied at the media element.

   2. If a fetching process is in progress for the media element, the user agent should stop it.

   3. Forget the media element's media-resource-specific tracks.

   4. If readyState is not set to HAVE_NOTHING, then set it to that state.

   5. If the paused attribute is false, then set it to true.

   6. If seeking is true, set it to false.

   7. Set the current playback position to 0.

      Set the official playback position to 0.

      If this changed the official playback position, then queue a task to fire a simple event named timeupdate at the media element.

   8. Set the timeline offset to Not-a-Number (NaN).

   9. Update the duration attribute to Not-a-Number (NaN).

      The user agent will not fire a durationchange event for this particular change of the duration.

5. Set the playbackRate attribute to the value of the defaultPlaybackRate attribute.

6. Set the error attribute to null and the autoplaying flag to true.

7. Invoke the media element's resource selection algorithm.

8. Playback of any previously playing media resource for this element stops.

The resource selection algorithm for a media element is as follows. This algorithm is always invoked as part of a task, but one of the first steps in the algorithm is to return and continue running the remaining steps in parallel. In addition, this algorithm interacts closely with the event loop mechanism; in particular, it has synchronous sections (which are triggered as part of the event loop algorithm). Steps in such sections are marked with ⌛.

1. Set the element's networkState attribute to the NETWORK_NO_SOURCE value.

2. Set the element's show poster flag to true.

3. Set the media element's delaying-the-load-event flag to true (this delays the load event).

4. Await a stable state, allowing the task that invoked this algorithm to continue. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

5. ⌛ If the media element's blocked-on-parser flag is false, then populate the list of pending text tracks.

6. ⌛ If the media element has an assigned media provider object, then let mode be object.

   ⌛ Otherwise, if the media element has no assigned media provider object but has a src attribute, then let mode be attribute.

   ⌛ Otherwise, if the media element does not have an assigned media provider object and does not have a src attribute, but does have a source element child, then let mode be children and let candidate be the first such source element child in tree order.

   ⌛ Otherwise the media element has no assigned media provider object and has neither a src attribute nor a source element child: set the networkState to NETWORK_EMPTY, and abort these steps; the synchronous section ends.

7. ⌛ Set the media element's networkState to NETWORK_LOADING.

8. ⌛ Queue a task to fire a simple event named loadstart at the media element.

9. Run the appropriate steps from the following list:

   If mode is object

   1. ⌛ Set the currentSrc attribute to the empty string.

   2. End the synchronous section, continuing the remaining steps in parallel.

   3. Run the resource fetch algorithm with the assigned media provider object. If that algorithm returns without aborting this one, then the load failed.

   4. Failed with media provider: Reaching this step indicates that the media resource failed to load. Queue a task to run the dedicated media source failure steps.

   5. Wait for the task queued by the previous step to have executed.

   6. Abort these steps. The element won't attempt to load another resource until this algorithm is triggered again.

   If mode is attribute

   1. ⌛ If the src attribute's value is the empty string, then end the synchronous section, and jump down to the failed with attribute step below.

   2. ⌛ Let absolute URL be the absolute URL that would have resulted from resolving the URL specified by the src attribute's value relative to the media element when the src attribute was last changed.

   3. ⌛ If absolute URL was obtained successfully, set the currentSrc attribute to absolute URL.

   4. End the synchronous section, continuing the remaining steps in parallel.

   5. If absolute URL was obtained successfully, run the resource fetch algorithm with absolute URL. If that algorithm returns without aborting this one, then the load failed.

   6. Failed with attribute: Reaching this step indicates that the media resource failed to load or that the given URL could not be resolved. Queue a task to run the dedicated media source failure steps.

   7. Wait for the task queued by the previous step to have executed.

   8. Abort these steps. The element won't attempt to load another resource until this algorithm is triggered again.

   Otherwise (mode is children)

   1. ⌛ Let pointer be a position defined by two adjacent nodes in the media element's child list, treating the start of the list (before the first child in the list, if any) and end of the list (after the last child in the list, if any) as nodes in their own right. One node is the node before pointer, and the other node is the node after pointer. Initially, let pointer be the position between the candidate node and the next node, if there are any, or the end of the list, if it is the last node.

      As nodes are inserted and removed into the media element, pointer must be updated as follows:

      If a new node is inserted between the two nodes that define pointer

      Let pointer be the point between the node before pointer and the new node. In other words, insertions at pointer go after pointer.

      If the node before pointer is removed

      Let pointer be the point between the node after pointer and the node before the node after pointer. In other words, pointer doesn't move relative to the remaining nodes.

      If the node after pointer is removed

      Let pointer be the point between the node before pointer and the node after the node before pointer. Just as with the previous case, pointer doesn't move relative to the remaining nodes.

      Other changes don't affect pointer.

   2. ⌛ Process candidate: If candidate does not have a src attribute, or if its src attribute's value is the empty string, then end the synchronous section, and jump down to the failed with elements step below.

   3. ⌛ Let absolute URL be the absolute URL that would have resulted from resolving the URL specified by candidate's src attribute's value relative to the candidate when the src attribute was last changed.

   4. ⌛ If absolute URL was not obtained successfully, then end the synchronous section, and jump down to the failed with elements step below.

   5. ⌛ If candidate has a type attribute whose value, when parsed as a MIME type (including any codecs described by the codecs parameter, for types that define that parameter), represents a type that the user agent knows it cannot render, then end the synchronous section, and jump down to the failed with elements step below.

   6. ⌛ Set the currentSrc attribute to absolute URL.

   7. End the synchronous section, continuing the remaining steps in parallel.

   8. Run the resource fetch algorithm with absolute URL. If that algorithm returns without aborting this one, then the load failed.

   9. Failed with elements: Queue a task to fire a simple event named error at the candidate element.

   10. Await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

   11. ⌛ Forget the media element's media-resource-specific tracks.

   12. ⌛ Find next candidate: Let candidate be null.

   13. ⌛ Search loop: If the node after pointer is the end of the list, then jump to the waiting step below.

   14. ⌛ If the node after pointer is a source element, let candidate be that element.

   15. ⌛ Advance pointer so that the node before pointer is now the node that was after pointer, and the node after pointer is the node after the node that used to be after pointer, if any.

   16. ⌛ If candidate is null, jump back to the search loop step. Otherwise, jump back to the process candidate step.

   17. ⌛ Waiting: Set the element's networkState attribute to the NETWORK_NO_SOURCE value.

   18. ⌛ Set the element's show poster flag to true.

   19. ⌛ Queue a task to set the element's delaying-the-load-event flag to false. This stops delaying the load event.

   20. End the synchronous section, continuing the remaining steps in parallel.

   21. Wait until the node after pointer is a node other than the end of the list. (This step might wait forever.)

   22. Await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)

   23. ⌛ Set the element's delaying-the-load-event flag back to true (this delays the load event again, in case it hasn't been fired yet).

   24. ⌛ Set the networkState back to NETWORK_LOADING.

   25. ⌛ Jump back to the find next candidate step above.

   The dedicated media source failure steps are the following steps:

   1. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_SRC_NOT_SUPPORTED.

   2. Forget the media element's media-resource-specific tracks.

   3. Set the element's networkState attribute to the NETWORK_NO_SOURCE value.

   4. Set the element's show poster flag to true.

   5. Fire a simple event named error at the media element.

   6. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

The resource fetch algorithm for a media element and a given absolute URL or media provider object is as follows:

1. If the algorithm was invoked with a URL, then let mode be remote, otherwise let mode be local.

2. If mode is local, then let the current media resource be the resource given by the absolute URL passed to this algorithm; otherwise, let the current media resource be the resource given by the media provider object. Either way, the current media resource is now the element's media resource.

3. Remove all media-resource-specific text tracks from the media element's list of pending text tracks, if any.

4. Run the appropriate steps from the following list:

   If mode is remote

   1. Optionally, run the following substeps. This is the expected behaviour if the user agent intends to not attempt to fetch the resource until the user requests it explicitly (e.g. as a way to implement the preload attribute's none keyword).

      1. Set the networkState to NETWORK_IDLE.

      2. Queue a task to fire a simple event named suspend at the element.

      3. Queue a task to set the element's delaying-the-load-event flag to false. This stops delaying the load event.

      4. Wait for the task to be run.

      5. Wait for an implementation-defined event (e.g. the user requesting that the media element begin playback).

      6. Set the element's delaying-the-load-event flag back to true (this delays the load event again, in case it hasn't been fired yet).

      7. Set the networkState to NETWORK_LOADING.

   2. Perform a potentially CORS-enabled fetch of the current media resource's absolute URL, with the mode being the state of the media element's crossorigin content attribute, the origin being the origin of the media element's node document, and the default origin behaviour set to taint.

      The resource obtained in this fashion, if any, contains the media data. It can be CORS-same-origin or CORS-cross-origin; this affects whether subtitles referenced in the media data are exposed in the API and, for video elements, whether a canvas gets tainted when the video is drawn on it.

      The stall timeout is a user-agent defined length of time, which should be about three seconds. When a media element that is actively attempting to obtain media data has failed to receive any data for a duration equal to the stall timeout, the user agent must queue a task to fire a simple event named 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 altogether, the user agent must act as if it was stalled (as opposed to acting as if the connection was closed). The rate of the download may also be throttled automatically by the user agent, e.g. to balance the download with other connections sharing the same bandwidth.

      User agents may decide to not download more content at any time, e.g. after buffering five minutes of a one hour media resource, while waiting for the user to decide whether to play the resource or not, while waiting for user input in an interactive resource, or when the user navigates away from the page. When a media element's download has been suspended, the user agent must queue a task, to set the networkState to NETWORK_IDLE and fire a simple event named suspend at the element. If and when downloading of the resource resumes, the user agent must queue a task to set the networkState to NETWORK_LOADING. Between the queuing of these tasks, the load is suspended (so progress events don't fire, as described above).

      The preload attribute provides a hint regarding how much buffering the author thinks is advisable, even in the absence of the autoplay attribute.

      When a user agent decides to completely stall a download, e.g. if it is waiting until the user starts playback before downloading any further content, the user agent must queue a task to set the element's delaying-the-load-event flag to false. This stops delaying the load event.

      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 range retrieval 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.

      To determine the format of the media resource, the user agent must use the rules for sniffing audio and video specifically.

      While the load is not suspended (see below), every 350ms (±200ms) or for every byte received, whichever is least frequent, queue a task to fire a simple event named progress at the element.

      The networking task source tasks to process the data as it is being fetched must each immediately queue a task to run the first appropriate steps from the media data processing steps list below. (A new task is used for this so that the work described below occurs relative to the media element event task source rather than the networking task source.)

      When the networking task source has queued the last task as part of fetching the media resource (i.e. once the download has completed), if the fetching process completes without errors, including decoding the media data, and if all of the data is available to the user agent without network access, then, the user agent must move on to the final step below. This might never happen, e.g. when streaming an infinite resource such as Web radio, or if the resource is longer than the user agent's ability to cache data.

      While the user agent might still need network access to obtain parts of the media resource, the user agent must remain on this step.

      For example, if the user agent has discarded the first half of a video, the user agent will remain at this step even once the playback has ended, because there is always the chance the user will seek back to the start. In fact, in this situation, once playback has ended, the user agent will end up firing a suspend event, as described earlier.

   Otherwise (mode is local)

   The resource described by the current media resource, if any, contains the media data. It is CORS-same-origin.

   If the current media resource is a raw data stream (e.g. from a File object), then to determine the format of the media resource, the user agent must use the rules for sniffing audio and video specifically. Otherwise, if the data stream is pre-decoded, then the format is the format given by the relevant specification.

   Whenever new data for the current media resource becomes available, queue a task to run the first appropriate steps from the media data processing steps list below.

   When the current media resource is permanently exhausted (e.g. all the bytes of a Blob have been processed), if there were no decoding errors, then the user agent must move on to the final step below. This might never happen, e.g. if the current media resource is a MediaStream.

   The media data processing steps list is as follows:

   If the media data cannot be fetched at all, due to network errors, causing the user agent to give up trying to fetch the resource

   If the media data can be fetched but is found by inspection to be in an unsupported format, or can otherwise not be rendered at all

   DNS errors, HTTP 4xx and 5xx errors (and equivalents in other protocols), and other fatal network errors that occur before the user agent has established whether the current media resource is usable, as well as the file using an unsupported container format, or using unsupported codecs for all the data, must cause the user agent to execute the following steps:

   1. The user agent should cancel the fetching process.

   2. Abort this subalgorithm, returning to the resource selection algorithm.

   If the media resource is found to have an audio track

   1. Create an AudioTrack object to represent the audio track.

   2. Update the media element's audioTracks attribute's AudioTrackList object with the new AudioTrack object.

   3. Let enable be unknown.

   4. If either the media resource or the address of the current media resource indicate a particular set of audio tracks to enable, or if the user agent has information that would facilitate the selection of specific audio tracks to improve the user's experience, then: if this audio track is one of the ones to enable, then set enable to true, otherwise, set enable to false.

      This could be triggered by Media Fragments URI fragment identifier syntax, but it could also be triggered e.g. by the user agent selecting a 5.1 surround sound audio track over a stereo audio track. [[!MEDIAFRAG]]

   5. If enable is still unknown, then, if the media element does not yet have an enabled audio track, then set enable to true, otherwise, set enable to false.

   6. If enable is true, then enable this audio track, otherwise, do not enable this audio track.

   7. Fire a trusted event with the name addtrack, that does not bubble and is not cancelable, and that uses the TrackEvent interface, with the track attribute initialised to the new AudioTrack object, at this AudioTrackList object.

   If the media resource is found to have a video track

   1. Create a VideoTrack object to represent the video track.

   2. Update the media element's videoTracks attribute's VideoTrackList object with the new VideoTrack object.

   3. Let enable be unknown.

   4. If either the media resource or the address of the current media resource indicate a particular set of video tracks to enable, or if the user agent has information that would facilitate the selection of specific video tracks to improve the user's experience, then: if this video track is the first such video track, then set enable to true, otherwise, set enable to false.

      This could again be triggered by Media Fragments URI fragment identifier syntax.

   5. If enable is still unknown, then, if the media element does not yet have a selected video track, then set enable to true, otherwise, set enable to false.

   6. If enable is true, then select this track and unselect any previously selected video tracks, otherwise, do not select this video track. If other tracks are unselected, then a change event will be fired.

   7. Fire a trusted event with the name addtrack, that does not bubble and is not cancelable, and that uses the TrackEvent interface, with the track attribute initialised to the new VideoTrack object, at this VideoTrackList object.

   Once enough of the media data has been fetched to determine the duration of the media resource, its dimensions, and other metadata

   This indicates that the resource is usable. The user agent must follow these substeps:

   1. Establish the media timeline for the purposes of the current playback position and the earliest possible position, based on the media data.

   2. Update the timeline offset to the date and time that corresponds to the zero time in the media timeline established in the previous step, if any. If no explicit time and date is given by the media resource, the timeline offset must be set to Not-a-Number (NaN).

   3. Set the current playback position and the official playback position to the earliest possible position.

   4. Update the duration attribute with the time of the last frame of the resource, if known, on the media timeline established above. If it is not known (e.g. a stream that is in principle infinite), update the duration attribute to the value positive Infinity.

      The user agent will queue a task to fire a simple event named durationchange at the element at this point.

   5. For video elements, set the videoWidth and videoHeight attributes, and queue a task to fire a simple event named resize at the media element.

      Further resize events will be fired if the dimensions subsequently change.

   6. Set the readyState attribute to HAVE_METADATA.

      A loadedmetadata DOM event will be fired as part of setting the readyState attribute to a new value.

   7. Let jumped be false.

   8. If the media element's default playback start position is greater than zero, then seek to that time, and let jumped be true.

   9. Let the media element's default playback start position be zero.

   10. Let the initial playback position be zero.

   11. If either the media resource or the address of the current media resource indicate a particular start time, then set the initial playback position to that time and, if jumped is still false, seek to that time and let jumped be true.

       For example, with media formats that support the Media Fragments URI fragment identifier syntax, the fragment identifier can be used to indicate a start position. [[!MEDIAFRAG]]

   12. If there is no enabled audio track, then enable an audio track. This will cause a change event to be fired.

   13. If there is no selected video track, then select a video track. This will cause a change event to be fired.

   14. If the media element has a current media controller, then: if jumped is true and the initial playback position, relative to the current media controller's timeline, is greater than the current media controller's media controller position, then seek the media controller to the media element's initial playback position, relative to the current media controller's timeline; otherwise, seek the media element to the media controller position, relative to the media element's timeline.

   Once the readyState attribute reaches HAVE_CURRENT_DATA, after the loadeddata event has been fired, set the element's delaying-the-load-event flag to false. This stops delaying the load event.

   A user agent that is attempting to reduce network usage while still fetching the metadata for each media resource would also stop buffering at this point, following the rules described previously, which involve the networkState attribute switching to the NETWORK_IDLE value and a suspend event firing.

   The user agent is required to determine the duration of the media resource and go through this step before playing.

   Once the entire media resource has been fetched (but potentially before any of it has been decoded)

   Fire a simple event named progress at the media element.

   Set the networkState to NETWORK_IDLE and fire a simple event named suspend at the media element.

   If the user agent ever discards any media data and then needs to resume the network activity to obtain it again, then it must queue a task to set the networkState to NETWORK_LOADING.

   If the user agent can keep the media resource loaded, then the algorithm will continue to its final step below, which aborts the algorithm.

   If the connection is interrupted after some media data has been received, causing the user agent to give up trying to fetch the resource

   Fatal network errors that occur after the user agent has established whether the current media resource is usable (i.e. once the media element's readyState attribute is no longer HAVE_NOTHING) must cause the user agent to execute the following steps:

   1. The user agent should cancel the fetching process.

   2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_NETWORK.

   3. Set the element's networkState attribute to the NETWORK_IDLE value.

   4. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

   5. Fire a simple event named error at the media element.

   6. Abort the overall resource selection algorithm.

   If the media data is corrupted

   Fatal errors in decoding the media data that occur after the user agent has established whether the current media resource is usable (i.e. once the media element's readyState attribute is no longer HAVE_NOTHING) must cause the user agent to execute the following steps:

   1. The user agent should cancel the fetching process.

   2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_DECODE.

   3. Set the element's networkState attribute to the NETWORK_IDLE value.

   4. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

   5. Fire a simple event named error at the media element.

   6. Abort the overall resource selection algorithm.

   If the media data fetching process is aborted by the user

   The fetching process is aborted by the user, e.g. because the user pressed a "stop" button, the user agent must execute the following steps. These steps are not followed if the load() method itself is invoked while these steps are running, as the steps above handle that particular kind of abort.

   1. The user agent should cancel the fetching process.

   2. Set the error attribute to a new MediaError object whose code attribute is set to MEDIA_ERR_ABORTED.

   3. Fire a simple event named abort at the media element.

   4. If the media element's readyState attribute has a value equal to HAVE_NOTHING, set the element's networkState attribute to the NETWORK_EMPTY value, set the element's show poster flag to true, and fire a simple event named emptied at the element.

      Otherwise, set the element's networkState attribute to the NETWORK_IDLE value.

   5. Set the element's delaying-the-load-event flag to false. This stops delaying the load event.

   6. Abort the overall resource selection algorithm.

   If the media data can be fetched but has non-fatal errors or uses, in part, codecs that are unsupported, preventing the user agent from rendering the content completely correctly but not preventing playback altogether

   The server returning data that is partially usable but cannot be optimally rendered must cause the user agent to render just the bits it can handle, and ignore the rest.

   If the media resource is found to declare a media-resource-specific text track that the user agent supports

   If the media data is CORS-same-origin, run the steps to expose a media-resource-specific text track with the relevant data.

   Cross-origin videos do not expose their subtitles, since that would allow attacks such as hostile sites reading subtitles from confidential videos on a user's intranet.

5. Final step: If the user agent ever reaches this step (which can only happen if the entire resource gets loaded and kept available): abort the overall resource selection algorithm.

When a media element is to forget the media element's media-resource-specific tracks, the user agent must remove from the media element's list of text tracks all the media-resource-specific text tracks, then empty the media element's audioTracks attribute's AudioTrackList object, then empty the media element's videoTracks attribute's VideoTrackList object. No events (in particular, no removetrack events) are fired as part of this; the error and emptied events, fired by the algorithms that invoke this one, can be used instead.

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. The attribute can be changed even once the media resource is being buffered or played; the descriptions in the table below are to be interpreted with that in mind.

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.

Authors might switch the attribute from "none" or "metadata" to "auto" dynamically once the user begins playback. For example, on a page with many videos this might be used to indicate that the many videos are not to be downloaded unless requested, but that once one is requested it is to be downloaded aggressively.

The preload attribute is intended to provide a hint to the user agent about what the author thinks will lead to the best user experience. The attribute may be ignored altogether, for example based on explicit user preferences or based on the available connectivity.

The preload IDL attribute must reflect the content attribute of the same name, limited to only known values.

The autoplay attribute can override 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.

media . buffered

Returns a TimeRanges object that represents the ranges of the media resource that the user agent has buffered.

The buffered attribute must return a new static normalised 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. Users agents must accurately determine the ranges available, even for media streams where this can only be determined by tedious inspection.

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.

User agents may discard previously buffered data.

Thus, a time position included within a range of the objects return by the buffered attribute at one time can end up being not included in the range(s) of objects returned by the same attribute at later times.

Offsets into the media resource

media . duration

Returns the length of the media resource, in seconds, assuming that the start of the media resource is at time zero.

Returns NaN if the duration isn't available.

Returns Infinity for unbounded streams.

media . currentTime [ = value ]

Returns the official playback position, in seconds.

Can be set, to seek to the given time.

Will throw an InvalidStateError exception if there is no selected media resource or if there is a current media controller.

A media resource has a media timeline that maps times (in seconds) to positions in the media resource. The origin of a timeline is its earliest defined position. The duration of a timeline is its last defined position.

Establishing the media timeline: If the media resource somehow specifies an explicit timeline whose origin is not negative (i.e. gives each frame a specific time offset and gives the first frame a zero or positive offset), then the media timeline should be that timeline. (Whether the media resource can specify a timeline or not depends on the media resource's format.) If the media resource specifies an explicit start time and date, then that time and date should be considered the zero point in the media timeline; the timeline offset will be the time and date, exposed using the getStartDate() method.

If the media resource has a discontinuous timeline, the user agent must extend the timeline used at the start of the resource across the entire resource, so that the media timeline of the media resource increases linearly starting from the earliest possible position (as defined below), even if the underlying media data has out-of-order or even overlapping time codes.

For example, if two clips have been concatenated into one video file, but the video format exposes the original times for the two clips, the video data might expose a timeline that goes, say, 00:15..00:29 and then 00:05..00:38. However, the user agent would not expose those times; it would instead expose the times as 00:15..00:29 and 00:29..01:02, as a single video.

In the rare case of a media resource that does not have an explicit timeline, the zero time on the media timeline should correspond to the first frame of the media resource. In the even rarer case of a media resource with no explicit timings of any kind, not even frame durations, the user agent must itself determine the time for each frame in a user-agent-defined manner.

An example of a file format with no explicit timeline but with explicit frame durations is the Animated GIF format. An example of a file format with no explicit timings at all is the JPEG-push format (multipart/x-mixed-replace with JPEG frames, often used as the format for MJPEG streams).

If, in the case of a resource with no timing information, the user agent will nonetheless be able to seek to an earlier point than the first frame originally provided by the server, then the zero time should correspond to the earliest seekable time of the media resource; otherwise, it should correspond to the first frame received from the server (the point in the media resource at which the user agent began receiving the stream).

At the time of writing, there is no known format that lacks explicit frame time offsets yet still supports seeking to a frame before the first frame sent by the server.

In any case, the user agent must ensure that the earliest possible position (as defined below) using the established media timeline, is greater than or equal to zero.

The media timeline also has an associated clock. Which clock is used is user-agent defined, and may be media resource-dependent, but it should approximate the user's wall clock.

All the media elements that share current media controller use the same clock for their media timeline.

Media elements have a current playback position, which must initially (i.e. in the absence of media data) be zero seconds. The current playback position is a time on the media timeline.

Media elements also have an official playback position, which must initially be set to zero seconds. The official playback position is an approximation of the current playback position that is kept stable while scripts are running.

Media elements also have a default playback start position, which must initially be set to zero seconds. This time is used to allow the element to be seeked even before the media is loaded.

Each media element has a show poster flag. When a media element is created, this flag must be set to true. This flag is used to control when the user agent is to show a poster frame for a video element instead of showing the video contents.

The currentTime attribute must, on getting, return the media element's default playback start position, unless that is zero, in which case it must return the element's official playback position. The returned value must be expressed in seconds. On setting, if the media element has a current media controller, then the user agent must throw an InvalidStateError exception; otherwise, if the media element's readyState is HAVE_NOTHING, then it must set the media element's default playback start position to the new value; otherwise, it must set the official playback position to the new value and then seek to the new value. The new value must be interpreted as being in seconds.

If the media resource is a streaming resource, then the user agent might be unable to obtain certain parts of the resource after it has expired from its buffer. Similarly, some media resources might have a media timeline that doesn't start at zero. The earliest possible position is the earliest position in the stream or resource that the user agent can ever obtain again. It is also a time on the media timeline.

The earliest possible position is not explicitly exposed in the API; it corresponds to the start time of the first range in the seekable attribute's TimeRanges object, if any, or the current playback position otherwise.

When the earliest possible position changes, then: if the current playback position is before the earliest possible position, the user agent must seek to the earliest possible position; otherwise, if the user agent has not fired a timeupdate event at the element in the past 15 to 250ms and is not still running event handlers for such an event, then the user agent must queue a task to fire a simple event named timeupdate at the element.

Because of the above requirement and the requirement in the resource fetch algorithm that kicks in when the metadata of the clip becomes known, the current playback position can never be less than the earliest possible position.

If at any time the user agent learns that an audio or video track has ended and all media data relating to that track corresponds to parts of the media timeline that are before the earliest possible position, the user agent may queue a task to first remove the track from the audioTracks attribute's AudioTrackList object or the videoTracks attribute's VideoTrackList object as appropriate and then fire a trusted event with the name removetrack, that does not bubble and is not cancelable, and that uses the TrackEvent interface, with the track attribute initialised to the AudioTrack or VideoTrack object representing the track, at the media element's aforementioned AudioTrackList or VideoTrackList object.

The duration attribute must return the time of the end of the media resource, in seconds, on the media timeline. If no media data is available, then the attributes must return the Not-a-Number (NaN) value. If the media resource is not known to be bounded (e.g. streaming radio, or a live event with no announced end time), then the attribute must return the positive Infinity value.

The user agent must determine the duration of the media resource before playing any part of the media data and before setting readyState to a value equal to or greater than HAVE_METADATA, even if doing so requires fetching multiple parts of the resource.

When the length of the media resource changes to a known value (e.g. from being unknown to known, or from a previously established length to a new length) the user agent must queue a task to fire a simple event named durationchange at the media element. (The event is not fired when the duration is reset as part of loading a new media resource.) If the duration is changed such that the current playback position ends up being greater than the time of the end of the media resource, then the user agent must also seek to the time of the end of the media resource.

If an "infinite" stream ends for some reason, then the duration would change from positive Infinity to the time of the last frame or sample in the stream, and the durationchange event would be fired. Similarly, if the user agent initially estimated the media resource's duration instead of determining it precisely, and later revises the estimate based on new information, then the duration would change and the durationchange event would be fired.

Some video files also have an explicit date and time corresponding to the zero time in the media timeline, known as the timeline offset. Initially, the timeline offset must be set to Not-a-Number (NaN).

The getStartDate() method must return a new Date object representing the current timeline offset.

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.

The loop attribute has no effect while the element has a current media controller.

The loop IDL attribute must reflect the content attribute of the same name.

Ready states

media . 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.

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:

HAVE_NOTHING (numeric value 0)

No information regarding the media resource is available. No data for the current playback position is available. Media elements whose networkState attribute are set to NETWORK_EMPTY are always in the HAVE_NOTHING state.

HAVE_METADATA (numeric value 1)

Enough of the resource has been obtained that the duration of the resource is available. In the case of a video element, the dimensions of the video are also available. The API will no longer throw an exception when seeking. No media data is available for the immediate current playback position.

HAVE_CURRENT_DATA (numeric value 2)

Data for the immediate current playback position is available, but either not enough data is available that the user agent could successfully advance the current playback position in the direction of playback at all without immediately reverting to the 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, when the current playback position is at the end of the current frame; and to when playback has ended.

HAVE_FUTURE_DATA (numeric value 3)

Data for the immediate current playback position is available, as well as enough data for the user agent to advance the current playback position in the direction of playback at least a little without immediately reverting to the HAVE_METADATA state, and the text tracks are ready. For example, in video this corresponds to the user agent having data for at least the current frame and the next frame when the current playback position is at the instant in time between the two frames, or to the user agent having the video data for the current frame and audio data to keep playing at least a little when the current playback position is in the middle of a 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)

All the conditions described for the HAVE_FUTURE_DATA state are met, and, in addition, either of the following conditions is also true:

• The user agent estimates that data is being fetched at a rate where the current playback position, if it were to advance at the effective playback rate, would not overtake the available data before playback reaches the end of the media resource.
• The user agent has entered a state where waiting longer will not result in further data being obtained, and therefore nothing would be gained by delaying playback any further. (For example, the buffer might be full.)

In practice, the difference between HAVE_METADATA and HAVE_CURRENT_DATA is negligible. Really the only time the difference is relevant is when painting a video element onto a canvas, where it distinguishes the case where something will be drawn (HAVE_CURRENT_DATA or greater) from the case where nothing is drawn (HAVE_METADATA or less). Similarly, the difference between HAVE_CURRENT_DATA (only the current frame) and HAVE_FUTURE_DATA (at least this frame and the next) can be negligible (in the extreme, only one frame). The only time that distinction really matters is when a page provides an interface for "frame-by-frame" navigation.

When the ready state of a media element whose networkState is not NETWORK_EMPTY changes, the user agent must follow the steps given below:

1. Apply the first applicable set of substeps from the following list:

   If the previous ready state was HAVE_NOTHING, and the new ready state is HAVE_METADATA

   Queue a task to fire a simple event named loadedmetadata at the element.

   Before this task is run, as part of the event loop mechanism, the rendering will have been updated to resize the video element if appropriate.

   If the previous ready state was HAVE_METADATA and the new ready state is HAVE_CURRENT_DATA or greater

   If this is the first time this occurs for this media element since the load() algorithm was last invoked, the user agent must queue a task to fire a simple event named loadeddata at the element.

   If the new ready state is HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA, then the relevant steps below must then be run also.

   If the previous ready state was HAVE_FUTURE_DATA or more, and the new ready state is HAVE_CURRENT_DATA or less

   If the media element was potentially playing before its readyState attribute changed to a value lower than HAVE_FUTURE_DATA, and the element has not ended playback, and playback has not stopped due to errors, paused for user interaction, or paused for in-band content, the user agent must queue a task to fire a simple event named timeupdate at the element, and queue a task to fire a simple event named waiting at the element.

   If the previous ready state was HAVE_CURRENT_DATA or less, and the new ready state is HAVE_FUTURE_DATA

   The user agent must queue a task to fire a simple event named canplay at the element.

   If the element's paused attribute is false, the user agent must queue a task to fire a simple event named playing at the element.

   If the new ready state is HAVE_ENOUGH_DATA

   If the previous ready state was HAVE_CURRENT_DATA or less, the user agent must queue a task to fire a simple event named canplay at the element, and, if the element's paused attribute is false, queue a task to fire a simple event named playing at the element.

   If the autoplaying flag is true, and the paused attribute is true, and the media element has an autoplay attribute specified, and the media element's node document's active sandboxing flag set does not have the sandboxed automatic features browsing context flag set, then the user agent may also run the following substeps:

   1. Set the paused attribute to false.
   2. If the element's show poster flag is true, set it to false and run the time marches on steps.
   3. Queue a task to fire a simple event named play at the element.
   4. Queue a task to fire a simple event named playing at the element.

   User agents do not need to support autoplay, and it is suggested that user agents honor user preferences on the matter. Authors are urged to use the autoplay attribute rather than using script to force the video to play, so as to allow the user to override the behaviour if so desired.

   In any case, the user agent must finally queue a task to fire a simple event named canplaythrough at the element.

2. If the media element has a current media controller, then report the controller state for the media element's current media controller.

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 readyState IDL 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 user agent (as described in the algorithm described herein) 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 behaviour at all, and instead to let the user agent wait for the user to start playback explicitly.

The autoplay IDL attribute must reflect the content attribute of the same name.

Playing the media resource

media . paused

Returns true if playback is paused; false otherwise.

media . ended

Returns true if playback has reached the end of the media resource.

media . 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.

When the element has a current media controller, the defaultPlaybackRate attribute is ignored and the current media controller's defaultPlaybackRate is used instead.

media . playbackRate [ = value ]

Returns the current rate playback, where 1.0 is normal speed.

Can be set, to change the rate of playback.

When the element has a current media controller, the playbackRate attribute is ignored and the current media controller's playbackRate is used instead.

media . played

Returns a TimeRanges object that represents the ranges of the media resource that the user agent has played.

media . 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.

media . pause()

Sets the paused attribute to true, loading the media resource if necessary.

The paused attribute represents whether the media element is paused or not. The attribute must initially be true.

A media element is a blocked media element if its readyState attribute is in the HAVE_NOTHING state, the HAVE_METADATA state, or the HAVE_CURRENT_DATA state, or if the element has paused for user interaction or paused for in-band content.

A media element is said to be potentially playing when its paused attribute is false, the element has not ended playback, playback has not stopped due to errors, the element either has no current media controller or has a current media controller but is not blocked on its media controller, and the element is not a blocked media element.

A waiting DOM event can be fired as a result of an element that is potentially playing stopping playback due to its readyState attribute changing to a value lower than HAVE_FUTURE_DATA.

A media element is said to have ended playback when:

• The element's readyState attribute is HAVE_METADATA or greater, and

• Either:

  • The current playback position is the end of the media resource, and
  • The direction of playback is forwards, and
  • Either the media element does not have a loop attribute specified, or the media element has a current media controller.

  Or:

  • The current playback position is the earliest possible position, and
  • The direction of playback is backwards.

The ended attribute must return true if, the last time the event loop reached step 1, the media element had ended playback and the direction of playback was forwards, and false otherwise.

A media element is said to have stopped due to errors when the element's readyState attribute is HAVE_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 HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA 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. If the media element has a current media controller when this happens, then the user agent must report the controller state for the media element's current media controller. If the media element has a current media controller when the user makes a selection, allowing playback to resume, the user agent must similarly report the controller state for the media element's current media controller.

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 that is potentially playing stops playing because it has paused for user interaction, the user agent must queue a task to fire a simple event named timeupdate at the element.

A media element is said to have paused for in-band content when its paused attribute is false, the readyState attribute is either HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA and the user agent has suspended playback of the media resource in order to play content that is temporally anchored to the media resource and has a non-zero length, or to play content that is temporally anchored to a segment of the media resource but has a length longer than that segment. If the media element has a current media controller when this happens, then the user agent must report the controller state for the media element's current media controller. If the media element has a current media controller when the user agent unsuspends playback, the user agent must similarly report the controller state for the media element's current media controller.

One example of when a media element would be paused for in-band content is when the user agent is playing audio descriptions from an external WebVTT file, and the synthesized speech generated for a cue is longer than the time between the text track cue start time and the text track cue end time.

When the current playback position reaches the end of the media resource when the direction of playback is forwards, then the user agent must follow these steps:

1. If the media element has a loop attribute specified and does not have a current media controller, then seek to the earliest possible position of the media resource and abort these steps.

2. As defined above, the ended IDL attribute starts returning true once the event loop returns to step 1.

3. Queue a task to fire a simple event named timeupdate at the media element.

4. Queue a task that, if the media element does not have a current media controller, and the media element has still ended playback, and the direction of playback is still forwards, and paused is false, changes paused to true and fires a simple event named pause at the media element.

5. Queue a task to fire a simple event named ended at the media element.

6. If the media element has a current media controller, then report the controller state for the media element's current media controller.

When the current playback position reaches the earliest possible position of the media resource when the direction of playback is backwards, then the user agent must only queue a task to fire a simple event named timeupdate at the element.

The word "reaches" here does not imply that the current playback position needs to have changed during normal playback; it could be via seeking, for instance.

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: on getting it must return the last value it was set to, or 1.0 if it hasn't yet been set; on setting the attribute must be set to the new value.

The defaultPlaybackRate is used by the user agent when it exposes a user interface to the user.

The playbackRate attribute gives the effective playback rate (assuming there is no current media controller overriding it), which is 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: on getting it must return the last value it was set to, or 1.0 if it hasn't yet been set; on setting the attribute must be set to the new value, and the playback will change speed (if the element is potentially playing and there is no current media controller).

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 named ratechange at the media element.

The defaultPlaybackRate and playbackRate attributes have no effect when the media element has a current media controller; the namesake attributes on the MediaController object are used instead in that situation.

The played attribute must return a new static normalised TimeRanges object that represents the ranges of points on the media timeline of the media resource reached through the usual monotonic increase of the current playback position during normal playback, if any, at the time the attribute is evaluated.

When the play() method on a media element is invoked, the user agent must run the following steps.

1. If the media element's networkState attribute has the value NETWORK_EMPTY, invoke the media element's resource selection algorithm.

2. If the playback has ended and the direction of playback is forwards, and the media element does not have a current media controller, seek to the earliest possible position of the media resource.

   This will cause the user agent to queue a task to fire a simple event named timeupdate at the media element.

3. If the media element has a current media controller, then bring the media element up to speed with its new media controller.

4. If the media element's paused attribute is true, run the following substeps:

   1. Change the value of paused to false.

   2. If the show poster flag is true, set the element's show poster flag to false and run the time marches on steps.

   3. Queue a task to fire a simple event named play at the element.

   4. If the media element's readyState attribute has the value HAVE_NOTHING, HAVE_METADATA, or HAVE_CURRENT_DATA, queue a task to fire a simple event named waiting at the element.

      Otherwise, the media element's readyState attribute has the value HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA: queue a task to fire a simple event named playing at the element.

5. Set the media element's autoplaying flag to false.

6. If the media element has a current media controller, then report the controller state for the media element's current media controller.

When the pause() method is invoked, and when the user agent is required to pause the media element, the user agent must run the following steps:

1. If the media element's networkState attribute has the value NETWORK_EMPTY, invoke the media element's resource selection algorithm.

2. Run the internal pause steps for the media element.

The internal pause steps for a media element are as follows:

1. Set the media element's autoplaying flag to false.

2. If the media element's paused attribute is false, run the following steps:

   1. Change the value of paused to true.

   2. Queue a task to fire a simple event named timeupdate at the element.

   3. Queue a task to fire a simple event named pause at the element.

   4. Set the official playback position to the current playback position.

3. If the media element has a current media controller, then report the controller state for the media element's current media controller.

The effective playback rate is not necessarily the element's playbackRate. When a media element has a current media controller, its effective playback rate is the MediaController's media controller playback rate. Otherwise, the effective playback rate is just the element's playbackRate. Thus, the current media controller overrides the media element.

If the effective playback rate is positive or zero, then the direction of playback is forwards. Otherwise, it is backwards.

When a media element is potentially playing and its Document is a fully active Document, its current playback position must increase monotonically at effective playback rate units of media time per unit time of the media timeline's clock. (This specification always refers to this as an increase, but that increase could actually be a decrease if the effective playback rate is negative.)

The effective playback rate can be 0.0, in which case the current playback position doesn't move, despite playback not being paused (paused doesn't become true, and the pause event doesn't fire).

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.

Any time the user agent provides a stable state, the official playback position must be set to the current playback position.

While the direction of playback is backwards, any corresponding audio must be muted. While the effective playback rate is so low or so high that the user agent cannot play audio usefully, the corresponding audio must also be muted. If the effective playback rate is not 1.0, the user agent may apply pitch adjustments to the audio as necessary to render it faithfully.

Media elements that are potentially 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 is in a state where no further audio could ever be played by that element may the element be garbage collected.

It is possible for an element to which no explicit references exist to play audio, even if such an element is not still actively playing: for instance, it could have a current media controller that still has references and can still be unpaused, or it could be unpaused but stalled waiting for content to buffer, or it could be still buffering, but with a suspend event listener that begins playback. Even a media element whose media resource has no audio tracks could eventually play audio again if it had an event listener that changes the media resource.

Each media element has a list of newly introduced cues, which must be initially empty. Whenever a text track cue is added to the list of cues of a text track that is in the list of text tracks for a media element, that cue must be added to the media element's list of newly introduced cues. Whenever a text track is added to the list of text tracks for a media element, all of the cues in that text track's list of cues must be added to the media element's list of newly introduced cues. When a media element's list of newly introduced cues has new cues added while the media element's show poster flag is not set, then the user agent must run the time marches on steps.

When a text track cue is removed from the list of cues of a text track that is in the list of text tracks for a media element, and whenever a text track is removed from the list of text tracks of a media element, if the media element's show poster flag is not set, then the user agent must run the time marches on steps.

When the current playback position of a media element changes (e.g. due to playback or seeking), the user agent must run the time marches on 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 cues to be skipped over as the user agent rushes ahead to "catch up".)

The time marches on steps are as follows:

1. Let current cues be a list of cues, initialised to contain all the cues of all the hidden or showing text tracks of the media element (not the disabled ones) whose start times are less than or equal to the current playback position and whose end times are greater than the current playback position.

2. Let other cues be a list of cues, initialised to contain all the cues of hidden and showing text tracks of the media element that are not present in current cues.

3. Let last time be the current playback position at the time this algorithm was last run for this media element, if this is not the first time it has run.

4. If the current playback position has, since the last time this algorithm was run, only changed through its usual monotonic increase during normal playback, then let missed cues be the list of cues in other cues whose start times are greater than or equal to last time and whose end times are less than or equal to the current playback position. Otherwise, let missed cues be an empty list.

5. Remove all the cues in missed cues that are also in the media element's list of newly introduced cues, and then empty the element's list of newly introduced cues.

6. If the time was reached through the usual monotonic increase of the current playback position during normal playback, and if the user agent has not fired a timeupdate event at the element in the past 15 to 250ms and is not still running event handlers for such an event, then the user agent must queue a task to fire a simple event named timeupdate at the element. (In the other cases, such as explicit seeks, relevant events get fired as part of the overall process of changing the current playback position.)

   The event thus is not to be fired faster than about 66Hz or slower than 4Hz (assuming the event handlers don't take longer than 250ms to run). User agents are encouraged to vary the frequency of the event based on the system load and the average cost of processing the event each time, so that the UI updates are not any more frequent than the user agent can comfortably handle while decoding the video.

7. If all of the cues in current cues have their text track cue active flag set, none of the cues in other cues have their text track cue active flag set, and missed cues is empty, then abort these steps.

8. If the time was reached through the usual monotonic increase of the current playback position during normal playback, and there are cues in other cues that have their text track cue pause-on-exit flag set and that either have their text track cue active flag set or are also in missed cues, then immediately pause the media element.

   In the other cases, such as explicit seeks, playback is not paused by going past the end time of a cue, even if that cue has its text track cue pause-on-exit flag set.

9. Let events be a list of tasks, initially empty. Each task in this list will be associated with a text track, a text track cue, and a time, which are used to sort the list before the tasks are queued.

   Let affected tracks be a list of text tracks, initially empty.

   When the steps below say to prepare an event named event for a text track cue target with a time time, the user agent must run these substeps:

   1. Let track be the text track with which the text track cue target is associated.

   2. Create a task to fire a simple event named event at target.

   3. Add the newly created task to events, associated with the time time, the text track track, and the text track cue target.

   4. Add track to affected tracks.

10. For each text track cue in missed cues, prepare an event named enter for the TextTrackCue object with the text track cue start time.

11. For each text track cue in other cues that either has its text track cue active flag set or is in missed cues, prepare an event named exit for the TextTrackCue object with the later of the text track cue end time and the text track cue start time.

12. For each text track cue in current cues that does not have its text track cue active flag set, prepare an event named enter for the TextTrackCue object with the text track cue start time.

13. Sort the tasks in events in ascending time order (tasks with earlier times first).

    Further sort tasks in events that have the same time by the relative text track cue order of the text track cues associated with these tasks.

    Finally, sort tasks in events that have the same time and same text track cue order by placing tasks that fire enter events before those that fire exit events.

14. Queue each task in events, in list order.

15. Sort affected tracks in the same order as the text tracks appear in the media element's list of text tracks, and remove duplicates.

16. For each text track in affected tracks, in the list order, queue a task to fire a simple event named cuechange at the TextTrack object, and, if the text track has a corresponding track element, to then fire a simple event named cuechange at the track element as well.

17. Set the text track cue active flag of all the cues in the current cues, and unset the text track cue active flag of all the cues in the other cues.

18. Run the rules for updating the text track rendering of each of the text tracks in affected tracks that are showing. For example, for text tracks based on WebVTT, the rules for updating the display of WebVTT text tracks. [[!WEBVTT]]

For the purposes of the algorithm above, a text track cue is considered to be part of a text track only if it is listed in the text track list of cues, not merely if it is associated with the text track.

If the media element's node document stops being a fully active document, then the playback will stop until the document is active again.

When a media element is removed from a Document, the user agent must run the following steps:

1. Await a stable state, allowing the task that removed the media element from the Document to continue. The synchronous section consists of all the remaining steps of this algorithm. (Steps in the synchronous section are marked with ⌛.)

2. ⌛ If the media element is in a Document, abort these steps.

3. ⌛ Run the internal pause steps for the media element.

Seeking

media . seeking

Returns true if the user agent is currently seeking.

media . seekable

Returns a TimeRanges object that represents the ranges of the media resource to which it is possible for the user agent to seek.

media . fastSeek( time )

Seeks to near the given time as fast as possible, trading precision for speed. (To seek to a precise time, use the currentTime attribute.)

This does nothing if the media resource has not been loaded.

The seeking attribute must initially have the value false.

The fastSeek() method must seek to the time given by the method's argument, with the approximate-for-speed flag set.

When the user agent is required to seek to a particular new playback position in the media resource, optionally with the approximate-for-speed flag set, it means that the user agent must run the following steps. This algorithm interacts closely with the event loop mechanism; in particular, it has a synchronous section (which is triggered as part of the event loop algorithm). Steps in that section are marked with ⌛.

1. Set the media element's show poster flag to false.

2. If the media element's readyState is HAVE_NOTHING, abort these steps.

3. If the element's seeking IDL attribute is true, then another instance of this algorithm is already running. Abort that other instance of the algorithm without waiting for the step that it is running to complete.

4. Set the seeking IDL attribute to true.

5. If the seek was in response to a DOM method call or setting of an IDL attribute, then continue the script. The remainder of these steps must be run in parallel. With the exception of the steps marked with ⌛, they could be aborted at any time by another instance of this algorithm being invoked.

6. If the new playback position is later than the end of the media resource, then let it be the end of the media resource instead.

7. If the new playback position is less than the earliest possible position, let it be that position instead.

8. If the (possibly now changed) new playback position is not in one of the ranges given in the seekable attribute, then let it be the position in one of the ranges given in the seekable attribute that is the nearest to the new playback position. If two positions both satisfy that constraint (i.e. the new playback position is exactly in the middle between two ranges in the seekable attribute) then use the position that is closest to the current playback position. If there are no ranges given in the seekable attribute then set the seeking IDL attribute to false and abort these steps.

9. If the approximate-for-speed flag is set, adjust the new playback position to a value that will allow for playback to resume promptly. If new playback position before this step is before current playback position, then the adjusted new playback position must also be before the current playback position. Similarly, if the new playback position before this step is after current playback position, then the adjusted new playback position must also be after the current playback position.

   For example, the user agent could snap to a nearby key frame, so that it doesn't have to spend time decoding then discarding intermediate frames before resuming playback.

10. Queue a task to fire a simple event named seeking at the element.

11. Set the current playback position to the new playback position.

    If the media element was potentially playing immediately before it started seeking, but seeking caused its readyState attribute to change to a value lower than HAVE_FUTURE_DATA, then a waiting event will be fired at the element.

    This step sets the current playback position, and thus can immediately trigger other conditions, such as the rules regarding when playback "reaches the end of the media resource" (part of the logic that handles looping), even before the user agent is actually able to render the media data for that position (as determined in the next step).

    The currentTime attribute returns the official playback position, not the current playback position, and therefore gets updated before script execution, separate from this algorithm.

12. Wait until the user agent 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.

13. Await a stable state. The synchronous section consists of all the remaining steps of this algorithm. (Steps in the synchronous section are marked with ⌛.)

14. ⌛ Set the seeking IDL attribute to false.

15. ⌛ Run the time marches on steps.

16. ⌛ Queue a task to fire a simple event named timeupdate at the element.

17. ⌛ Queue a task to fire a simple event named seeked at the element.

The seekable attribute must return a new static normalised 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.

If the user agent can seek to anywhere in the media resource, e.g. because it is 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 (the earliest possible position, 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, and might be positive Infinity).

The range might be continuously changing, e.g. if the user agent is buffering a sliding window on an infinite stream. This is the behaviour seen with DVRs viewing live TV, for instance.

User agents should adopt adopt a very liberal and optimistic view of what is seekable. User agents should also buffer recent content where possible to enable seeking to be fast.

For instance, consider a large video file served on an HTTP server without support for HTTP Range requests. A browser could implement this by only buffering the current frame and data obtained for subsequent frames, never allow seeking, except for seeking to the very start by restarting the playback. However, this would be a poor implementation. A high quality implementation would buffer the last few minutes of content (or more, if sufficient storage space is available), allowing the user to jump back and rewatch something surprising without any latency, and would in addition allow arbitrary seeking by reloading the file from the start if necessary, which would be slower but still more convenient than having to literally restart the video and watch it all the way through just to get to an earlier unbuffered spot.

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). If the media element has a current media controller, then the user agent must seek the media controller appropriately instead.

Media resources with multiple media tracks

A media resource can have multiple embedded audio and video tracks. For example, in addition to the primary video and audio tracks, a media resource could have foreign-language dubbed dialogues, director's commentaries, audio descriptions, alternative angles, or sign-language overlays.

media . audioTracks

Returns an AudioTrackList object representing the audio tracks available in the media resource.

media . videoTracks

Returns a VideoTrackList object representing the video tracks available in the media resource.

The audioTracks attribute of a media element must return a live AudioTrackList object representing the audio tracks available in the media element's media resource.

The videoTracks attribute of a media element must return a live VideoTrackList object representing the video tracks available in the media element's media resource.

There are only ever one AudioTrackList object and one VideoTrackList object per media element, even if another media resource is loaded into the element: the objects are reused. (The AudioTrack and VideoTrack objects are not, though.)

<script>
 function loadVideo(url, container) {
   var controller = new MediaController();
   var video = document.createElement('video');
   video.src = url;
   video.autoplay = true;
   video.controls = true;
   video.controller = controller;
   container.appendChild(video);
   video.onloadedmetadata = function (event) {
     for (var i = 0; i < video.videoTracks.length; i += 1) {
       if (video.videoTracks[i].kind == 'sign') {
         var sign = document.createElement('video');
         sign.src = url + '#track=' + video.videoTracks[i].id; 
         sign.autoplay = true;
         sign.controller = controller;
         container.appendChild(sign);
         return;
       }
     }
   };
 }
</script>

interface AudioTrackList : EventTarget {
  readonly attribute unsigned long length;
  getter AudioTrack (unsigned long index);
  AudioTrack? getTrackById(DOMString id);

  attribute EventHandler onchange;
  attribute EventHandler onaddtrack;
  attribute EventHandler onremovetrack;
};

interface AudioTrack {
  readonly attribute DOMString id;
  readonly attribute DOMString kind;
  readonly attribute DOMString label;
  readonly attribute DOMString language;
  attribute boolean enabled;
};

interface VideoTrackList : EventTarget {
  readonly attribute unsigned long length;
  getter VideoTrack (unsigned long index);
  VideoTrack? getTrackById(DOMString id);
  readonly attribute long selectedIndex;

  attribute EventHandler onchange;
  attribute EventHandler onaddtrack;
  attribute EventHandler onremovetrack;
};

interface VideoTrack {
  readonly attribute DOMString id;
  readonly attribute DOMString kind;
  readonly attribute DOMString label;
  readonly attribute DOMString language;
  attribute boolean selected;
};

<video src="myvideo#track=Alternative"></video>

Synchronising multiple media elements

enum MediaControllerPlaybackState { "waiting", "playing", "ended" };
[Constructor]
interface MediaController : EventTarget {
  readonly attribute unsigned short readyState; // uses HTMLMediaElement.readyState's values

  readonly attribute TimeRanges buffered;
  readonly attribute TimeRanges seekable;
  readonly attribute unrestricted double duration;
  attribute double currentTime;

  readonly attribute boolean paused;
  readonly attribute MediaControllerPlaybackState playbackState;
  readonly attribute TimeRanges played;
  void pause();
  void unpause();
  void play(); // calls play() on all media elements as well

  attribute double defaultPlaybackRate;
  attribute double playbackRate;

  attribute double volume;
  attribute boolean muted;

  attribute EventHandler onemptied;
  attribute EventHandler onloadedmetadata;
  attribute EventHandler onloadeddata;
  attribute EventHandler oncanplay;
  attribute EventHandler oncanplaythrough;
  attribute EventHandler onplaying;
  attribute EventHandler onended;
  attribute EventHandler onwaiting;

  attribute EventHandler ondurationchange;
  attribute EventHandler ontimeupdate;
  attribute EventHandler onplay;
  attribute EventHandler onpause;
  attribute EventHandler onratechange;
  attribute EventHandler onvolumechange;
};

<article>
 <style scoped>
  div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
  video { position; absolute; bottom: 0; right: 0; }
  video:first-child { width: 100%; height: 100%; }
  video:last-child { width: 30%; }
 </style>
 <div>
  <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
  <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
 </div>
</article>

Timed text tracks

interface TextTrackList : EventTarget {
  readonly attribute unsigned long length;
  getter TextTrack (unsigned long index);
  TextTrack? getTrackById(DOMString id);

  attribute EventHandler onchange;
  attribute EventHandler onaddtrack;
  attribute EventHandler onremovetrack;
};

enum TextTrackMode { "disabled",  "hidden",  "showing" };
enum TextTrackKind { "subtitles",  "captions",  "descriptions",  "chapters",  "metadata" };
interface TextTrack : EventTarget {
  readonly attribute TextTrackKind kind;
  readonly attribute DOMString label;
  readonly attribute DOMString language;

  readonly attribute DOMString id;
  readonly attribute DOMString inBandMetadataTrackDispatchType;

  attribute TextTrackMode mode;

  readonly attribute TextTrackCueList? cues;
  readonly attribute TextTrackCueList? activeCues;

  void addCue(TextTrackCue cue);
  void removeCue(TextTrackCue cue);

  attribute EventHandler oncuechange;
};

var sfx = new Audio('sfx.wav');
var sounds = sfx.addTextTrack('metadata');

// add sounds we care about
function addFX(start, end, name) {
  var cue = new VTTCue(start, end, '');
  cue.id = name;
  cue.pauseOnExit = true;
  sounds.addCue(cue);
}
addFX(12.783, 13.612, 'dog bark');
addFX(13.612, 15.091, 'kitten mew'))

function playSound(id) {
  sfx.currentTime = sounds.getCueById(id).startTime;
  sfx.play();
}

// play a bark as soon as we can
sfx.oncanplaythrough = function () {
  playSound('dog bark');
}
// meow when the user tries to leave
window.onbeforeunload = function () {
  playSound('kitten mew');
  return 'Are you sure you want to leave this awesome page?';
}

interface TextTrackCueList {
  readonly attribute unsigned long length;
  getter TextTrackCue (unsigned long index);
  TextTrackCue? getCueById(DOMString id);
};

interface TextTrackCue : EventTarget {
  readonly attribute TextTrack? track;

  attribute DOMString id;
  attribute double startTime;
  attribute double endTime;
  attribute boolean pauseOnExit;

  attribute EventHandler onenter;
  attribute EventHandler onexit;
};

[Constructor(double startTime, double endTime, ArrayBuffer data)]
   interface DataCue : TextTrackCue {
               attribute ArrayBuffer data;
};

WEBVTT

00:00:00.000 --> 00:50:00.000
Astrophysics

00:00:00.000 --> 00:10:00.000
Introduction to Astrophysics

00:10:00.000 --> 00:45:00.000
The Solar System

00:00:00.000 --> 00:10:00.000
Coursework Description

00:50:00.000 --> 01:40:00.000
Computational Physics

00:50:00.000 --> 00:55:00.000
Introduction to Programming

00:55:00.000 --> 01:30:00.000
Data Structures

01:30:00.000 --> 01:35:00.000
Answers to Last Exam

01:35:00.000 --> 01:40:00.000
Coursework Description

01:40:00.000 --> 02:30:00.000
General Relativity

01:40:00.000 --> 02:00:00.000
Tensor Algebra

02:00:00.000 --> 02:30:00.000
The General Relativistic Field Equations

WEBVTT

...

05:10:00.000 --> 05:12:15.000
matchtype:qual
matchnumber:37

...

05:11:02.251 --> 05:11:17.198
red:78

05:11:03.672 --> 05:11:54.198
blue:66

05:11:17.198 --> 05:11:25.912
red:80

05:11:25.912 --> 05:11:26.522
red:83

05:11:26.522 --> 05:11:26.982
red:86

05:11:26.982 --> 05:11:27.499
red:89

...