- From: poot <cvsmail@w3.org>
- Date: Thu, 30 Jun 2011 19:53:16 -0400
- To: public-html-diffs@w3.org
hixie: Revamp how audioTracks and videoTracks work on HTMLMediaElement
and MediaStream. (whatwg r6275)
http://dev.w3.org/cvsweb/html5/spec/Overview.html?r1=1.5022&r2=1.5023&f=h
http://html5.org/tools/web-apps-tracker?from=6274&to=6275
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.5022
retrieving revision 1.5023
diff -u -d -r1.5022 -r1.5023
--- Overview.html 24 Jun 2011 00:32:45 -0000 1.5022
+++ Overview.html 30 Jun 2011 23:52:50 -0000 1.5023
@@ -318,7 +318,7 @@
<h1>HTML5</h1>
<h2 class="no-num no-toc" id="a-vocabulary-and-associated-apis-for-html-and-xhtml">A vocabulary and associated APIs for HTML and XHTML</h2>
- <h2 class="no-num no-toc" id="editor-s-draft-24-june-2011">Editor's Draft 24 June 2011</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-30-june-2011">Editor's Draft 30 June 2011</h2>
<dl><dt>Latest Published Version:</dt>
<dd><a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a></dd>
<dt>Latest Editor's Draft:</dt>
@@ -464,7 +464,7 @@
Group</a> is the W3C working group responsible for this
specification's progress along the W3C Recommendation
track.
- This specification is the 24 June 2011 Editor's Draft.
+ This specification is the 30 June 2011 Editor's Draft.
</p><!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>Work on this specification is also done at the <a href="http://www.whatwg.org/">WHATWG</a>. The W3C HTML working group
actively pursues convergence with the WHATWG, as required by the <a href="http://www.w3.org/2007/03/HTML-WG-charter">W3C HTML working
group charter</a>.</p><!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST --><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
@@ -767,7 +767,7 @@
<li><a href="#seeking"><span class="secno">4.8.10.9 </span>Seeking</a></li>
<li><a href="#media-resources-with-multiple-media-tracks"><span class="secno">4.8.10.10 </span>Media resources with multiple media tracks</a>
<ol>
- <li><a href="#tracklist-objects"><span class="secno">4.8.10.10.1 </span><code>TrackList</code> objects</a></li>
+ <li><a href="#audiotracklist-and-videotracklist-objects"><span class="secno">4.8.10.10.1 </span><code>AudioTrackList</code> and <code>VideoTrackList</code> objects</a></li>
<li><a href="#selecting-specific-audio-and-video-tracks-declaratively"><span class="secno">4.8.10.10.2 </span>Selecting specific audio and video tracks declaratively</a></ol></li>
<li><a href="#synchronising-multiple-media-elements"><span class="secno">4.8.10.11 </span>Synchronising multiple media elements</a>
<ol>
@@ -2941,9 +2941,9 @@
specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
<p>The terms <dfn id="supported-property-indices">supported property indices</dfn>, <dfn id="supported-property-names">supported
- property names</dfn>, and <dfn id="dfn-read-only-array" title="dfn-read-only-array">read
- only</dfn> (when applied to arrays) are used as defined in the
- WebIDL specification.</p>
+ property names</dfn>, <dfn id="determine-the-value-of-an-indexed-property">determine the value of an indexed
+ property</dfn>, <dfn id="array-host-objects">array host objects</dfn>, and <dfn id="dfn-read-only-array" title="dfn-read-only-array">read only</dfn> (when applied to
+ arrays) are used as defined in the WebIDL specification.</p>
<p id="float-nan">Except where otherwise specified, if an IDL
attribute that is a floating point number type (<code title="">double</code>) is assigned an Infinity or Not-a-Number
@@ -22294,9 +22294,9 @@
attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
// tracks
- readonly attribute <a href="#multipletracklist">MultipleTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
- readonly attribute <a href="#exclusivetracklist">ExclusiveTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
- readonly attribute <a href="#texttrack">TextTrack</a>[] <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
+ readonly attribute <a href="#audiotracklist">AudioTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
+ readonly attribute <a href="#videotracklist">VideoTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
+ readonly attribute <a href="#texttracklist">TextTrackList</a> <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
<a href="#mutabletexttrack">MutableTextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(in DOMString kind, in optional DOMString label, in optional DOMString language);
};</pre><p>The <dfn id="media-element-attributes">media element attributes</dfn>, <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
<code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
@@ -24642,7 +24642,7 @@
<dd>
- <p>Returns a <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
+ <p>Returns an <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
</dd>
@@ -24651,7 +24651,7 @@
<dd>
- <p>Returns an <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object representing
+ <p>Returns an <code><a href="#videotracklist">VideoTrackList</a></code> object representing
the video tracks available in the <a href="#media-resource">media resource</a>.</p>
</dd>
@@ -24660,23 +24660,24 @@
<p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
attribute of a <a href="#media-element">media element</a> must return a
- <a href="#live">live</a> <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
+ <a href="#live">live</a> <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
the audio tracks available in the <a href="#media-element">media element</a>'s
<a href="#media-resource">media resource</a>. The same object must be returned each
time.</p>
<p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
attribute of a <a href="#media-element">media element</a> must return a
- <a href="#live">live</a> <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object
+ <a href="#live">live</a> <code><a href="#videotracklist">VideoTrackList</a></code> object
representing the video tracks available in the <a href="#media-element">media
element</a>'s <a href="#media-resource">media resource</a>. The same object must
be returned each time.</p>
- <p class="note">There are only ever two <code><a href="#tracklist">TrackList</a></code>
- objects (one <code><a href="#multipletracklist">MultipleTrackList</a></code> object and one
- <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object) per <a href="#media-element">media
+ <p class="note">There are only ever one <code><a href="#audiotracklist">AudioTrackList</a></code>
+ object and one <code><a href="#videotracklist">VideoTrackList</a></code> object per <a href="#media-element">media
element</a>, even if another <a href="#media-resource">media resource</a> is
- loaded into the element: the objects are reused.</p>
+ loaded into the element: the objects are reused. (The
+ <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects are
+ not, though.)</p>
</div><div class="example">
@@ -24699,9 +24700,9 @@
container.appendChild(video);
video.onloadedmetadata = function (event) {
for (var i = 0; i < video.videoTracks.length; i += 1) {
- if (video.videoTracks.getKind(i) == 'sign') {
+ if (video.videoTracks[i].kind == 'sign') {
var sign = document.createElement('video');
- sign.src = url + '#track=' + video.videoTracks.getID(i);
+ sign.src = url + '#track=' + video.videoTracks[i].id;
sign.autoplay = true;
sign.controller = controller;
container.appendChild(sign);
@@ -24712,30 +24713,39 @@
}
</script></pre>
- </div><h6 id="tracklist-objects"><span class="secno">4.8.10.10.1 </span><code><a href="#tracklist">TrackList</a></code> objects</h6><p>The <code><a href="#multipletracklist">MultipleTrackList</a></code> and
- <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> interfaces, used by the attributes
- defined in the previous section, are substantially similar. Their
- common features are defined in the <code><a href="#tracklist">TrackList</a></code> interface,
- from which they both inherit.</p><pre class="idl">interface <dfn id="tracklist">TrackList</dfn> {
- readonly attribute unsigned long <a href="#dom-tracklist-length" title="dom-TrackList-length">length</a>;
- DOMString <a href="#dom-tracklist-getid" title="dom-TrackList-getID">getID</a>(in unsigned long index);
- DOMString <a href="#dom-tracklist-getkind" title="dom-TrackList-getKind">getKind</a>(in unsigned long index);
- DOMString <a href="#dom-tracklist-getlabel" title="dom-TrackList-getLabel">getLabel</a>(in unsigned long index);
- DOMString <a href="#dom-tracklist-getlanguage" title="dom-TrackList-getLanguage">getLanguage</a>(in unsigned long index);
-
+ </div><h6 id="audiotracklist-and-videotracklist-objects"><span class="secno">4.8.10.10.1 </span><code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects</h6><p>The <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code>
+ interfaces are used by attributes defined in the previous
+ section.<pre class="idl">interface <dfn id="audiotracklist">AudioTrackList</dfn> {
+ readonly attribute unsigned long <a href="#dom-audiotracklist-length" title="dom-AudioTrackList-length">length</a>;
+ getter <a href="#audiotrack">AudioTrack</a> (in unsigned long index);
+ <a href="#audiotrack">AudioTrack</a>? <a href="#dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById">getTrackById</a>(in DOMString id);
attribute <a href="#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
};
-interface <dfn id="multipletracklist">MultipleTrackList</dfn> : <a href="#tracklist">TrackList</a> {
- boolean <a href="#dom-tracklist-isenabled" title="dom-TrackList-isEnabled">isEnabled</a>(in unsigned long index);
- void <a href="#dom-tracklist-enable" title="dom-TrackList-enable">enable</a>(in unsigned long index);
- void <a href="#dom-tracklist-disable" title="dom-TrackList-disable">disable</a>(in unsigned long index);
+interface <dfn id="audiotrack">AudioTrack</dfn> {
+ readonly attribute DOMString <a href="#dom-audiotrack-id" title="dom-AudioTrack-id">id</a>;
+ readonly attribute DOMString <a href="#dom-audiotrack-kind" title="dom-AudioTrack-kind">kind</a>;
+ readonly attribute DOMString <a href="#dom-audiotrack-label" title="dom-AudioTrack-label">label</a>;
+ readonly attribute DOMString <a href="#dom-audiotrack-language" title="dom-AudioTrack-language">language</a>;
+ attribute boolean <a href="#dom-audiotrack-enabled" title="dom-AudioTrack-enabled">enabled</a>;
};
-interface <dfn id="exclusivetracklist">ExclusiveTrackList</dfn> : <a href="#tracklist">TrackList</a> {
- readonly attribute long <a href="#dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex">selectedIndex</a>;
- void <a href="#dom-tracklist-select" title="dom-TrackList-select">select</a>(in unsigned long index);
-};</pre><dl class="domintro"><dt><var title="">tracks</var> . <code title="dom-TrackList-length"><a href="#dom-tracklist-length">length</a></code></dt>
+interface <dfn id="videotracklist">VideoTrackList</dfn> {
+ readonly attribute unsigned long <a href="#dom-videotracklist-length" title="dom-VideoTrackList-length">length</a>;
+ getter <a href="#videotrack">VideoTrack</a> (in unsigned long index);
+ <a href="#videotrack">VideoTrack</a>? <a href="#dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById">getTrackById</a>(in DOMString id);
+ readonly attribute long <a href="#dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex">selectedIndex</a>;
+ attribute <a href="#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
+};
+
+interface <dfn id="videotrack">VideoTrack</dfn> {
+ readonly attribute DOMString <a href="#dom-videotrack-id" title="dom-VideoTrack-id">id</a>;
+ readonly attribute DOMString <a href="#dom-videotrack-kind" title="dom-VideoTrack-kind">kind</a>;
+ readonly attribute DOMString <a href="#dom-videotrack-label" title="dom-VideoTrack-label">label</a>;
+ readonly attribute DOMString <a href="#dom-videotrack-language" title="dom-VideoTrack-language">language</a>;
+ attribute boolean <a href="#dom-videotrack-selected" title="dom-VideoTrack-selected">selected</a>;
+};</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> . <code title="dom-AudioTrackList-length"><a href="#dom-audiotracklist-length">length</a></code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-length"><a href="#dom-videotracklist-length">length</a></code></dt>
<dd>
@@ -24743,65 +24753,74 @@
</dd>
- <dt><var title="">id</var> = <var title="">tracks</var> . <code title="dom-TrackList-getID"><a href="#dom-tracklist-getid">getID</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>[<var title="">index</var>]</dt>
+ <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code>[<var title="">index</var>]</dt>
<dd>
- <p>Returns the ID of the given track. This is the ID that can be
- used with a fragment identifier if the format supports the
- <cite>Media Fragments URI</cite> syntax. <a href="#hrefMEDIAFRAG">[MEDIAFRAG]</a></p>
+ <p>Returns the specified <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object.</p>
</dd>
- <dt><var title="">kind</var> = <var title="">tracks</var> . <code title="dom-TrackList-getKind"><a href="#dom-tracklist-getkind">getKind</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> . <code title="dom-AudioTrackList-getTrackById"><a href="#dom-audiotracklist-gettrackbyid">getTrackById</a></code>( <var title="">id</var> )</dt>
+ <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-getTrackById"><a href="#dom-videotracklist-gettrackbyid">getTrackById</a></code>( <var title="">id</var> )</dt>
<dd>
- <p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
+ <p>Returns the <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object with the given identifier, or null if no track has that identifier.</p>
</dd>
- <dt><var title="">label</var> = <var title="">tracks</var> . <code title="dom-TrackList-getLabel"><a href="#dom-tracklist-getlabel">getLabel</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-id"><a href="#dom-audiotrack-id">id</a></code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-id"><a href="#dom-videotrack-id">id</a></code></dt>
<dd>
- <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
+ <p>Returns the ID of the given track. This is the ID that can be
+ used with a fragment identifier if the format supports the
+ <cite>Media Fragments URI</cite> syntax, and that can be used with
+ the <code title="">getTrackById()</code> method. <a href="#hrefMEDIAFRAG">[MEDIAFRAG]</a></p>
</dd>
- <dt><var title="">language</var> = <var title="">tracks</var> . <code title="dom-TrackList-getLanguage"><a href="#dom-tracklist-getlanguage">getLanguage</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">kind</a></code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">kind</a></code></dt>
<dd>
- <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
+ <p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
</dd>
- <dt><var title="">enabled</var> = <var title="">audioTracks</var> . <code title="dom-TrackList-isEnabled"><a href="#dom-tracklist-isenabled">isEnabled</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-label"><a href="#dom-audiotrack-label">label</a></code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-label"><a href="#dom-videotrack-label">label</a></code></dt>
<dd>
- <p>Returns true if the given track is active, and false otherwise.</p>
+ <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
</dd>
- <dt><var title="">audioTracks</var> . <code title="dom-TrackList-enable"><a href="#dom-tracklist-enable">enable</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-language"><a href="#dom-audiotrack-language">language</a></code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-language"><a href="#dom-videotrack-language">language</a></code></dt>
<dd>
- <p>Enables the given track.</p>
+ <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
</dd>
- <dt><var title="">audioTracks</var> . <code title="dom-TrackList-disable"><a href="#dom-tracklist-disable">disable</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-enabled"><a href="#dom-audiotrack-enabled">enabled</a></code> [ = <var title="">value</var> ]</dt>
<dd>
- <p>Disables the given track.</p>
+ <p>Returns true if the given track is active, and false otherwise.</p>
+
+ <p>Can be set, to change whether the track is enabled or not. If multiple audio tracks are enabled simultaneously, they are mixed.</p>
</dd>
- <dt><var title="">videoTracks</var> . <code title="dom-TrackList-selectedIndex"><a href="#dom-tracklist-selectedindex">selectedIndex</a></code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-selectedIndex"><a href="#dom-videotracklist-selectedindex">selectedIndex</a></code></dt>
<dd>
@@ -24809,42 +24828,106 @@
</dd>
- <dt><var title="">videoTracks</var> . <code title="dom-TrackList-select"><a href="#dom-tracklist-select">select</a></code>( <var title="">index</var> )</dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-selected"><a href="#dom-videotrack-selected">selected</a></code> [ = <var title="">value</var> ]</dt>
<dd>
- <p>Selects the given track.</p>
+ <p>Returns true if the given track is active, and false otherwise.</p>
+
+ <p>Can be set, to change whether the track is selected or not. Either zero or one video track is selected; selecting a new track while a previous one is selected will unselect the previous one.</p>
</dd>
</dl><div class="impl">
- <p>The <dfn id="dom-tracklist-length" title="dom-TrackList-length"><code>length</code></dfn>
- attribute must return the number of tracks represented by the
- <code><a href="#tracklist">TrackList</a></code> object at the time of getting.</p>
+ <p>An <code><a href="#audiotracklist">AudioTrackList</a></code> object represents a dynamic list
+ of zero or more audio tracks, of which zero or more can be enabled
+ at a time. Each audio track is represented by an
+ <code><a href="#audiotrack">AudioTrack</a></code> object.</p>
- <p>Tracks in a <code><a href="#tracklist">TrackList</a></code> object must be consistently
- ordered. If the <a href="#media-resource">media resource</a> is in a format that
- defines an order, then that order must be used; otherwise, the order
- must be the relative order in which the tracks are declared in the
- <a href="#media-resource">media resource</a>. Each track in a <code><a href="#tracklist">TrackList</a></code>
- thus has an index; the first has the index 0, and each subsequent
- track is numbered one higher than the previous one.</p>
+ <p>A <code><a href="#videotracklist">VideoTrackList</a></code> object represents a dynamic list of
+ zero or more video tracks, of which zero or one can be selected at a
+ time. Each video track is represented by a <code><a href="#videotrack">VideoTrack</a></code>
+ object.</p>
- <p>The <dfn id="dom-tracklist-getid" title="dom-TrackList-getID"><code>getID(<var title="">index</var>)</code></dfn> method must return the identifier
- of the track with index <var title="">index</var>, if there is one.
- If there is no such track, then the method must instead throw an
- <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception. If the <a href="#media-resource">media
- resource</a> is in a format that supports the <cite>Media
- Fragments URI</cite> fragment identifier syntax, the returned
- identifier must be the same identifier that would enable the track
- if used as the name of a track in the track dimension of such a
+ <p>Tracks in <code><a href="#audiotracklist">AudioTrackList</a></code> and
+ <code><a href="#videotracklist">VideoTrackList</a></code> objects must be consistently ordered. If
+ the <a href="#media-resource">media resource</a> is in a format that defines an
+ order, then that order must be used; otherwise, the order must be
+ the relative order in which the tracks are declared in the
+ <a href="#media-resource">media resource</a>. The order used is called the <i>natural
+ order</i> of the list.</p>
+
+ <p class="note">Each track in a <code>TrackList</code> thus has an
+ index; the first has the index 0, and each subsequent track is
+ numbered one higher than the previous one. If a <a href="#media-resource">media
+ resource</a> dynamically adds or removes audio or video tracks,
+ then the indices of the tracks will change dynamically. If the
+ <a href="#media-resource">media resource</a> changes entirely, then all the previous
+ tracks will be removed and replaced with new tracks.</p>
+
+ <p>The <dfn id="dom-audiotracklist-length" title="dom-AudioTrackList-length"><code>AudioTrackList.length</code></dfn>
+ and <dfn id="dom-videotracklist-length" title="dom-VideoTrackList-length"><code>VideoTrackList.length</code></dfn>
+ attributes must return the number of tracks represented by their
+ objects at the time of getting.</p>
+
+ <p>The <a href="#supported-property-indices">supported property indices</a> of
+ <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects
+ at any instant are the numbers from zero to the number of tracks
+ represented by the respective object minus one, if any tracks are
+ represented. If a <code><a href="#audiotracklist">AudioTrackList</a></code> or
+ <code><a href="#videotracklist">VideoTrackList</a></code> object represents no tracks, it has no
+ <a href="#supported-property-indices">supported property indices</a>.</p>
+
+ <p>To <a href="#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
+ given index <var title="">index</var> in an
+ <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> object
+ <var title="">list</var>, the user agent must return the
+ <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object that
+ represents the <var title="">index</var>th track in <var title="">list</var>.</p>
+
+ <p>The <dfn id="dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById"><code>AudioTrackList.getTrackById(<var title="">id</var>)</code></dfn> and <dfn id="dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById"><code>VideoTrackList.getTrackById(<var title="">id</var>)</code></dfn> methods must return the first
+ <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object
+ (respectively) in the <code><a href="#audiotrack">AudioTrack</a></code> or
+ <code><a href="#videotrack">VideoTrack</a></code> object (respectively) whose identifier is
+ equal to the value of the <var title="">id</var> argument (in the
+ natural order of the list, as defined above). When no tracks match
+ the given argument, the methods must return null.</p>
+
+ <p>The <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects
+ represent specific tracks of a <a href="#media-resource">media resource</a>. Each
+ track can have an identifier, category, label, and language. These
+ aspects of a track are permanent for the lifetime of the track; even
+ if a track is removed from a <a href="#media-resource">media resource</a>'s
+ <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> objects,
+ those aspects do not change.</p>
+
+ <p>In addition, <code><a href="#audiotrack">AudioTrack</a></code> objects can each be enabled
+ or disabled; this is the audio track's <i>enabled state</i>. When an
+ <code><a href="#audiotrack">AudioTrack</a></code> is created, its <i>enabled state</i> must be
+ set to false (disabled). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
+ can override this.</p>
+
+ <p>Similarly, a single <code><a href="#videotrack">VideoTrack</a></code> object per
+ <code><a href="#videotracklist">VideoTrackList</a></code> object can be selected, this is the
+ video track's <i>selection state</i>. When an
+ <code><a href="#videotrack">VideoTrack</a></code> is created, its <i>selection state</i> must
+ be set to false (not selected). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
+ can override this.</p>
+
+ <p>The <dfn id="dom-audiotrack-id" title="dom-AudioTrack-id"><code>AudioTrack.id</code></dfn> and <dfn id="dom-videotrack-id" title="dom-VideoTrack-id"><code>VideTrack.id</code></dfn>
+ attributes must return the identifier of the track, if it has one,
+ or the empty string otherwise. If the <a href="#media-resource">media resource</a> is
+ in a format that supports the <cite>Media Fragments URI</cite>
+ fragment identifier syntax, the identifier returned for a particular
+ track must be the same identifier that would enable the track if
+ used as the name of a track in the track dimension of such a
fragment identifier. <a href="#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
- <p>The <dfn id="dom-tracklist-getkind" title="dom-TrackList-getKind"><code>getKind(<var title="">index</var>)</code></dfn> method must return the category
- of the track with index <var title="">index</var>, if there is one.
- If there is no such track, then the method must instead throw an
- <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
+ <p>The <dfn id="dom-audiotrack-kind" title="dom-AudioTrack-kind"><code>AudioTrack.kind</code></dfn> and
+ <dfn id="dom-videotrack-kind" title="dom-VideoTrack-kind"><code>VideoTrack.kind</code></dfn>
+ attributes must return the category of the track, if it has one, or
+ the empty string otherwise.</p>
<p>The category of a track is the string given in the first column
of the table below that is the most appropriate for the track based
@@ -24855,108 +24938,108 @@
what the category given in the cell in the first column of that row
applies to; a category is only appropriate for an audio track if it
applies to audio tracks, and a category is only appropriate for
- video tracks if it applies to video tracks.</p>
+ video tracks if it applies to video tracks. Categories must only be
+ returned for <code><a href="#audiotrack">AudioTrack</a></code> objects if they are appropriate
+ for audio, and must only be returned for <code><a href="#videotrack">VideoTrack</a></code>
+ objects if they are appropriate for video.</p>
- </div><table id="dom-TrackList-getKind-categories"><caption>Return values for <code title="dom-TrackList-getKind"><a href="#dom-tracklist-getkind">getKind()</a></code></caption>
+ </div><table id="dom-TrackList-getKind-categories"><caption>Return values for <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">AudioTrack.kind()</a></code> and <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">VideoTrack.kind()</a></code></caption>
<thead><tr><th>Category
<th>Definition
<th>Applies to...</th>
<th>Examples
- <tbody><tr><td>"<dfn id="dom-tracklist-getkind-alternate" title="dom-TrackList-getKind-alternate"><code>alternative</code></dfn>"
+ <tbody><tr><td>"<dfn id="value-track-kind-alternate" title="value-track-kind-alternate"><code>alternative</code></dfn>"
<td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
<td>Audio and video.
<td>Ogg: "audio/alterate" or "video/alternate".
- <tr><td>"<dfn id="dom-tracklist-getkind-description" title="dom-TrackList-getKind-description"><code>description</code></dfn>"
+ <tr><td>"<dfn id="value-track-kind-description" title="value-track-kind-description"><code>description</code></dfn>"
<td>An audio description of a video track.
<td>Audio only.
<td>Ogg: "audio/audiodesc".
- <tr><td>"<dfn id="dom-tracklist-getkind-main" title="dom-TrackList-getKind-main"><code>main</code></dfn>"
+ <tr><td>"<dfn id="value-track-kind-main" title="value-track-kind-main"><code>main</code></dfn>"
<td>The primary audio or video track.
<td>Audio and video.
<td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
- <tr><td>"<dfn id="dom-tracklist-getkind-sign" title="dom-TrackList-getKind-sign"><code>sign</code></dfn>"
+ <tr><td>"<dfn id="value-track-kind-sign" title="value-track-kind-sign"><code>sign</code></dfn>"
<td>A sign-language interpretation of an audio track.
<td>Video only.
<td>Ogg: "video/sign".
- <tr><td>"<dfn id="dom-tracklist-getkind-translation" title="dom-TrackList-getKind-translation"><code>translation</code></dfn>"
+ <tr><td>"<dfn id="value-track-kind-translation" title="value-track-kind-translation"><code>translation</code></dfn>"
<td>A translated version of the main track.
<td>Audio only.
<td>Ogg: "audio/dub".
- <tr><td>"<dfn id="dom-tracklist-getkind-none" title="dom-TrackList-getKind-none"><code></code></dfn>" (empty string)
+ <tr><td>"<dfn id="value-track-kind-commentary" title="value-track-kind-commentary"><code>commentary</code></dfn>"
+ <td>Commentary on the primary audio or video track, e.g. a director's commentary.
+ <td>Audio and video.
+ <td>No known formats expose this category at this time.
+
+ <tr><td>"<dfn id="value-track-kind-none" title="value-track-kind-none"><code></code></dfn>" (empty string)
<td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
<td>Audio and video.
<td>Any other track type or track role.
</table><div class="impl">
- <p>The <dfn id="dom-tracklist-getlabel" title="dom-TrackList-getLabel"><code>getLabel(<var title="">index</var>)</code></dfn> method must return the label of
- the track with index <var title="">index</var>, if there is one and
- it has a label. If there is no such track, then the method must
- instead throw an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is
- a track with index <var title="">index</var>, but it has no label,
- then the method must return the empty string.</p>
+ <p>The <dfn id="dom-audiotrack-label" title="dom-AudioTrack-label"><code>AudioTrack.label</code></dfn> and
+ <dfn id="dom-videotrack-label" title="dom-VideoTrack-label"><code>VideoTrack.label</code></dfn>
+ attributes must return the label of the track, if it has one, or the
+ empty string otherwise.</p>
- <p>The <dfn id="dom-tracklist-getlanguage" title="dom-TrackList-getLanguage"><code>getLanguage(<var title="">index</var>)</code></dfn> method must return the BCP 47
- language tag of the language of the track with index <var title="">index</var>, if there is one and it has a language. If
- there is no such track, then the method must instead throw an
- <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is a track with
- index <var title="">index</var>, but it has no language, or the user
+ <p>The <dfn id="dom-audiotrack-language" title="dom-AudioTrack-language"><code>AudioTrack.language</code></dfn>
+ and <dfn id="dom-videotrack-language" title="dom-VideoTrack-language"><code>VideoTrack.language</code></dfn>
+ attributes must return the BCP 47 language tag of the language of
+ the track, if it has one, or the empty string otherwise. If the user
agent is not able to express that language as a BCP 47 language tag
(for example because the language information in the <a href="#media-resource">media
resource</a>'s format is a free-form string without a defined
- interpretation), then the method must return the empty string.</p>
-
- <hr><p>A <code><a href="#multipletracklist">MultipleTrackList</a></code> object represents a track list
- where multiple tracks can be enabled simultaneously. Each track is
- either enabled or disabled.</p>
-
- <p>The <dfn id="dom-tracklist-isenabled" title="dom-TrackList-isEnabled"><code>isEnabled(<var title="">index</var>)</code></dfn> method must return true if there
- is a track with index <var title="">index</var>, and it is currently
- enabled, false if there is a track with index <var title="">index</var>, but it is currently disabled, and must throw
- an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception if there is no track with
- index <var title="">index</var>.</p>
-
- <p>The <dfn id="dom-tracklist-enable" title="dom-TrackList-enable"><code>enable(<var title="">index</var>)</code></dfn> method must enable the track with
- index <var title="">index</var>, if there is one. If there is not,
- it must instead throw an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
-
- <p>The <dfn id="dom-tracklist-disable" title="dom-TrackList-disable"><code>disable(<var title="">index</var>)</code></dfn> method must disable the track with
- index <var title="">index</var>, if there is one. If there is not,
- it must instead throw an <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
+ interpretation), then the method must return the empty string, as if
+ the track had no language.</p>
- <p>Whenever a track is enabled or disabled, the user agent must
- <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple event</a> named
- <code title="event-media-change">change</code> at the
- <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
+ <p>The <dfn id="dom-audiotrack-enabled" title="dom-AudioTrack-enabled"><code>AudioTrack.enabled</code></dfn>
+ attribute, on getting, must return true if the track is currently
+ enabled, and false otherwise. On setting, it must enable the track
+ if the new value is true, and disable it otherwise. (If the track is
+ no longer in an <code><a href="#audiotracklist">AudioTrackList</a></code> object, then the track
+ being enabled or disabled has no effect beyond changing the value of
+ the attribute on the <code><a href="#audiotrack">AudioTrack</a></code> object.)</p>
- <hr><p>An <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object represents a track list
- where exactly one track is selected at a time.</p>
+ <p>Whenever an audio track in an <code><a href="#audiotracklist">AudioTrackList</a></code> is
+ enabled or disabled, the user agent must <a href="#queue-a-task">queue a task</a>
+ to <a href="#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
+ <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p>
- <p>The <dfn id="dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex"><code>selectedIndex</code></dfn>
- attribute must return the index of the currently selected track. If
- the <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object does not represent any
- tracks, it must instead return −1.</p>
+ <p>The <dfn id="dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex"><code>VideoTrackList.selectedIndex</code></dfn>
+ attribute must return the index of the currently selected track, if
+ any. If the <code><a href="#videotracklist">VideoTrackList</a></code> object does not currently
+ represent any tracks, or if none of the tracks are selected, it must
+ instead return −1.</p>
- <p>The <dfn id="dom-tracklist-select" title="dom-TrackList-select"><code>select(<var title="">index</var>)</code></dfn> must select the track with index
- <var title="">index</var>, if there is one, unselecting whichever
- track was previously selected. If there is no track with index <var title="">index</var>, it must instead throw an
- <code><a href="#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
+ <p>The <dfn id="dom-videotrack-selected" title="dom-VideoTrack-selected"><code>VideoTrack.selected</code></dfn>
+ attribute, on getting, must return true if the track is currently
+ selected, and false otherwise. On setting, it must select the track
+ if the new value is true, and unselect it otherwise. If the track is
+ in a <code><a href="#videotracklist">VideoTrackList</a></code>, then all the other
+ <code><a href="#videotrack">VideoTrack</a></code> objects in that list must be unselected. (If
+ the track is no longer in a <code><a href="#videotracklist">VideoTrackList</a></code> object, then
+ the track being selected or unselected has no effect beyond changing
+ the value of the attribute on the <code><a href="#videotrack">VideoTrack</a></code>
+ object.)</p>
- <p>Whenever the selected track is changed, the user agent must
- <a href="#queue-a-task">queue a task</a> to <a href="#fire-a-simple-event">fire a simple event</a> named
- <code title="event-media-change">change</code> at the
- <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
+ <p>Whenever a track in a <code><a href="#videotracklist">VideoTrackList</a></code> that was
+ previously not selected is selected, the user agent must <a href="#queue-a-task">queue
+ a task</a> to <a href="#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
+ <code><a href="#videotracklist">VideoTrackList</a></code> object.</p>
<hr><p>The following are the <a href="#event-handlers">event handlers</a> (and their
corresponding <a href="#event-handler-event-type" title="event handler event type">event handler
event types</a>) that must be supported, as IDL attributes, by
- all objects implementing the <code><a href="#tracklist">TrackList</a></code>
- interface:</p>
+ all objects implementing the <code><a href="#audiotracklist">AudioTrackList</a></code> and
+ <code><a href="#videotracklist">VideoTrackList</a></code> interfaces:</p>
<table><thead><tr><th><a href="#event-handlers" title="event handlers">Event handler</a> <th><a href="#event-handler-event-type">Event handler event type</a>
<tbody><tr><td><dfn id="handler-tracklist-onchange" title="handler-TrackList-onchange"><code>onchange</code></dfn> <td> <code title="event-change">change</code>
@@ -26342,7 +26425,7 @@
<p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn>
attribute of <a href="#media-element" title="media element">media elements</a> must
- return an <span title="array host objects">array host object</span>
+ return an <a href="#array-host-objects" title="array host objects">array host object</a>
for objects of type <code><a href="#texttrack">TextTrack</a></code> that is <i>fixed
length</i> and <i>read only</i>. The same object must be returned
each time the attribute is accessed. <a href="#refsWEBIDL">[WEBIDL]</a></p>
@@ -26375,7 +26458,9 @@
attribute <a href="#function">Function</a>? <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
};
-<a href="#texttrack">TextTrack</a> implements <a href="#eventtarget">EventTarget</a>;</pre><dl class="domintro"><dt><var title="">textTrack</var> . <code title="dom-TextTrack-kind"><a href="#dom-texttrack-kind">kind</a></code></dt>
+<a href="#texttrack">TextTrack</a> implements <a href="#eventtarget">EventTarget</a>;
+
+typedef <a href="#texttrack">TextTrack</a>[] <dfn id="texttracklist">TextTrackList</dfn>;</pre><dl class="domintro"><dt><var title="">textTrack</var> . <code title="dom-TextTrack-kind"><a href="#dom-texttrack-kind">kind</a></code></dt>
<dd>
<p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
</dd>
@@ -26735,15 +26820,15 @@
cue">cues</a> in the list represented by the
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
- <p>The <span>supported property indicies</span> of a
+ <p>The <a href="#supported-property-indices">supported property indices</a> of a
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
minus one, if any. If there are no <a href="#text-track-cue" title="text track
- cue">cues</a> in the list, there are no <span>supported property
- indicies</span>.</p>
+ cue">cues</a> in the list, there are no <a href="#supported-property-indices">supported property
+ indices</a>.</p>
- <p>To <span>determine the value of an indexed property</span> for a
+ <p>To <a href="#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
given index <var title="">index</var>, the user agent must return
the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
Received on Thursday, 30 June 2011 23:53:18 UTC