1. 4.8.8 The video element
      2. 4.8.9 The audio element
      3. 4.8.10 The track element
      4. 4.8.11 Media elements
        1. 4.8.11.1 Error codes
        2. 4.8.11.2 Location of the media resource
        3. 4.8.11.3 MIME types
        4. 4.8.11.4 Network states
        5. 4.8.11.5 Loading the media resource
        6. 4.8.11.6 Offsets into the media resource
        7. 4.8.11.7 Ready states
        8. 4.8.11.8 Playing the media resource
        9. 4.8.11.9 Seeking
        10. 4.8.11.10 Media resources with multiple media tracks
          1. 4.8.11.10.1 AudioTrackList and VideoTrackList objects
          2. 4.8.11.10.2 Selecting specific audio and video tracks declaratively
        11. 4.8.11.11 Timed text tracks
          1. 4.8.11.11.1 Text track model
          2. 4.8.11.11.2 Sourcing in-band text tracks
          3. 4.8.11.11.3 Sourcing out-of-band text tracks
          4. 4.8.11.11.4 Guidelines for exposing cues in various formats as text track cues
          5. 4.8.11.11.5 Text track API
          6. 4.8.11.11.6 Event handlers for objects of the text track APIs
          7. 4.8.11.11.7 Best practices for metadata text tracks
        12. 4.8.11.12 Identifying a track kind through a URL
        13. 4.8.11.13 User interface
        14. 4.8.11.14 Time ranges
        15. 4.8.11.15 The TrackEvent interface
        16. 4.8.11.16 Events summary
        17. 4.8.11.17 Security and privacy considerations
        18. 4.8.11.18 Best practices for authors using media elements
        19. 4.8.11.19 Best practices for implementers of media elements

4.8.8 The video element

Element/video

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android?

HTMLVideoElement

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+
Categories:
Flow content.
Phrasing content.
Embedded content.
If the element has a controls attribute: Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
If the element has a src attribute: zero or more track elements, then transparent, but with no media element descendants.
If the element does not have a src attribute: zero or more source elements, then zero or more track elements, then transparent, but with no media element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
crossorigin — How the element handles crossorigin requests
poster — Poster frame to show prior to video playback
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
playsinline — Encourage the user agent to display video content within the element's playback area
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
loading — Used when determining loading deferral
width — Horizontal dimension
height — Vertical dimension
Accessibility considerations:
For authors.
For implementers.
Sanitization:
Uncategorized.
DOM interface:
[Exposed=Window]
interface HTMLVideoElement : HTMLMediaElement {
  [HTMLConstructor] constructor();

  [CEReactions, Reflect] attribute unsigned long width;
  [CEReactions, Reflect] attribute unsigned long height;
  readonly attribute unsigned long videoWidth;
  readonly attribute unsigned long videoHeight;
  [CEReactions, ReflectURL] attribute USVString poster;
  [CEReactions, Reflect] attribute boolean playsInline;

};

A video element is used for playing videos or movies, and audio files with captions.

Content may be provided inside the video element. User agents should not show this content to the user; it is intended for older web browsers which do not support video, so that text can be shown to the users of these older browsers informing them of how to access the video contents.

In particular, this content is not intended to address accessibility concerns. To make video content accessible to the partially sighted, the blind, the hard-of-hearing, the deaf, and those with other physical or cognitive disabilities, a variety of features are available. Captions can be provided, either embedded in the video stream or as external files using the track element. Sign-language tracks can be embedded in the video stream. Audio descriptions can be embedded in the video stream or in text form using a WebVTT file referenced using the track element and synthesized into speech by the user agent. WebVTT can also be used to provide chapter titles. For users who would rather not use a media element at all, transcripts or other textual alternatives can be provided by simply linking to them in the prose near the video element. [WEBVTT]

The video element is a media element whose media data is ostensibly video data, possibly with associated audio data.

The video element has an internal shadow tree with no slot elements.

The src, crossorigin, preload, autoplay, loop, muted, and controls attributes are the attributes common to all media elements.

The poster attribute gives the URL of an image file that the user agent can show while no video data is available. The attribute, if present, must contain a valid non-empty URL potentially surrounded by spaces.

If the specified resource is to be used, then, when the element is created or when the poster attribute is set, changed, or removed, the user agent must run the following steps to determine the element's poster frame (regardless of the value of the element's show poster flag):

  1. If there is an existing instance of this algorithm running for this video element, abort that instance of this algorithm without changing the poster frame.

  2. If the poster attribute's value is the empty string or if the attribute is absent:

    1. Set the video element's poster lazy load resumption steps to null.

    2. There is no poster frame; return.

  3. Let url be the result of encoding-parsing a URL given the poster attribute's value, relative to the element's node document.

  4. If url is failure, then return. There is no poster frame.

  5. Let request be a new request whose URL is url, client is the element's node document's relevant settings object, destination is "image", initiator type is "video", credentials mode is "include", and whose use-URL-credentials flag is set.

  6. If the will lazy load element steps given the video return true:

    1. Let posterResumptionSteps be the rest of this algorithm starting with the step labeled Fetch.

    2. Set the video element's poster lazy load resumption steps to posterResumptionSteps.

    3. Return.

  7. Fetch request. This must delay the load event of the element's node document.

  8. If an image is thus obtained, the poster frame is that image. Otherwise, there is no poster frame.

The image given by the poster attribute, the poster frame, is intended to be a representative frame of the video (typically one of the first non-blank frames) that gives the user an idea of what the video is like.

The playsinline attribute is a boolean attribute. If present, it serves as a hint to the user agent that the video ought to be displayed "inline" in the document by default, constrained to the element's playback area, instead of being displayed fullscreen or in an independent resizable window.

The absence of the playsinline attribute does not imply that the video will display fullscreen by default. Indeed, most user agents have chosen to play all videos inline by default, and in such user agents the playsinline attribute has no effect.

If the poster attribute is present and the loading attribute is in the Lazy state, the user agent must defer loading the poster image source data until the element's lazy load resumption steps are invoked.

<video src="1.mp4" poster="1.jpg" type="video/mp4">
<video src="2.mp4" type="video/mp4" loading="eager">
<video src="3.mp4" type="video/mp4" loading="lazy">
<video src="4.mp4" type="video/mp4" loading="lazy" autoplay>
<div id="very-large"></div> <!-- Everything after this div is below the viewport -->
<video src="5.mp4" type="video/mp4">
<video src="6.mp4" type="video/mp4" loading="lazy">
<video src="7.mp4" type="video/mp4" autoplay loading="lazy">
<video src="8.mp4" type="video/mp4" poster="8.jpg" loading="lazy">
<video src="9.mp4" type="video/mp4" preload="none" poster="9.jpg" loading="lazy">
<video src="10.mp4" type="video/mp4" preload="metadata" loading="lazy">
<video src="11.mp4" type="video/mp4" poster="11.jpg" preload="none" loading="eager">

In the example above, the videos load as follows:

1.mp4

The video and poster image load eagerly and delay the window's load event.

2.mp4, 5.mp4

The videos load eagerly and delay the window's load event.

3.mp4

The video loads when layout is known, due to being in the viewport, however it does not delay the window's load event.

4.mp4

The video loads and autoplay playback begins when layout is known, due to being in the viewport, however it does not delay the window's load event.

6.mp4

The video loads only once scrolled into the viewport, and does not delay the window's load event.

7.mp4

The video loads and autoplay playback begins only once scrolled into the viewport, and does not delay the window's load event.

8.mp4

The video and poster image load only once scrolled into the viewport, and does not delay the window's load event.

9.mp4

The video does not load until played. The poster image loads only once scrolled into the viewport, and does not delay the window's load event.

10.mp4

The video's metadata loads only once scrolled into the viewport, and does not delay the window's load event.

11.mp4

The video does not load until played. The poster image loads eagerly and delays the window's load event.


A video element represents what is given for the first matching condition in the list below:

When no video data is available (the element's readyState attribute is either HAVE_NOTHING, or HAVE_METADATA but no video data has yet been obtained at all, or the element's readyState attribute is any subsequent value but the media resource does not have a video channel)
The video element represents its poster frame, if any, or else transparent black with no natural dimensions.
When the video element is paused, the current playback position is the first frame of video, and the element's show poster flag is set
The video element represents its poster frame, if any, or else the first frame of the video.
When the video element is paused, and the frame of video corresponding to the current playback position is not available (e.g. because the video is seeking or buffering)
When the video element is neither potentially playing nor paused (e.g. when seeking or stalled)
The video element represents the last frame of the video to have been rendered.
When the video element is paused
The video element represents the frame of video corresponding to the current playback position.
Otherwise (the video element has a video channel and is potentially playing)
The video element represents the frame of video at the continuously increasing "current" position. When the current playback position changes such that the last frame rendered is no longer the frame corresponding to the current playback position in the video, the new frame must be rendered.

Frames of video must be obtained from the video track that was selected when the event loop last reached step 1.

Which frame in a video stream corresponds to a particular playback position is defined by the video stream's format.

The video element also represents any text track cues whose text track cue active flag is set and whose text track is in the showing mode, and any audio from the media resource, at the current playback position.

Any audio associated with the media resource must, if played, be played synchronized with the current playback position, at the element's effective media volume. The user agent must play the audio from audio tracks that were enabled when the event loop last reached step 1.

In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.

User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.

When a video element's media resource has a video channel, the element provides a paint source whose width is the media resource's natural width, whose height is the media resource's natural height, and whose appearance is the frame of video corresponding to the current playback position, if that is available, or else (e.g. when the video is seeking or buffering) its previous appearance, if any, or else (e.g. because the video is still loading the first frame) blackness.


video.videoWidth

HTMLVideoElement/videoWidth

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+
video.videoHeight

HTMLVideoElement/videoHeight

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+

These attributes return the natural dimensions of the video, or 0 if the dimensions are not known.

The natural width and natural height of the media resource are the dimensions of the resource in CSS pixels after taking into account the resource's dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for the format used by the resource. If an anamorphic format does not define how to apply the aspect ratio to the video data's dimensions to obtain the "correct" dimensions, then the user agent must apply the ratio by increasing one dimension and leaving the other unchanged.

The videoWidth getter steps are:

  1. If this's readyState attribute is HAVE_NOTHING, then return 0.

  2. Return the natural width of the video in CSS pixels.

The videoHeight getter steps are:

  1. If this's readyState attribute is HAVE_NOTHING, then return 0.

  2. Return the natural height of the video in CSS pixels.

Whenever the natural width or natural height of the video changes (including, for example, because the selected video track was changed), if the element's readyState attribute is not HAVE_NOTHING, the user agent must queue a media element task given the media element to fire an event named resize at the media element.

The video element supports dimension attributes.

In the absence of style rules to the contrary, video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area that do not contain the video represent nothing.

In user agents that implement CSS, the above requirement can be implemented by using the style rule suggested in the Rendering section.

The natural width of a video element's playback area is the natural width of the poster frame, if that is available and the element currently represents its poster frame; otherwise, it is the natural width of the video resource, if that is available; otherwise the natural width is missing.

The natural height of a video element's playback area is the natural height of the poster frame, if that is available and the element currently represents its poster frame; otherwise it is the natural height of the video resource, if that is available; otherwise the natural height is missing.

The default object size is a width of 300 CSS pixels and a height of 150 CSS pixels. [CSSIMAGES]


User agents should provide controls to enable or disable the display of closed captions, audio description tracks, and other additional data associated with the video stream, though such features should, again, not interfere with the page's normal rendering.

User agents may allow users to view the video content in manners more suitable to the user, such as fullscreen or in an independent resizable window. User agents may even trigger such a viewing mode by default upon playing a video, although they should not do so when the playsinline attribute is specified. As with the other user interface features, controls to enable this should not interfere with the page's normal rendering unless the user agent is exposing a user interface. In such an independent viewing mode, however, user agents may make full user interfaces visible, even if the controls attribute is absent.

User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.


This example shows how to detect when a video has failed to play correctly:

<script>
 function failed(e) {
   // video playback failed - show a message saying why
   switch (e.target.error.code) {
     case e.target.error.MEDIA_ERR_ABORTED:
       alert('You aborted the video playback.');
       break;
     case e.target.error.MEDIA_ERR_NETWORK:
       alert('A network error caused the video download to fail part-way.');
       break;
     case e.target.error.MEDIA_ERR_DECODE:
       alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
       break;
     case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
       alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
       break;
     default:
       alert('An unknown error occurred.');
       break;
   }
 }
</script>
<p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
<p><a href="tgif.vid">Download the video file</a>.</p>

4.8.9 The audio element

Element/audio

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android3+Samsung Internet?Opera Android11+

HTMLAudioElement

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+
Categories:
Flow content.
Phrasing content.
Embedded content.
If the element has a controls attribute: Interactive content.
If the element has a controls attribute: Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
If the element has a src attribute: zero or more track elements, then transparent, but with no media element descendants.
If the element does not have a src attribute: zero or more source elements, then zero or more track elements, then transparent, but with no media element descendants.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
src — Address of the resource
crossorigin — How the element handles crossorigin requests
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
loading — Used when determining loading deferral
Accessibility considerations:
For authors.
For implementers.
Sanitization:
Uncategorized.
DOM interface:
[Exposed=Window,
 LegacyFactoryFunction=Audio(optional DOMString src)]
interface HTMLAudioElement : HTMLMediaElement {
  [HTMLConstructor] constructor();
};

An audio element represents a sound or audio stream.

Content may be provided inside the audio element. User agents should not show this content to the user; it is intended for older web browsers which do not support audio, so that text can be shown to the users of these older browsers informing them of how to access the audio contents.

In particular, this content is not intended to address accessibility concerns. To make audio content accessible to the deaf or to those with other physical or cognitive disabilities, a variety of features are available. If captions or a sign language video are available, the video element can be used instead of the audio element to play the audio, allowing users to enable the visual alternatives. Chapter titles can be provided to aid navigation, using the track element and a WebVTT file. And, naturally, transcripts or other textual alternatives can be provided by simply linking to them in the prose near the audio element. [WEBVTT]

The audio element is a media element whose media data is ostensibly audio data.

The audio element has an internal shadow tree with no slot elements.

The src, crossorigin, preload, autoplay, loop, muted, controls, and loading attributes are the attributes common to all media elements.

audio elements without a controls attribute will not be displayed by the user agent, preventing them from lazy loading.

<audio src="1.mp3" type="audio/mpeg" controls>
<audio src="2.mp3" type="audio/mpeg" controls loading="eager">
<audio src="3.mp3" type="audio/mpeg" controls loading="lazy">
<audio src="4.mp3" type="audio/mpeg" controls loading="lazy" autoplay>
<div id="very-large"></div> <!-- Everything after this div is below the viewport -->
<audio src="5.mp3" type="audio/mpeg" controls>
<audio src="6.mp3" type="audio/mpeg" controls loading="lazy">
<audio src="7.mp3" type="audio/mpeg" controls autoplay loading="lazy">
<audio src="8.mp3" type="audio/mpeg" controls preload="metadata" loading="lazy">

In the example above, the audio files load as follows:

1.mp3, 2.mp3, 5.mp3

The audio file loads eagerly and delays the window's load event.

3.mp3

The audio loads when layout is known, due to being in the viewport, however it does not delay the window's load event.

4.mp3

The audio loads and autoplay playback begins when layout is known, due to being in the viewport, however it does not delay the window's load event.

6.mp3

The audio loads only once scrolled into the viewport, and does not delay the window's load event.

7.mp3

The audio loads and autoplay playback begins only once scrolled into the viewport, and does not delay the window's load event.

8.mp3

The audio's metadata loads only once scrolled into the viewport, and does not delay the window's load event.

audio = new Audio([ url ])

HTMLAudioElement/Audio

Support in all current engines.

Firefox3.5+Safari3.1+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

Returns a new audio element, with the src attribute set to the value passed in the argument, if applicable.

A legacy factory function is provided for creating HTMLAudioElement objects (in addition to the factory methods from DOM such as createElement()): Audio(src). When invoked, the legacy factory function must perform the following steps:

  1. Let document be the current global object's associated Document.

  2. Let audio be the result of creating an element given document, "audio", and the HTML namespace.

  3. Set an attribute value for audio using "preload" and "auto".

  4. If src is given, then set an attribute value for audio using "src" and src. (This will cause the user agent to invoke the object's resource selection algorithm before returning.)

  5. Return audio.

4.8.10 The track element

Element/track

Support in all current engines.

Firefox31+Safari6+Chrome23+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android25+WebView Android?Samsung Internet?Opera Android12.1+

HTMLTrackElement

Support in all current engines.

Firefox31+Safari6+Chrome23+
Opera12+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+

HTMLTrackElement/src

Support in all current engines.

Firefox31+Safari6+Chrome23+
Opera12+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+
Categories:
None.
Contexts in which this element can be used:
As a child of a media element, before any flow content.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
kind — The type of text track
src — Address of the resource
srclang — Language of the text track
label — User-visible label
default — Enable the track if no other text track is more suitable
Accessibility considerations:
For authors.
For implementers.
Sanitization:
Uncategorized.
DOM interface:
[Exposed=Window]
interface HTMLTrackElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute DOMString kind;
  [CEReactions, ReflectURL] attribute USVString src;
  [CEReactions, Reflect] attribute DOMString srclang;
  [CEReactions, Reflect] attribute DOMString label;
  [CEReactions, Reflect] attribute boolean default;

  const unsigned short NONE = 0;
  const unsigned short LOADING = 1;
  const unsigned short LOADED = 2;
  const unsigned short ERROR = 3;
  readonly attribute unsigned short readyState;

  readonly attribute TextTrack track;
};

The track element allows authors to specify explicit external timed text tracks for media elements. It does not represent anything on its own.

The kind attribute is an enumerated attribute with the following keywords and states:

Keyword State Brief description
subtitles Subtitles Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the media resource's audio track). Overlaid on the video.
captions Captions Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf). Overlaid on the video; labeled as appropriate for the hard-of-hearing.
descriptions Descriptions Textual descriptions of the video component of the media resource, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind). Synthesized as audio.
chapters Chapters metadata Tracks intended for use from script. Not displayed by the user agent.
metadata Metadata

The attribute's missing value default is the subtitles state, and its invalid value default is the metadata state.

The src attribute gives the URL of the text track data. The value must be a valid non-empty URL potentially surrounded by spaces. This attribute must be present.

The element has an associated track URL (a string), initially the empty string.

When the element's src attribute is set, run these steps:

  1. Let trackURL be failure.

  2. Let value be the element's src attribute value.

  3. If value is not the empty string, then set trackURL to the result of encoding-parsing-and-serializing a URL given value, relative to the element's node document.

  4. Set the element's track URL to trackURL if it is not failure; otherwise to the empty string.

If the element's track URL identifies a WebVTT resource, and the element's kind attribute is not in the chapters metadata or metadata state, then the WebVTT file must be a WebVTT file using cue text. [WEBVTT]

The srclang attribute gives the language of the text track data. The value must be a valid BCP 47 language tag. This attribute must be present if the element's kind attribute is in the subtitles state. [BCP47]

If the element has a srclang attribute whose value is not the empty string, then the element's track language is the value of the attribute. Otherwise, the element has no track language.

The label attribute gives a user-readable title for the track. This title is used by user agents when listing subtitle, caption, and audio description tracks in their user interface.

The value of the label attribute, if the attribute is present, must not be the empty string. Furthermore, there must not be two track element children of the same media element whose kind attributes are in the same state, whose srclang attributes are both missing or have values that represent the same language, and whose label attributes are again both missing or both have the same value.

If the element has a label attribute whose value is not the empty string, then the element's track label is the value of the attribute. Otherwise, the element's track label is an empty string.

The default attribute is a boolean attribute, which, if specified, indicates that the track is to be enabled if the user's preferences do not indicate that another track would be more appropriate.

Each media element must have no more than one track element child whose kind attribute is in the subtitles or captions state and whose default attribute is specified.

Each media element must have no more than one track element child whose kind attribute is in the description state and whose default attribute is specified.

Each media element must have no more than one track element child whose kind attribute is in the chapters metadata state and whose default attribute is specified.

There is no limit on the number of track elements whose kind attribute is in the metadata state and whose default attribute is specified.

track.readyState

Returns the text track readiness state, represented by a number from the following list:

track.NONE (0)

The text track not loaded state.

track.LOADING (1)

The text track loading state.

track.LOADED (2)

The text track loaded state.

track.ERROR (3)

The text track failed to load state.

track.track

Returns the track element's text track.

The readyState attribute must return the numeric value corresponding to the text track readiness state of the track element's text track, as defined by the following list:

NONE (numeric value 0)
The text track not loaded state.
LOADING (numeric value 1)
The text track loading state.
LOADED (numeric value 2)
The text track loaded state.
ERROR (numeric value 3)
The text track failed to load state.

The track getter steps are to return this's text track.

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

This video has subtitles in several languages:

<video src="brave.webm">
 <track kind=subtitles src=brave.en.vtt srclang=en label="English">
 <track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
 <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
 <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
</video>

(The lang attributes on the last two describe the language of the label attribute, not the language of the subtitles themselves. The language of the subtitles is given by the srclang attribute.)

4.8.11 Media elements

HTMLMediaElement objects (audio and video, in this specification) are simply known as media elements.

HTMLMediaElement

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera10.5+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+

HTMLMediaElement/src

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

HTMLMediaElement/autoplay

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

HTMLMediaElement/loop

Support in all current engines.

Firefox11+Safari4+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

HTMLMediaElement/controls

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

HTMLMediaElement/defaultMuted

Support in all current engines.

Firefox11+Safari6+Chrome15+
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+
enum CanPlayTypeResult { "" /* empty string */, "maybe", "probably" };
typedef (MediaStream or MediaSource or Blob) MediaProvider;

[Exposed=Window]
interface HTMLMediaElement : HTMLElement {

  // error state
  readonly attribute MediaError? error;

  // network state
  [CEReactions, ReflectURL] attribute USVString src;
  attribute MediaProvider? srcObject;
  readonly attribute USVString currentSrc;
  [CEReactions] attribute DOMString? crossOrigin;
  const unsigned short NETWORK_EMPTY = 0;
  const unsigned short NETWORK_IDLE = 1;
  const unsigned short NETWORK_LOADING = 2;
  const unsigned short NETWORK_NO_SOURCE = 3;
  readonly attribute unsigned short networkState;
  [CEReactions] attribute DOMString preload;
  readonly attribute TimeRanges buffered;
  undefined load();
  CanPlayTypeResult canPlayType(DOMString type);

  // ready state
  const unsigned short HAVE_NOTHING = 0;
  const unsigned short HAVE_METADATA = 1;
  const unsigned short HAVE_CURRENT_DATA = 2;
  const unsigned short HAVE_FUTURE_DATA = 3;
  const unsigned short HAVE_ENOUGH_DATA = 4;
  readonly attribute unsigned short readyState;
  readonly attribute boolean seeking;

  // playback state
  attribute double currentTime;
  undefined fastSeek(double time);
  readonly attribute unrestricted double duration;
  object getStartDate();
  readonly attribute boolean paused;
  attribute double defaultPlaybackRate;
  attribute double playbackRate;
  attribute boolean preservesPitch;
  readonly attribute TimeRanges played;
  readonly attribute TimeRanges seekable;
  readonly attribute boolean ended;
  [CEReactions, Reflect] attribute boolean autoplay;
  [CEReactions, Reflect] attribute boolean loop;
  Promise<undefined> play();
  undefined pause();

  // controls
  [CEReactions, Reflect] attribute boolean controls;
  attribute double volume;
  attribute boolean muted;
  [CEReactions, Reflect="muted"] attribute boolean defaultMuted;
  [CEReactions] attribute DOMString loading;

  // tracks
  [SameObject] readonly attribute AudioTrackList audioTracks;
  [SameObject] readonly attribute VideoTrackList videoTracks;
  [SameObject] readonly attribute TextTrackList textTracks;
  TextTrack addTextTrack(TextTrackKind kind, optional DOMString label = "", optional DOMString language = "");
};

The media element attributes, src, crossorigin, preload, autoplay, loop, muted, controls, and loading, apply to all media elements. They are defined in this section.

The loading attribute is a lazy loading attribute. Its purpose is to indicate the policy for loading media resources that are outside the viewport.

When the loading attribute's state is changed to the Eager state, the user agent must run these steps:

  1. Let resumptionSteps be the media element's lazy load resumption steps.

  2. Let posterResumptionSteps be null.

    If the media element is a video element, then set posterResumptionSteps to the video element's poster lazy load resumption steps.

  3. If resumptionSteps is null and posterResumptionSteps is null, then return.

  4. If resumptionSteps is not null:

    1. Set the media element's lazy load resumption steps to null.

    2. Invoke resumptionSteps.

  5. If posterResumptionSteps is not null:

    1. Set the video element's poster lazy load resumption steps to null.

    2. Invoke posterResumptionSteps.

The loading IDL attribute must reflect the loading content attribute, limited to only known values.

When the loading attribute is in the Lazy state, it takes precedence over the preload attribute by deferring data fetching.

If the autoplay attribute is present and the loading attribute is in the Lazy state, the user agent must also defer starting playback (and any associated network requests autoplay can introduce) until the element's lazy load resumption steps are invoked.

Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video. The term media resource is used to refer to the complete set of media data, e.g. the complete video file, or complete audio file.

A media resource has an associated origin, which is either "none", "multiple", "rewritten", or an origin. It is initially set to "none".

A media resource can have multiple audio and video tracks. For the purposes of a media element, the video data of the media resource is only that of the currently selected track (if any) as given by the element's videoTracks attribute when the event loop last reached step 1, and the audio data of the media resource is the result of mixing all the currently enabled tracks (if any) given by the element's audioTracks attribute when the event loop last reached step 1.

Both audio and video elements can be used for both audio and video. The main difference between the two is simply that the audio element has no playback area for visual content (such as video or captions), whereas the video element does.

Each media element has a unique media element event task source.

To queue a media element task with a media element element and a series of steps steps, queue an element task on the media element's media element event task source given element and steps.

4.8.11.1 Error codes

MediaError

Support in all current engines.

Firefox4+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+
media.error

HTMLMediaElement/error

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

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.

[Exposed=Window]
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;
  readonly attribute DOMString message;
};
media.error.code

MediaError/code

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

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

media.error.message

MediaError/message

Support in all current engines.

Firefox52+Safari15+Chrome59+
Opera?Edge79+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

Returns a specific informative diagnostic message about the error condition encountered. The message and message format are not generally uniform across different user agents. If no such message is available, then the empty string is returned.

Every MediaError object has a message, which is a string, and a code, which is 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.

To create a MediaError, given an error code which is one of the above values, return a new MediaError object whose code is the given error code and whose message is a string containing any details the user agent is able to supply about the cause of the error condition, or the empty string if the user agent is unable to supply such details. This message string must not contain only the information already available via the supplied error code; for example, it must not simply be a translation of the code into a string format. If no additional information is available beyond that provided by the error code, the message must be set to the empty string.

The code getter steps are to return this's code.

The message getter steps are to return this's message.

4.8.11.2 Location of the media resource

The src content attribute on media elements gives the URL 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.)

HTMLMediaElement/crossOrigin

Support in all current engines.

Firefox22+Safari10+Chrome33+
Opera?Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

The crossOrigin IDL attribute must reflect the crossorigin content attribute, limited to only known values.

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

Each media element has an assigned media provider object, which is a media provider object or null, initially null.

media.srcObject [ = source ]

HTMLMediaElement/srcObject

Support in one engine only.

Firefox🔰 42+Safari11+Chrome🔰 108+
Opera?Edge🔰 108+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

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

media.currentSrc

HTMLMediaElement/currentSrc

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+

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

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

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 getter steps are to return this's assigned media provider object.

The srcObject setter steps are:

  1. Set this's assigned media provider object to the given value.

  2. Invoke this'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.

4.8.11.3 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 recognize the container type, or it doesn't support the listed codecs.

The MIME type "application/octet-stream" with no parameters is never a type that the user agent knows it cannot render. User agents must treat that type as equivalent to the lack of any ex