HTML5 Edition for Web Authors revision 1.4519

4.8.6 The video element

ISSUE-9 (video-accessibility) blocks progress to Last Call

Categories

Flow content.

Phrasing content.

Embedded content.

If the element has a controls attribute: Interactive 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: one or more source elements, then zero or more track elements, then transparent, but with no media element descendants.

Content attributes:

Global attributes

src

poster

preload

autoplay

loop

audio

controls

width

height

DOM interface:

interface HTMLVideoElement : HTMLMediaElement {
           attribute unsigned long width;
           attribute unsigned long height;
  readonly attribute unsigned long videoWidth;
  readonly attribute unsigned long videoHeight;
           attribute DOMString poster;
           attribute boolean audio; 
};

A video element is used for playing videos or movies.

Content may be provided inside the video element; it is intended for older Web browsers which do not support video, so that legacy video plugins can be tried, or to show text to the users of these older browsers informing them of how to access the video contents.

In particular, this content is not intended to address accessibility concerns. To make video content accessible to the blind, deaf, and those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as caption or subtitle tracks, audio description tracks, or sign-language overlays) into their media streams.

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

The src, preload, autoplay, loop, and controls attributes are the attributes common to all media elements. The audio attribute controls the audio channel.

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

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

video . videoWidth

video . videoHeight

These attributes return the intrinsic dimensions of the video, or zero if the dimensions are not known.

The video element supports dimension attributes.

<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.7 The audio element

Categories

Flow content.

Phrasing content.

Embedded content.

If the element has a controls attribute: Interactive 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: one or more source elements, then zero or more track elements, then transparent, but with no media element descendants.

Content attributes:

Global attributes

src

preload

autoplay

loop

controls

DOM interface:

[NamedConstructor=Audio(),
 NamedConstructor=Audio(in DOMString src)]
interface HTMLAudioElement : HTMLMediaElement {};

An audio element represents a sound or audio stream.

Content may be provided inside the audio element; it is intended for older Web browsers which do not support audio, so that legacy audio plugins can be tried, or to show text to the users of these older browsers informing them of how to access the audio contents.

In particular, this content is not intended to address accessibility concerns. To make audio content accessible to the deaf or to those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as transcriptions) into their media streams.

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

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

audio = new Audio( [ url ] )

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

4.8.8 The source element

Categories

None.

Contexts in which this element can be used:

As a child of a media element, before any flow content or track elements.

Content model:

Empty.

Content attributes:

Global attributes

src

type

media

DOM interface:

interface HTMLSourceElement : HTMLElement {
           attribute DOMString src;
           attribute DOMString type;
           attribute DOMString media;
};

The source element allows authors to specify multiple alternative media resources for media elements. It does not represent anything on its own.

The src attribute gives the address of the media resource. The value must be a valid non-empty URL potentially surrounded by spaces. This attribute must be present.

Dynamically modifying a source element and its attribute when the element is already inserted in a video or audio element will have no effect. To change what is playing, either just use the src attribute on the media element directly, or call the load() method on the media element after manipulating the source elements.

The type attribute gives the type of the media resource, to help the user agent determine if it can play this media resource before fetching it. If specified, its value must be a valid MIME type. The codecs parameter, which certain MIME types define, might be necessary to specify exactly how the resource is encoded. [RFC4281]

The media attribute gives the intended media type of the media resource, to help the user agent determine if this media resource is useful to the user before fetching it. Its value must be a valid media query.

The default, if the media attribute is omitted, is "all", meaning that by default the media resource is suitable for all media.

<script>
 function fallback(video) {
   // replace <video> with its contents
   while (video.hasChildNodes()) {
     if (video.firstChild instanceof HTMLSourceElement)
       video.removeChild(video.firstChild);
     else
       video.parentNode.insertBefore(video.firstChild, video);
   }
   video.parentNode.removeChild(video);
 }
</script>
<video controls autoplay>
 <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
 <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
         onerror="fallback(parentNode)">
 ...
</video>

4.8.9 The track element

ISSUE-9 (video-accessibility) blocks progress to Last Call

Categories

None.

Contexts in which this element can be used:

As a child of a media element, before any flow content.

Content model:

Empty.

Content attributes:

Global attributes

kind

src

charset

srclang

label

DOM interface:

interface HTMLTrackElement : HTMLElement {
           attribute DOMString kind;
           attribute DOMString src;
           attribute DOMString charset;
           attribute DOMString srclang;
           attribute DOMString label;

  readonly attribute TimedTrack track;
};

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

The kind attribute is an enumerated attribute. The following table lists the keywords defined for this attribute. The keyword given in the first cell of each row maps to the state given in the second cell.

The attribute may be omitted. The missing value default is the subtitles state.

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

If the elements's track URL identifies a WebSRT resource, and the element's kind attribute is not in the metadata state, then the WebSRT file must be a WebSRT file using cue text.

If the elements's track URL identifies a WebSRT resource, then the charset attribute may be specified. If the attribute is set, its value must be a valid character encoding name, must be an ASCII case-insensitive match for the preferred MIME name for that encoding, and must match the character encoding of the WebSRT file. [IANACHARSET]

The srclang attribute gives the language of the timed 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]

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.

track . track

Returns the TimedTrack object corresponding to the timed track of the track element.

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

4.8.10 Media elements

Media elements (audio and video, in this specification) implement the following interface:

interface HTMLMediaElement : HTMLElement {

  // error state
  readonly attribute MediaError error;

  // network state
           attribute DOMString src;
  readonly attribute DOMString currentSrc;
  const unsigned short NETWORK_EMPTY = 0;
  const unsigned short NETWORK_IDLE = 1;
  const unsigned short NETWORK_LOADING = 2;
  const unsigned short NETWORK_NO_SOURCE = 3;
  readonly attribute unsigned short networkState;
           attribute DOMString preload;
  readonly attribute TimeRanges buffered;
  void load();
  DOMString canPlayType(in DOMString type);

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

  // playback state
           attribute double currentTime;
  readonly attribute double initialTime;
  readonly attribute double duration;
  readonly attribute Date startOffsetTime;
  readonly attribute boolean paused;
           attribute double defaultPlaybackRate;
           attribute double playbackRate;
  readonly attribute TimeRanges played;
  readonly attribute TimeRanges seekable;
  readonly attribute boolean ended;
           attribute boolean autoplay;
           attribute boolean loop;
  void play();
  void pause();

  // controls
           attribute boolean controls;
           attribute double volume;
           attribute boolean muted;

  // timed tracks
  readonly attribute TimedTrack[] tracks;
  MutableTimedTrack addTrack(in DOMString kind, in optional DOMString label, in optional DOMString language);

};

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

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

4.8.10.1 Error codes

media . error

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

Returns null if there is no error.

interface MediaError {
  const unsigned short MEDIA_ERR_ABORTED = 1;
  const unsigned short MEDIA_ERR_NETWORK = 2;
  const unsigned short MEDIA_ERR_DECODE = 3;
  const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
  readonly attribute unsigned short code;
};

media . error . code

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

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 was not suitable.

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

media . currentSrc

Returns the address of the current media resource.

Returns the empty string when there is no media resource.

There are two ways to specify a media resource, the src attribute, or source elements. The attribute overrides the elements.

4.8.10.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.) [RFC4281]

Types are usually somewhat incomplete descriptions; for example "video/mpeg" doesn't say anything except what the container type is, and even a type like "video/mp4; codecs="avc1.42E01E, mp4a.40.2"" doesn't include information like the actual bitrate (only the maximum bitrate). Thus, given a type, a user agent can often only know whether it might be able to play media of that type (with varying levels of confidence), or whether it definitely cannot play media of that type.

A type that the user agent knows it cannot render is one that describes a resource that the user agent definitely does not support, for example because it doesn't recognize the container type, or it doesn't support the listed codecs.

The MIME type "application/octet-stream" with no parameters is never a type that the user agent knows it cannot render. User agents must treat that type as equivalent to the lack of any explicit Content-Type metadata when it is used to label a potential media resource.

In the absence of a specification to the contrary, the MIME type "application/octet-stream" when used with parameters, e.g. "application/octet-stream;codecs=theora", is a type that the user agent knows it cannot render, since that parameter is not defined for that type.

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.

<section id="video">
 <p><a href="playing-cats.nfv">Download video</a></p>
</section>
<script>
 var videoSection = document.getElementById('video');
 var videoElement = document.createElement('video');
 var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
 if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) {
   // not confident of browser support
   // but we have a plugin
   // so use plugin instead
   videoElement = document.createElement("embed");
 } else if (support == "") {
   // no support from browser and no plugin
   // do nothing
   videoElement = null;
 }
 if (videoElement) {
   while (videoSection.hasChildNodes())
     videoSection.removeChild(videoSection.firstChild);
   videoElement.setAttribute("src", "playing-cats.nfv");
   videoSection.appendChild(videoElement);
 }
</script>

The type attribute of the source element allows the user agent to avoid downloading resources that use formats it cannot render.

4.8.10.4 Network states

media . networkState

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

NETWORK_EMPTY (numeric value 0)

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

NETWORK_IDLE (numeric value 1)

The element 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 has so not yet found a resource to use.

4.8.10.5 Loading the media resource

media . load()

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

The preload attribute is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.

The empty string is also a valid keyword, and maps to the Automatic state. The attribute's missing value default is user-agent defined, though the Metadata state is suggested as a compromise between reducing server load and providing an optimal user experience.

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

4.8.10.6 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 current playback position, in seconds.

Can be set, to seek to the given time.

Will throw an INVALID_STATE_ERR exception if there is no selected media resource. Will throw an INDEX_SIZE_ERR exception if the given time is not within the ranges to which the user agent can seek.

media . initialTime

Returns the initial playback position, that is, time to which the media resource was automatically seeked when it was loaded. Returns zero if the initial playback position is still unknown.

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.

4.8.10.7 The 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.

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 raise an exception when seeking. No media data is available for the immediate current playback position. The timed tracks are ready.

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; 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. For example, in video this corresponds to the user agent having data for at least the current frame and the next frame. The user agent cannot be in this state if playback has ended, as the current playback position can never advance in this case.

HAVE_ENOUGH_DATA (numeric value 4)

All the conditions described for the HAVE_FUTURE_DATA state are met, and, in addition, the user agent estimates that data is being fetched at a rate where the current playback position, if it were to advance at the rate given by the defaultPlaybackRate attribute, would not overtake the available data before playback reaches the end of the media resource.

It is possible for the ready state of a media element to jump between these states discontinuously. For example, the state of a media element can jump straight from HAVE_METADATA to HAVE_ENOUGH_DATA without passing through the HAVE_CURRENT_DATA and HAVE_FUTURE_DATA states.

The autoplay attribute is a boolean attribute. When present, the user agent will automatically begin playback of the media resource as soon as it can do so without stopping.

Authors are urged to use the autoplay attribute rather than using script to trigger automatic playback, as this allows the user to override the automatic playback when it is not desired, e.g. when using a screen reader. Authors are also encouraged to consider not using the automatic playback behavior at all, and instead to let the user agent wait for the user to start playback explicitly.

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

media . playbackRate [ = value ]

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

Can be set, to change the rate of playback.

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.

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

4.8.10.10 Timed tracks

ISSUE-9 (video-accessibility) blocks progress to Last Call

4.8.10.10.1 Timed track model

A media element can have a group of associated timed tracks, known as the media element's list of timed tracks. The timed tracks are sorted as follows:

1. The timed tracks corresponding to track element children of the media element, in tree order.
2. Any timed tracks added using the addTrack() method, in the order they were added, oldest first.
3. Any media-resource-specific timed tracks (timed tracks corresponding to data in the media resource), in the order defined by the media resource's format specification.

A timed track consists of:

The kind of timed track

This decides how the track is handled by the user agent. The kind is represented by a string. The possible strings are:

• subtitles
• captions
• descriptions
• chapters
• metadata

The kind of track can change dynamically, in the case of a timed track corresponding to a track element.

A label

This is a human-readable string intended to identify the track for the user. In certain cases, the label might be generated automatically.

The label of a track can change dynamically, in the case of a timed track corresponding to a track element or in the case of an automatically-generated label whose value depends on variable factors such as the user's preferred user interface language.

A language

This is a string (a BCP 47 language tag) representing the language of the timed track's cues. [BCP47]

The language of a timed track can change dynamically, in the case of a timed track corresponding to a track element.

A readiness state

One of the following:

Not loaded

Indicates that the timed track is known to exist (e.g. it has been declared with a track element), but its cues have not been obtained.

Loading

Indicates that the timed track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track.

Loaded

Indicates that the timed track has been loaded with no fatal errors. No new cues will be added to the track except if the timed track corresponds to a MutableTimedTrack object.

Failed to load

Indicates that the timed track was enabled, but when the user agent attempted to obtain it, this failed in some way (e.g. URL could not be resolved, network error, unknown timed track format). Some or all of the cues are likely missing and will not be obtained.

The readiness state of a timed track changes dynamically as the track is obtained.

A mode

One of the following:

Disabled

Indicates that the timed track is not active. Other than for the purposes of exposing the track in the DOM, the user agent is ignoring the timed track. No cues are active, no events are fired, and the user agent will not attempt to obtain the track's cues.

Hidden

Indicates that the timed track is active, but that the user agent is not actively displaying the cues. If no attempt has yet been made to obtain the track's cues, the user agent will perform such an attempt momentarily. The user agent is maintaining a list of which cues are active, and events are being fired accordingly.

Showing

Indicates that the timed track is active. If no attempt has yet been made to obtain the track's cues, the user agent will perform such an attempt momentarily. The user agent is maintaining a list of which cues are active, and events are being fired accordingly. In addition, for timed tracks whose kind is subtitles or captions, the cues are being displayed over the video as appropriate; for timed tracks whose kind is descriptions, the user agent is making the cues available to the user in a non-visual fashion; and for timed tracks whose kind is chapters, the user agent is making available to the user a mechanism by which the user can navigate to any point in the media resource by selecting a cue.

A list of zero or more cues

A list of timed track cues, along with rules for updating the timed track rendering (e.g., for WebSRT, the rules for updating the display of WebSRT timed tracks).

The list of cues of a timed track can change dynamically, either because the timed track has not yet been loaded or is still loading, or because the the timed track corresponds to a MutableTimedTrack object, whose API allows individual cues can be added or removed dynamically.

Each timed track has a corresponding TimedTrack object.

The timed tracks of a media element are ready if all the timed tracks whose mode was not in the disabled state when the element's resource selection algorithm last started now have a timed track readiness state of loaded or failed to load.

A timed track cue is the unit of time-sensitive data in a timed track, corresponding for instance for subtitles and captions to the text that appears at a particular time and disappears at another time.

Each timed track cue consists of:

An identifier

An arbitrary string.

A start time

A time, in seconds and fractions of a second, at which the cue becomes relevant.

An end time

A time, in seconds and fractions of a second, at which the cue stops being relevant.

A pause-on-exit flag

A boolean indicating whether playback of the media resource is to pause when the cue stops being relevant.

A writing direction

A writing direction, either horizontal (a line extends horizontally and is positioned vertically, with consecutive lines displayed below each other), vertical growing left (a line extends vertically and is positioned horizontally, with consecutive lines displayed to the left of each other), or vertical growing right (a line extends vertically and is positioned horizontally, with consecutive lines displayed to the right of each other).

If the writing direction is horizontal, then line position percentages are relative to the height of the video, and text position and size percentages are relative to the width of the video.

Otherwise, line position percentages are relative to the width of the video, and text position and size percentages are relative to the height of the video.

A snap-to-lines flag

A boolean indicating whether the line's position is a line position (positioned to a multiple of the line dimensions of the first line of the cue), or whether it is a percentage of the dimension of the video.

A line position

Either a number giving the position of the lines of the cue, to be interpreted as defined by the writing direction and snap-to-lines flag of the cue, or the special value auto, which means the position is to depend on the other active tracks.

A text position

A number giving the position of the text of the cue within each line, to be interpreted as a percentage of the video, as defined by the writing direction.

A size

A number giving the size of the box within which the text of each line of the cue is to be aligned, to be interpreted as a percentage of the video, as defined by the writing direction.

An alignment

An alignment for the text of each line of the cue, either start alignment (the text is aligned towards its start side), middle alignment (the text is aligned centered between its start and end sides), end alignment (the text is aligned towards its end side). Which sides are the start and end sides depends on the Unicode bidirectional algorithm and the writing direction. [BIDI]

A voice identifier

A string identifying the voice with which the cue is associated.

The text of the cue

The raw text of the cue, and rules for its interpretation, allowing the text to be rendered and converted to a DOM fragment.

A timed track cue is immutable.

Each timed track cue has a corresponding TimedTrackCue object, and can be associated with a particular timed track. Once a timed track cue is associated with a particular timed track, the association is permanent.

In addition, each timed track cue has two pieces of dynamic information:

The active flag

This flag must be initially unset. The flag is used to ensure events are fired appropriately when the cue becomes active or inactive, and to make sure the right cues are rendered.

The user agent must synchronously unset this flag whenever the timed track cue is removed from its timed track's timed track list of cues; whenever the timed track itself is removed from its media element's list of timed tracks or has its timed track mode changed to disabled; and whenever the media element's readyState is changed back to HAVE_NOTHING. When the flag is unset in this way for one or more cues in timed tracks that were showing prior to the relevant incident, the user agent must, after having unset the flag for all the affected cues, apply the rules for updating the timed track rendering of those timed tracks (e.g., for timed tracks based on WebSRT, the rules for updating the display of WebSRT timed tracks).

The display state

This is used as part of the rendering model, to keep cues in a consistent position. It must initially be empty. Whenever the timed track cue active flag is unset, the user agent must empty the timed track cue display state.

The timed track cues of a media element's timed tracks are ordered relative to each other in the timed track cue order, which is determined as follows: first group the cues by their timed track, with the groups being sorted in the same order as their timed tracks appear in the media element's list of timed tracks; then, within each group, cues must be sorted by their start time, earliest first; then, any cues with the same start time must be sorted by their end time, earliest first; and finally, any cues with identical end times must be sorted in the order they were created (so e.g. for cues from a WebSRT file, that would be the order in which the cues were listed in the file).

4.8.10.10.2 Sourcing in-band timed tracks

A media-resource-specific timed track is a timed track that corresponds to data found in the media resource.

4.8.10.10.3 Timed track API

media . tracks . length

Returns the number of timed tracks associated with the media element (e.g. from track elements). This is the number of timed tracks in the media element's list of timed tracks.

media . tracks[ n ]

Returns the TimedTrack object representing the nth timed track in the media element's list of timed tracks.

track . track

Returns the TimedTrack object representing the track element's timed track.

interface TimedTrack {
  readonly attribute DOMString kind;
  readonly attribute DOMString label;
  readonly attribute DOMString language;

  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 Function onload;
  readonly attribute Function onerror;

  const unsigned short OFF = 0;
  const unsigned short HIDDEN = 1;
  const unsigned short SHOWING = 2;
           attribute unsigned short mode;

  readonly attribute TimedTrackCueList cues;
  readonly attribute TimedTrackCueList activeCues;

  readonly attribute Function oncuechange;
};

timedTrack . kind

Returns the timed track kind string.

timedTrack . label

Returns the timed track label.

timedTrack . language

Returns the timed track language string.

timedTrack . readyState

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

TimedTrack . NONE (0)

The timed track not loaded state.

TimedTrack . LOADING (1)

The timed track loading state.

TimedTrack . LOADED (2)

The timed track loaded state.

TimedTrack . ERROR (3)

The timed track failed to load state.

timedTrack . mode

Returns the timed track mode, represented by a number from the following list:

TimedTrack . OFF (0)

The timed track disabled mode.

TimedTrack . HIDDEN (0)

The timed track hidden mode.

TimedTrack . SHOWING (0)

The timed track showing mode.

Can be set, to change the mode.

timedTrack . cues

Returns the timed track list of cues, as a TimedTrackCueList object.

timedTrack . activeCues

Returns the timed track cues from the timed track list of cues that are currently active (i.e. that start before the current playback position and end after it), as a TimedTrackCueList object.

interface MutableTimedTrack : TimedTrack {
 void addCue(in TimedTrackCue cue);
 void removeCue(in TimedTrackCue cue);
};

mutableTimedTrack = media . addTrack( kind [, label [, language ] ] )

Creates and returns a new MutableTimedTrack object, which is also added to the media element's list of timed tracks.

mutableTimedTrack . addCue( cue )

Adds the given cue to mutableTimedTrack's timed track list of cues.

Raises an exception if the argument is null, associated with another timed track, or already in the list of cues.

mutableTimedTrack . removeCue( cue )

Removes the given cue from mutableTimedTrack's timed track list of cues.

Raises an exception if the argument is null, associated with another timed track, or not in the list of cues.

var sfx = new Audio('sfx.wav');
var sounds = a.addTrack('metadata');
// add sounds we care about
sounds.addCue(new TimedTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
sounds.addCue(new TimedTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));

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

sfx.oncanplaythrough = function () {
  playSound('dog bark');
}
window.onbeforeunload = function () {
  playSound('kitten mew');
  return 'Are you sure you want to leave this awesome page?';
}

interface TimedTrackCueList {
  readonly attribute unsigned long length;
  getter TimedTrackCue (in unsigned long index);
  TimedTrackCue getCueById(in DOMString id);
};

cuelist . length

Returns the number of cues in the list.

cuelist[index]

Returns the timed track cue with index index in the list. The cues are sorted in timed track cue order.

cuelist . getCueById( id )

Returns the first timed track cue (in timed track cue order) with timed track cue identifier id.

Returns null if none of the cues have the given identifier or if the argument is the empty string.

[Constructor(in DOMString id, in double startTime, in double endTime, in DOMString text, in optional DOMString settings, in optional DOMString voice, in optional boolean pauseOnExit)]
interface TimedTrackCue {
  readonly attribute TimedTrack track;
  readonly attribute DOMString id;

  readonly attribute double startTime;
  readonly attribute double endTime;
  readonly attribute boolean pauseOnExit;

  readonly attribute DOMString direction;
  readonly attribute boolean snapToLines;
  readonly attribute long linePosition;
  readonly attribute long textPosition;
  readonly attribute long size;
  readonly attribute DOMString alignment;

  readonly attribute DOMString voice;
  DOMString getCueAsSource();
  DocumentFragment getCueAsHTML();

  readonly attribute Function onenter;
  readonly attribute Function onexit;
};

cue = new TimedTrackCue( id, startTime, endTime, text [, settings [, voice [, pauseOnExit ] ] ] )

Returns a new TimedTrackCue object, for use with the addCue() method.

The id argument sets the timed track cue identifier.

The startTime argument sets the timed track cue start time.

The endTime argument sets the timed track cue end time.

The text argument sets the timed track cue text.

The settings argument is a string in the format of WebSRT cue settings. If omitted, the empty string is assumed.

The voice argument sets the timed track cue voice identifier. If omitted, the empty string is assumed.

The pauseOnExit argument sets the timed track cue pause-on-exit flag. If omitted, false is assumed.

cue . track

Returns the TimedTrack object to which this timed track cue belongs, if any, or null otherwise.

cue . id

Returns the timed track cue identifier.

cue . startTime

Returns the timed track cue start time, in seconds.

cue . endTime

Returns the timed track cue end time, in seconds.

cue . pauseOnExit

Returns true if the timed track cue pause-on-exit flag is set, false otherwise.

cue . direction

Returns a string representing the timed track cue writing direction, as follows:

If it is horizontal

The string "horizontal".

If it is vertical growing left

The string "vertical".

If it is vertical growing right

The string "vertical-lr".

cue . snapToLines

Returns true if the timed track cue snap-to-lines flag is set, false otherwise.

cue . linePosition

Returns the timed track cue line position. In the case of the value being auto, the appropriate default is returned.

cue . textPosition

Returns the timed track cue text position.

cue . size

Returns the timed track cue size.

cue . alignment

Returns a string representing the timed track cue alignment, as follows:

If it is start alignment

The string "start".

If it is middle alignment

The string "middle".

If it is end alignment

The string "end".

cue . voice

Returns the timed track cue voice identifier.

source = cue . getCueAsSource()

Returns the timed track cue text in raw unparsed form.

fragment = cue . getCueAsHTML()

Returns the timed track cue text as a DocumentFragment of HTML elements and other DOM nodes.

4.8.10.11 User interface

The controls attribute is a boolean attribute. If present, it indicates that the author has not provided a scripted controller and would like the user agent to provide its own set of controls.

media . volume [ = value ]

Returns the current playback volume, as a number in the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.

Can be set, to change the volume.

Throws an INDEX_SIZE_ERR if the new value is not in the range 0.0 .. 1.0.

media . muted [ = value ]

Returns true if audio is muted, overriding the volume attribute, and false if the volume attribute is being honored.

Can be set, to change whether the audio is muted or not.

The audio attribute on the video element controls the default state of the audio channel of the media resource, potentially overriding user preferences.

The audio attribute, if specified, must have a value that is an unordered set of unique space-separated tokens, which are ASCII case-insensitive. The tokens must be from the following list (currently, only one allowed token is defined):

muted

Causes the user agent to override the user's preferences, if any, and always default the video to muted.

A future version of this specification will probably introduce new values here, e.g. to control the default volume, or to select a default audio track.

This attribute has no dynamic effect (it only controls the default state of the element).

<video src="adverts.cgi?kind=video" controls autoplay loop audio=muted></video>

4.8.10.12 Time ranges

Objects implementing the TimeRanges interface represent a list of ranges (periods) of time.

interface TimeRanges {
  readonly attribute unsigned long length;
  double start(in unsigned long index);
  double end(in unsigned long index);
};

media . length

Returns the number of ranges in the object.

time = media . start(index)

Returns the time for the start of the range with the given index.

Throws an INDEX_SIZE_ERR if the index is out of range.

time = media . end(index)

Returns the time for the end of the range with the given index.

Throws an INDEX_SIZE_ERR if the index is out of range.

4.8.10.13 Event summary

This section is non-normative.

The following events fire on media elements as part of the processing model described above: