track
elementtrack
elementkind
src
srclang
label
default
interface HTMLTrackElement : HTMLElement { attribute DOMString kind; attribute DOMString src; attribute DOMString srclang; attribute DOMString label; attribute boolean default; 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. 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.
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 soundtrack). Displayed over the video. |
captions |
Captions | Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when the soundtrack is unavailable (e.g. because it is muted or because the user is deaf). Displayed over 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 unavailable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind). Synthesized as separate audio track. |
chapters |
Chapters | Chapter titles, intended to be used for navigating the media resource. Displayed as an interactive list in the user agent's interface. |
metadata |
Metadata | Tracks intended for use from script. Not displayed by the user agent. |
The attribute may be omitted. The missing value default is the subtitles state.
The src
attribute gives the address of the text track data. The value must be a valid non-empty URL potentially surrounded by spaces. This attribute must be present.
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]
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.
The default
attribute, 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. There must not be more than one track
element with the same parent node with the default
attribute specified.
track
Returns the TextTrack
object corresponding to the text track of the track
element.
The src
, srclang
, label
, and default
IDL attributes must reflect the respective content attributes of the same name. 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.vtt srclang=en label="English for the Hard of Hearing"> <track kind=subtitles src=brave.fr.vtt srclang=fr label="Français"> <track kind=subtitles src=brave.de.vtt srclang=de label="Deutsch"> </video>
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();
// media controller
attribute DOMString mediaGroup;
attribute MediaController controller;
// controls
attribute boolean controls;
attribute double volume;
attribute boolean muted;
attribute boolean defaultMuted;
// tracks
readonly attribute MultipleTrackList audioTracks;
readonly attribute ExclusiveTrackList videoTracks;
readonly attribute TextTrack[] textTracks;
MutableTextTrack addTextTrack(in DOMString kind, in optional DOMString label, in optional DOMString language);
};
The media element attributes, src
, preload
, autoplay
, mediagroup
, loop
, muted
, 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.
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) given by the element's videoTracks
attribute, 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.
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.
error
Returns a MediaError
object representing the current error state of the element.
Returns null if there is no error.
interface MediaError { const unsigned short MEDIA_ERR_ABORTED = 1; const unsigned short MEDIA_ERR_NETWORK = 2; const unsigned short MEDIA_ERR_DECODE = 3; const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4; readonly attribute unsigned short code; };
error
. code
Returns the current error's error code, from the list below.
MEDIA_ERR_ABORTED
(numeric value 1)MEDIA_ERR_NETWORK
(numeric value 2)MEDIA_ERR_DECODE
(numeric value 3)MEDIA_ERR_SRC_NOT_SUPPORTED
(numeric value 4)src
attribute was not suitable.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.
The src
IDL attribute on media elements must reflect the content attribute of the same name.
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.
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.
"application/octet-stream
" is special-cased here; if any parameter appears with it, it should be treated just like any other MIME type. This is a deviation from the rule that unknown MIME type parameters should be ignored.
canPlayType
(type)Returns the empty string (a negative response), "maybe", or "probably" based on how confident the user agent is that it can play media resources of the given type.
This script tests to see if the user agent supports a (fictional) new format to dynamically decide whether to use a video
element or a plugin:
<section id="video"> <p><a href="playing-cats.nfv">Download video</a></p> </section> <script> var videoSection = document.getElementById('video'); var videoElement = document.createElement('video'); var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"'); if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) { // not confident of browser support // but we have a plugin // so use plugin instead videoElement = document.createElement("embed"); } else if (support == "") { // no support from browser and no plugin // do nothing videoElement = null; } if (videoElement) { while (videoSection.hasChildNodes()) videoSection.removeChild(videoSection.firstChild); videoElement.setAttribute("src", "playing-cats.nfv"); videoSection.appendChild(videoElement); } </script>
The type
attribute of the source
element allows the user agent to avoid downloading resources that use formats it cannot render.
networkState
Returns the current state of network activity for the element, from the codes in the list below.
NETWORK_EMPTY
(numeric value 0)NETWORK_IDLE
(numeric value 1)NETWORK_LOADING
(numeric value 2)NETWORK_NO_SOURCE
(numeric value 3)load
()Causes the element to reset and start selecting and loading a new media resource from scratch.
The preload
attribute is an enumerated attribute. The following table lists the keywords and states for the attribute — the keywords in the left column map to the states in the cell in the second column on the same row as the keyword.
Keyword | State | Brief description |
---|---|---|
none |
None | Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimise unnecessary traffic. |
metadata |
Metadata | Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, first frame, track list, duration, etc) is reasonable. |
auto |
Automatic | Hints to the user agent that the user agent can put the user's needs first without risk to the server, up to and including optimistically downloading the entire resource. |
The empty string is also a valid keyword, and maps to the Automatic state. The attribute's missing value default is user-agent defined, though the Metadata state is suggested as a compromise between reducing server load and providing an optimal user experience.
The 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.
buffered
Returns a TimeRanges
object that represents the ranges of the media resource that the user agent has buffered.
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.
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 or if there is a current media controller. Will throw an INDEX_SIZE_ERR
exception if the given time is not within the ranges to which the user agent can seek.
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 startOffsetTime
attribute 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.
readyState
Returns a value that expresses the current state of the element with respect to rendering the current playback position, from the codes in the list below.
HAVE_NOTHING
(numeric value 0)networkState
attribute are set to NETWORK_EMPTY
are always in the HAVE_NOTHING
state.HAVE_METADATA
(numeric value 1)video
element, the dimensions of the video are also available. The API will no longer raise an exception when seeking. No media data is available for the immediate current playback position. The text tracks are ready.HAVE_CURRENT_DATA
(numeric value 2)HAVE_METADATA
state, or there is no more data to obtain in the direction of playback. For example, in video this corresponds to the user agent having data from the current frame, but not the next frame; and to when playback has ended.HAVE_FUTURE_DATA
(numeric value 3)HAVE_METADATA
state. For example, in video this corresponds to the user agent having data for at least the current frame and the next frame. The user agent cannot be in this state if playback has ended, as the current playback position can never advance in this case.HAVE_ENOUGH_DATA
(numeric value 4)HAVE_FUTURE_DATA
state are met, and, in addition, the user agent estimates that data is being fetched at a rate where the current playback position, if it were to advance at the effective playback rate, 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.
The autoplay
IDL attribute must reflect the content attribute of the same name.
paused
Returns true if playback is paused; false otherwise.
ended
Returns true if playback has reached the end of the media resource.
defaultPlaybackRate
[ = value ]Returns the default rate of playback, for when the user is not fast-forwarding or reversing through the media resource.
Can be set, to change the default rate of playback.
The default rate has no direct effect on playback, but if the user switches to a fast-forward mode, when they return to the normal playback mode, it is expected that the rate of playback will be returned to the default rate of playback.
When the element has a current media controller, the defaultPlaybackRate
attribute is ignored and the current media controller's defaultPlaybackRate
is used instead.
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.
played
Returns a TimeRanges
object that represents the ranges of the media resource that the user agent has played.
play
()Sets the paused
attribute to false, loading the media resource and beginning playback if necessary. If the playback had ended, will restart it from the start.
pause
()Sets the paused
attribute to true, loading the media resource if necessary.
seeking
Returns true if the user agent is currently seeking.
seekable
Returns a TimeRanges
object that represents the ranges of the media resource to which it is possible for the user agent to seek.
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.
audioTracks
Returns a MultipleTrackList
object representing the audio tracks available in the media resource.
videoTracks
Returns an ExclusiveTrackList
object representing the video tracks available in the media resource.
TrackList
objectsThe MultipleTrackList
and ExclusiveTrackList
interfaces, used by the attributes defined in the previous section, are substantially similar. Their common features are defined in the TrackList
interface, from which they both inherit.
interface TrackList { readonly attribute unsigned long length; DOMString getID(in unsigned long index); DOMString getKind(in unsigned long index); DOMString getLabel(in unsigned long index); DOMString getLanguage(in unsigned long index); attribute Function onchange; }; interface MultipleTrackList : TrackList { boolean isEnabled(in unsigned long index); void enable(in unsigned long index); void disable(in unsigned long index); }; interface ExclusiveTrackList : TrackList { readonly attribute unsigned long selectedIndex; void select(in unsigned long index); };
length
Returns the number of tracks in the list.
getID
( index )Returns the ID of the given track. This is the ID that can be used with a fragment identifier if the format supports the Media Fragments URI syntax. [MEDIAFRAG]
getKind
( index )Returns the category the given track falls into. The possible track categories are given below.
getLabel
( index )Returns the label of the given track, if known, or the empty string otherwise.
getLanguage
( index )Returns the language of the given track, if known, or the empty string otherwise.
isEnabled
( index )Returns true if the given track is active, and false otherwise.
enable
( index )Enables the given track.
disable
( index )Disables the given track.
isEnabled
Returns the index of the currently selected track, if any, or −1 otherwise.
select
( index )Selects the given track.
Category | Definition | Applies to... | Examples |
---|---|---|---|
"alternative " |
A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video). | Audio and video. | Ogg: "audio/alterate" or "video/alternate". |
"description " |
An audio description of a video track. | Audio only. | Ogg: "audio/audiodesc". |
"main " |
The primary audio or video track. | Audio and video. | Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set. |
"sign " |
A sign-language interpretation of an audio track. | Video only. | Ogg: "video/sign". |
"translation " |
A translated version of the main track. | Audio only. | Ogg: "audio/dub". |
"" (empty string) | No explicit kind, or the kind given by the track's metadata is not recognised by the user agent. | Audio and video. | Any other track type or track role. |
The audioTracks
and videoTracks
attributes allow scripts to select which track should play, but it is also possible to select specific tracks declaratively, by specifying particular tracks in the fragment identifier of the URL of the media resource. The format of the fragment identifier depends on the MIME type of the media resource. [RFC2046] [RFC3986]
In this example, a video that uses a format that supports the Media Fragments URI fragment identifier syntax is embedded in such a way that the alternative angles labeled "Alternative" are enabled instead of the default video track. [MEDIAFRAG]
<video src="myvideo#track=Alternative"></video>
Each media element can have a MediaController
. A MediaController
is an object that coordinates the playback of multiple media elements, for instance so that a sign-language interpreter track can be overlaid on a video track, with the two being kept in sync.
By default, a media element has no MediaController
. An implicit MediaController
can be assigned using the mediagroup
content attribute. An explicit MediaController
can be assigned directly using the controller
IDL attribute.
Media elements with a MediaController
are said to be slaved to their controller. The MediaController
modifies the playback rate and the playback volume of each of the media elements slaved to it, and ensures that when any of its slaved media elements unexpectedly stall, the others are stopped at the same time.
When a media element is slaved to a MediaController
, its playback rate is fixed to that of the other tracks in the same MediaController
, and any looping is disabled.
[Constructor] interface MediaController { readonly attribute TimeRanges buffered; readonly attribute TimeRanges seekable; readonly attribute double duration; attribute double currentTime; readonly attribute boolean paused; readonly attribute TimeRanges played; void play(); void pause(); attribute double defaultPlaybackRate; attribute double playbackRate; attribute double volume; attribute boolean muted; attribute Function onemptied; attribute Function onloadedmetadata; attribute Function onloadeddata; attribute Function oncanplay; attribute Function oncanplaythrough; attribute Function onplaying; attribute Function onwaiting; attribute Function ondurationchange; attribute Function ontimeupdate; attribute Function onplay; attribute Function onpause; attribute Function onratechange; attribute Function onvolumechange; };
MediaController
()Returns a new MediaController
object.
controller
[ = controller ]Returns the current MediaController
for the media element, if any; returns null otherwise.
Can be set, to set an explicit MediaController
. Doing so removes the mediagroup
attribute, if any.
buffered
Returns a TimeRanges
object that represents the intersection of the time ranges for which the user agent has all relevant media data for all the slaved media elements.
seekable
Returns a TimeRanges
object that represents the intersection of the time ranges into which the user agent can seek for all the slaved media elements.
duration
Returns the difference between the earliest playable moment and the latest playable moment (not considering whether the data in question is actually buffered or directly seekable, but not including time in the future for infinite streams). Will return zero if there is no media.
currentTime
[ = value ]Returns the current playback position, in seconds, as a position between zero time and the current duration
.
Can be set, to seek to the given time.
paused
Returns true if playback is paused; false otherwise. When this attribute is true, any media element slaved to this controller will be stopped.
played
Returns a TimeRanges
object that represents the union of the time ranges in all the slaved media elements that have been played.
play
()Sets the paused
attribute to false.
pause
()Sets the paused
attribute to true.
defaultPlaybackRate
[ = value ]Returns the default rate of playback.
Can be set, to change the default rate of playback.
This 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 rate of playback (playbackRate
) will be returned to this default rate.
playbackRate
[ = value ]Returns the current rate of playback.
Can be set, to change the rate of playback.
volume
[ = value ]Returns the current playback volume multiplier, 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 multiplier.
Throws an INDEX_SIZE_ERR
if the new value is not in the range 0.0 .. 1.0.
muted
[ = value ]Returns true if all audio is muted (regardless of other attributes either on the controller or on any media elements slaved to this controller), and false otherwise.
Can be set, to change whether the audio is muted or not.
The mediagroup
content attribute on media elements can be used to link multiple media elements together by implicitly creating a MediaController
.
The mediaGroup
IDL attribute on media elements must reflect the mediagroup
content attribute.
Multiple media elements referencing the same media resource will share a single network request. This can be used to efficiently play two (video) tracks from the same media resource in two different places on the screen. Used with the mediagroup
attribute, these elements can also be kept synchronised.
In this example, a sign-languge interpreter track from a movie file is overlaid on the primary video track of that same video file using two video
elements, some CSS, and an implicit MediaController
:
<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&track=English" autoplay controls mediagroup=movie></video> <video src="movie.vid#track=sign" autoplay mediagroup=movie></video> </div> </article>
A media element can have a group of associated text tracks, known as the media element's list of text tracks. The text tracks are sorted as follows:
track
element children of the media element, in tree order.addTextTrack()
method, in the order they were added, oldest first.A text track consists of:
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 text track corresponding to a track
element.
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 text 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.
This is a string (a BCP 47 language tag) representing the language of the text track's cues. [BCP47]
The language of a text track can change dynamically, in the case of a text track corresponding to a track
element.
One of the following:
Indicates that the text track is known to exist (e.g. it has been declared with a track
element), but its cues have not been obtained.
Indicates that the text track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track.
Indicates that the text track has been loaded with no fatal errors. No new cues will be added to the track except if the text track corresponds to a MutableTextTrack
object.
Indicates that the text 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 text track format). Some or all of the cues are likely missing and will not be obtained.
The readiness state of a text track changes dynamically as the track is obtained.
One of the following:
Indicates that the text track is not active. Other than for the purposes of exposing the track in the DOM, the user agent is ignoring the text track. No cues are active, no events are fired, and the user agent will not attempt to obtain the track's cues.
Indicates that the text 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.
Indicates that the text 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 text tracks whose kind is subtitles
or captions
, the cues are being displayed over the video as appropriate; for text tracks whose kind is descriptions
, the user agent is making the cues available to the user in a non-visual fashion; and for text 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.
The showing by default state is used in conjunction with the default
attribute on track
elements to indicate that the text track was enabled due to that attribute. This allows the user agent to override the state if a later track is discovered that is more appropriate per the user's preferences.
A list of text track cues, along with rules for updating the text track rendering.
The list of cues of a text track can change dynamically, either because the text track has not yet been loaded or is still loading, or because the text track corresponds to a MutableTextTrack
object, whose API allows individual cues can be added or removed dynamically.
Each text track has a corresponding TextTrack
object.
The text tracks of a media element are ready if all the text tracks whose mode was not in the disabled state when the element's resource selection algorithm last started now have a text track readiness state of loaded or failed to load.
A text track cue is the unit of time-sensitive data in a text track, corresponding for instance for subtitles and captions to the text that appears at a particular time and disappears at another time.
Each text track cue consists of:
An arbitrary string.
A time, in seconds and fractions of a second, at which the cue becomes relevant.
A time, in seconds and fractions of a second, at which the cue stops being relevant.
A boolean indicating whether playback of the media resource is to pause when the cue stops being relevant.
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).
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.
The raw text of the cue, and rules for its interpretation, allowing the text to be rendered and converted to a DOM fragment.
A text track cue is immutable.
Each text track cue has a corresponding TextTrackCue
object, and can be associated with a particular text track. Once a text track cue is associated with a particular text track, the association is permanent.
In addition, each text track cue has two pieces of dynamic information:
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 text track cue is removed from its text track's text track list of cues; whenever the text track itself is removed from its media element's list of text tracks or has its text 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 text tracks that were showing or showing by default 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 text track rendering of those text tracks.
This is used as part of the rendering model, to keep cues in a consistent position. It must initially be empty. Whenever the text track cue active flag is unset, the user agent must empty the text track cue display state.
The text track cues of a media element's text tracks are ordered relative to each other in the text track cue order, which is determined as follows: first group the cues by their text track, with the groups being sorted in the same order as their text tracks appear in the media element's list of text 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 WebVTT file, that would be the order in which the cues were listed in the file).
A media-resource-specific text track is a text track that corresponds to data found in the media resource.
textTracks
. length
Returns the number of text tracks associated with the media element (e.g. from track
elements). This is the number of text tracks in the media element's list of text tracks.
textTracks[
n ]
Returns the TextTrack
object representing the nth text track in the media element's list of text tracks.
track
Returns the TextTrack
object representing the track
element's text track.
interface TextTrack { 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; attribute Function onload; attribute Function onerror; const unsigned short OFF = 0; const unsigned short HIDDEN = 1; const unsigned short SHOWING = 2; attribute unsigned short mode; readonly attribute TextTrackCueList cues; readonly attribute TextTrackCueList activeCues; attribute Function oncuechange; }; TextTrack implements EventTarget;
kind
Returns the text track kind string.
label
Returns the text track label.
language
Returns the text track language string.
readyState
Returns the text track readiness state, represented by a number from the following list:
TextTrack
. NONE
(0)The text track not loaded state.
TextTrack
. LOADING
(1)The text track loading state.
TextTrack
. LOADED
(2)The text track loaded state.
TextTrack
. ERROR
(3)The text track failed to load state.
mode
Returns the text track mode, represented by a number from the following list:
TextTrack
. OFF
(0)The text track disabled mode.
TextTrack
. HIDDEN
(1)The
mode.TextTrack
. SHOWING
(2)The text track showing and showing by default modes.
Can be set, to change the mode.
cues
Returns the text track list of cues, as a TextTrackCueList
object.
activeCues
Returns the text track cues from the text track list of cues that are currently active (i.e. that start before the current playback position and end after it), as a TextTrackCueList
object.
interface MutableTextTrack : TextTrack { void addCue(in TextTrackCue cue); void removeCue(in TextTrackCue cue); };
addTextTrack
( kind [, label [, language ] ] )Creates and returns a new MutableTextTrack
object, which is also added to the media element's list of text tracks.
addCue
( cue )Adds the given cue to mutableTextTrack's text track list of cues.
Raises an exception if the argument is null, associated with another text track, or already in the list of cues.
removeCue
( cue )Removes the given cue from mutableTextTrack's text track list of cues.
Raises an exception if the argument is null, associated with another text track, or not in the list of cues.
In this example, an audio
element is used to play a specific sound-effect from a sound file containing many sound effects. A cue is used to pause the audio, so that it ends exactly at the end of the clip, even if the browser is busy running some script. If the page had relied on script to pause the audio, then the start of the next clip might be heard if the browser was not able to run the script at the exact time specified.
var sfx = new Audio('sfx.wav'); var sounds = a.addTextTrack('metadata'); // add sounds we care about sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true)); sounds.addCue(new TextTrackCue('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 TextTrackCueList { readonly attribute unsigned long length; getter TextTrackCue (in unsigned long index); TextTrackCue getCueById(in DOMString id); };
length
Returns the number of cues in the list.
Returns the text track cue with index index in the list. The cues are sorted in text track cue order.
getCueById
( id )Returns the first text track cue (in text track cue order) with text track cue identifier id.
Returns null if none of the cues have the given identifier or if the argument is the empty string.
interface TextTrackCue { readonly attribute TextTrack track; readonly attribute DOMString id; readonly attribute double startTime; readonly attribute double endTime; readonly attribute boolean pauseOnExit; DOMString getCueAsSource(); DocumentFragment getCueAsHTML(); attribute Function ; attribute Function ; }; TextTrackCue implements EventTarget;
Returns the TextTrack
object to which this text track cue belongs, if any, or null otherwise.
Returns the text track cue identifier.
Returns the text track cue start time, in seconds.
Returns the text track cue end time, in seconds.
Returns true if the text track cue pause-on-exit flag is set, false otherwise.
Returns the text track cue text in raw unparsed form.
Returns the text track cue text as a DocumentFragment
of HTML elements and other DOM nodes.
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.
The controls
IDL attribute must reflect the content attribute of the same name.
volume
[ = value ]Returns the current playback volume, as a number in the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.
Can be set, to change the volume.
Throws an INDEX_SIZE_ERR
if the new value is not in the range 0.0 .. 1.0.
muted
[ = value ]Returns true if audio is muted, overriding the volume
attribute, and false if the volume
attribute is being honored.
Can be set, to change whether the audio is muted or not.
The muted
attribute on the video
element controls the default state of the audio channel of the media resource, potentially overriding user preferences.
The defaultMuted
IDL attribute must reflect the muted
content attribute.
This attribute has no dynamic effect (it only controls the default state of the element).
This video (an advertisment) autoplays, but to avoid annoying users, it does so without sound, and allows the user to turn the sound on.
<video src="adverts.cgi?kind=video" controls autoplay loop muted></video>
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); };
length
Returns the number of ranges in the object.
start
(index)Returns the time for the start of the range with the given index.
Throws an INDEX_SIZE_ERR
if the index is out of range.
end
(index)Returns the time for the end of the range with the given index.
Throws an INDEX_SIZE_ERR
if the index is out of range.
The following events fire on media elements as part of the processing model described above:
Event name | Interface | Dispatched when... | Preconditions |
---|---|---|---|
loadstart |
Event |
The user agent begins looking for media data, as part of the resource selection algorithm. | networkState equals NETWORK_LOADING |
progress |
Event |
The user agent is fetching media data. | networkState equals NETWORK_LOADING |
suspend |
Event |
The user agent is intentionally not currently fetching media data, but does not have the entire media resource downloaded. | networkState equals NETWORK_IDLE |
abort |
Event |
The user agent stops fetching the media data before it is completely downloaded, but not due to an error. | error is an object with the code MEDIA_ERR_ABORTED . networkState equals either NETWORK_EMPTY or NETWORK_IDLE , depending on when the download was aborted. |
error |
Event |
An error occurs while fetching the media data. | error is an object with the code MEDIA_ERR_NETWORK or higher. networkState equals either NETWORK_EMPTY or NETWORK_IDLE , depending on when the download was aborted. |
emptied |
Event |
A media element whose networkState was previously not in the NETWORK_EMPTY state has just switched to that state (either because of a fatal error during load that's about to be reported, or because the load() method was invoked while the resource selection algorithm was already running). |
networkState is NETWORK_EMPTY ; all the IDL attributes are in their initial states. |
stalled |
Event |
The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. | networkState is NETWORK_LOADING . |
loadedmetadata |
Event |
The user agent has just determined the duration and dimensions of the media resource and the text tracks are ready. | readyState is newly equal to HAVE_METADATA or greater for the first time. |
loadeddata |
Event |
The user agent can render the media data at the current playback position for the first time. | readyState newly increased to HAVE_CURRENT_DATA or greater for the first time. |
canplay |
Event |
The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content. | readyState newly increased to HAVE_FUTURE_DATA or greater. |
canplaythrough |
Event |
The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering. | readyState is newly equal to HAVE_ENOUGH_DATA . |
playing |
Event |
Playback is ready to start after having been paused or delayed due to lack of media data. | readyState is newly equal to or greater than HAVE_FUTURE_DATA and paused is false, or paused is newly false and readyState is equal to or greater than HAVE_FUTURE_DATA . Even if this event fires, the element might still not be potentially playing, e.g. if the element
is blocked on its media controller (e.g. because the current media controller is paused, or another slaved media element is stalled somehow, or because the media resource has no data corresponding to the media controller position), or the element is paused for user interaction. |
waiting |
Event |
Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course. | readyState is equal to or less than HAVE_CURRENT_DATA , and paused is false. Either seeking is true, or the current playback position is not contained in any of the ranges in buffered . It is possible for playback to stop for other reasons without paused being false, but those reasons do not fire
this event (and when those situations resolve, a separate playing event is not fired either): e.g. the element is newly blocked on its media controller, or playback ended, or playback stopped due to errors, or the element has paused for user interaction. |
seeking |
Event |
The seeking IDL attribute changed to true and the seek operation is taking long enough that the user agent has time to fire the event. |
|
seeked |
Event |
The seeking IDL attribute changed to false. |
|
ended |
Event |
Playback has stopped because the end of the media resource was reached. | currentTime equals the end of the media resource; ended is true. |
durationchange |
Event |
The duration attribute has just been updated. |
|
timeupdate |
Event |
The current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. | |
play |
Event |
The element is no longer paused. Fired after the play() method has returned, or when the autoplay attribute has caused playback to begin. |
paused is newly false. |
pause |
Event |
The element has been paused. Fired after the pause() method has returned. |
paused is newly true. |
ratechange |
Event |
Either the defaultPlaybackRate or the playbackRate attribute has just been updated. |
|
volumechange |
Event |
Either the volume attribute or the muted attribute has changed. Fired after the relevant attribute's setter has returned. |
The following events fire on MediaController
objects:
Event name | Interface | Dispatched when... |
---|---|---|
emptied |
Event |
All the slaved media elements newly have readyState set to HAVE_NOTHING or greater, or there are no longer any slaved media elements. |
loadedmetadata |
Event |
All the slaved media elements newly have readyState set to HAVE_METADATA or greater. |
loadeddata |
Event |
All the slaved media elements newly have readyState set to HAVE_CURRENT_DATA or greater. |
canplay |
Event |
All the slaved media elements newly have readyState set to HAVE_FUTURE_DATA or greater. |
canplaythrough |
Event |
All the slaved media elements newly have readyState set to HAVE_ENOUGH_DATA or greater. |
playing |
Event |
The MediaController is no longer a blocked media controller. |
waiting |
Event |
The MediaController is now a blocked media controller. |
ended |
Event |
All the slaved media elements have newly ended playback. |
durationchange |
Event |
The duration attribute has just been updated. |
timeupdate |
Event |
The media controller position changed. |
play |
Event |
The paused attribute is newly false. |
pause |
Event |
The paused attribute is newly true. |
ratechange |
Event |
Either the defaultPlaybackRate attribute or the playbackRate attribute has just been updated. |
volumechange |
Event |
Either the volume attribute or the muted attribute has just been updated. |
Playing audio and video resources on small devices such as set-top boxes or mobile phones is often constrained by limited hardware resources in the device. For example, a device might only support three simultaneous videos. For this reason, it is a good practice to release resources held by media elements when they are done playing, either by being very careful about removing all references to the element and allowing it to be garbage collected, or, even better, by removing the element's src
attribute and any source
element descendants, and invoking the element's load()
method.
Similarly, when the playback rate is not exactly 1.0, hardware, software, or format limitations can cause video frames to be dropped and audio to be choppy or muted.