[giow] (0) Add TextTrack.id and TextTrackList.getTrackById to enable …

…in-band text tracks to be identified and selected from JS Fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=22015 Affected topics: Video Text Tracks, Video and Audio git-svn-id: http://svn.whatwg.org/webapps@7947 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Jun 8, 2013 · f57e84d · f57e84d
1 parent 50e564b
commit f57e84d
Show file tree

Hide file tree

Showing 3 changed files with 130 additions and 12 deletions.
diff --git a/complete.html b/complete.html
@@ -256,7 +256,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1 class=allcaps>HTML</h1>
-    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 7 June 2013</h2>
+    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 8 June 2013</h2>
    </hgroup><dl><dt><strong>Web developer edition:</strong></dt>
     <dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
     <dt>Multiple-page version:</dt>
@@ -29605,9 +29605,10 @@ <h6 id=audiotracklist-and-videotracklist-objects><span class=secno>4.8.10.10.1 <
   <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>
+  <code><a href=#videotrack>VideoTrack</a></code> object (respectively) in the <code><a href=#audiotracklist>AudioTrackList</a></code> or
+  <code><a href=#videotracklist>VideoTrackList</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.
@@ -31339,6 +31340,7 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
   <pre class=idl>interface <dfn id=texttracklist>TextTrackList</dfn> : <a href=#eventtarget>EventTarget</a> {
   readonly attribute unsigned long <a href=#dom-texttracklist-length title=dom-TextTrackList-length>length</a>;
   getter <a href=#texttrack>TextTrack</a> (unsigned long index);
+  <a href=#texttrack>TextTrack</a>? <a href=#dom-texttracklist-gettrackbyid title=dom-TextTrackList-getTrackById>getTrackById</a>(DOMString id);
 
            attribute <a href=#eventhandler>EventHandler</a> <a href=#handler-texttracklist-onaddtrack title=handler-TextTrackList-onaddtrack>onaddtrack</a>;
            attribute <a href=#eventhandler>EventHandler</a> <a href=#handler-texttracklist-onremovetrack title=handler-TextTrackList-onremovetrack>onremovetrack</a>;
@@ -31354,6 +31356,14 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
     <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object representing the <var title="">n</var>th <a href=#text-track>text track</a> in the <a href=#media-element>media element</a>'s <a href=#list-of-text-tracks>list of text tracks</a>.</p>
    </dd>
 
+   <dt><var title="">textTrack</var> = <var title="">media</var> . <code title=dom-media-textTracks><a href=#dom-media-texttracks>textTracks</a></code> . <code title=dom-TextTrackList-getTrackById><a href=#dom-texttracklist-gettrackbyid>getTrackById</a></code>( <var title="">id</var> )</dt>
+
+   <dd>
+
+    <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object with the given identifier, or null if no track has that identifier.</p>
+
+   </dd>
+
    <dt><var title="">track</var> . <code title=dom-track-track><a href=#dom-track-track>track</a></code></dt>
    <dd>
     <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object representing the <code><a href=#the-track-element>track</a></code> element's <a href=#text-track>text track</a>.</p>
@@ -31391,6 +31401,11 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
   <code><a href=#texttracklist>TextTrackList</a></code> object for a given index <var title="">index</var>, the user agent must return the <var title="">index</var>th <a href=#text-track>text track</a> in the list
   represented by the <code><a href=#texttracklist>TextTrackList</a></code> object.</p>
 
+  <p>The <dfn id=dom-texttracklist-gettrackbyid title=dom-TextTrackList-getTrackById><code>getTrackById(<var title="">id</var>)</code></dfn> method must return the first <code><a href=#texttrack>TextTrack</a></code> in the
+  <code><a href=#texttracklist>TextTrackList</a></code> object whose <code title=dom-TextTrack-id><a href=#dom-texttrack-id>id</a></code> IDL attribute
+  would return a value equal to the value of the <var title="">id</var> argument. When no tracks
+  match the given argument, the method must return null.</p>
+
   </div>
 
   <hr><pre class=idl>enum <dfn id=texttrackmode>TextTrackMode</dfn> {<!--
@@ -31407,6 +31422,8 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
   readonly attribute <a href=#texttrackkind>TextTrackKind</a> <a href=#dom-texttrack-kind title=dom-TextTrack-kind>kind</a>;
   readonly attribute DOMString <a href=#dom-texttrack-label title=dom-TextTrack-label>label</a>;
   readonly attribute DOMString <a href=#dom-texttrack-language title=dom-TextTrack-language>language</a>;
+
+  readonly attribute DOMString <a href=#dom-texttrack-id title=dom-TextTrack-id>id</a>;
   readonly attribute DOMString <a href=#dom-texttrack-inbandmetadatatrackdispatchtype title=dom-TextTrack-inBandMetadataTrackDispatchType>inBandMetadataTrackDispatchType</a>;
 
            attribute <a href=#texttrackmode>TextTrackMode</a> <a href=#dom-texttrack-mode title=dom-TextTrack-mode>mode</a>;
@@ -31443,6 +31460,19 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
     <p>Returns the <a href=#text-track-language>text track language</a> string.</p>
    </dd>
 
+   <dt><var title="">textTrack</var> . <code title=dom-TextTrack-id><a href=#dom-texttrack-id>id</a></code></dt>
+   <dd>
+
+    <p>Returns the ID of the given track.</p>
+
+    <p>For in-band tracks, 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=dom-TextTrackList-getTrackById><a href=#dom-texttracklist-gettrackbyid>getTrackById()</a></code> method. <a href=#refsMEDIAFRAG>[MEDIAFRAG]</a></p>
+
+    <p>For <code><a href=#texttrack>TextTrack</a></code> objects corresponding to <code><a href=#the-track-element>track</a></code> elements, this is the
+    ID of the <code><a href=#the-track-element>track</a></code> element.</p>
+
+   </dd>
+
    <dt><var title="">textTrack</var> . <code title=dom-TextTrack-inBandMetadataTrackDispatchType><a href=#dom-texttrack-inbandmetadatatrackdispatchtype>inBandMetadataTrackDispatchType</a></code></dt>
    <dd>
     <p>Returns the <a href=#text-track-in-band-metadata-track-dispatch-type>text track in-band metadata track dispatch type</a> string.</p>
@@ -31546,6 +31576,14 @@ <h6 id=text-track-api><span class=secno>4.8.10.12.5 </span>Text track API</h6>
   <a href=#text-track-language>text track language</a> of the <a href=#text-track>text track</a> that the <code><a href=#texttrack>TextTrack</a></code>
   object represents.</p>
 
+  <p>The <dfn id=dom-texttrack-id title=dom-TextTrack-id><code>id</code></dfn> attribute returns the track's
+  identifier, if it has one, or the empty string otherwise. For tracks that correspond to
+  <code><a href=#the-track-element>track</a></code> elements, the track's identifier is the value of the element's <code title=attr-id><a href=#the-id-attribute>id</a></code> attribute, if any. For in-band tracks, the track's identifier is
+  specified by the <a href=#media-resource>media resource</a>. 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-texttrack-inbandmetadatatrackdispatchtype title=dom-TextTrack-inBandMetadataTrackDispatchType><code>inBandMetadataTrackDispatchType</code></dfn>
   attribute must return the <a href=#text-track-in-band-metadata-track-dispatch-type>text track in-band metadata track dispatch type</a> of the
   <a href=#text-track>text track</a> that the <code><a href=#texttrack>TextTrack</a></code> object represents.</p>

diff --git a/index b/index
@@ -256,7 +256,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1 class=allcaps>HTML</h1>
-    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 7 June 2013</h2>
+    <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 8 June 2013</h2>
    </hgroup><dl><dt><strong>Web developer edition:</strong></dt>
     <dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
     <dt>Multiple-page version:</dt>
@@ -29605,9 +29605,10 @@ interface <dfn id=videotrack>VideoTrack</dfn> {
   <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>
+  <code><a href=#videotrack>VideoTrack</a></code> object (respectively) in the <code><a href=#audiotracklist>AudioTrackList</a></code> or
+  <code><a href=#videotracklist>VideoTrackList</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.
@@ -31339,6 +31340,7 @@ interface <dfn id=mediacontroller>MediaController</dfn> : <a href=#eventtarget>E
   <pre class=idl>interface <dfn id=texttracklist>TextTrackList</dfn> : <a href=#eventtarget>EventTarget</a> {
   readonly attribute unsigned long <a href=#dom-texttracklist-length title=dom-TextTrackList-length>length</a>;
   getter <a href=#texttrack>TextTrack</a> (unsigned long index);
+  <a href=#texttrack>TextTrack</a>? <a href=#dom-texttracklist-gettrackbyid title=dom-TextTrackList-getTrackById>getTrackById</a>(DOMString id);
 
            attribute <a href=#eventhandler>EventHandler</a> <a href=#handler-texttracklist-onaddtrack title=handler-TextTrackList-onaddtrack>onaddtrack</a>;
            attribute <a href=#eventhandler>EventHandler</a> <a href=#handler-texttracklist-onremovetrack title=handler-TextTrackList-onremovetrack>onremovetrack</a>;
@@ -31354,6 +31356,14 @@ interface <dfn id=mediacontroller>MediaController</dfn> : <a href=#eventtarget>E
     <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object representing the <var title="">n</var>th <a href=#text-track>text track</a> in the <a href=#media-element>media element</a>'s <a href=#list-of-text-tracks>list of text tracks</a>.</p>
    </dd>
 
+   <dt><var title="">textTrack</var> = <var title="">media</var> . <code title=dom-media-textTracks><a href=#dom-media-texttracks>textTracks</a></code> . <code title=dom-TextTrackList-getTrackById><a href=#dom-texttracklist-gettrackbyid>getTrackById</a></code>( <var title="">id</var> )</dt>
+
+   <dd>
+
+    <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object with the given identifier, or null if no track has that identifier.</p>
+
+   </dd>
+
    <dt><var title="">track</var> . <code title=dom-track-track><a href=#dom-track-track>track</a></code></dt>
    <dd>
     <p>Returns the <code><a href=#texttrack>TextTrack</a></code> object representing the <code><a href=#the-track-element>track</a></code> element's <a href=#text-track>text track</a>.</p>
@@ -31391,6 +31401,11 @@ interface <dfn id=mediacontroller>MediaController</dfn> : <a href=#eventtarget>E
   <code><a href=#texttracklist>TextTrackList</a></code> object for a given index <var title="">index</var>, the user agent must return the <var title="">index</var>th <a href=#text-track>text track</a> in the list
   represented by the <code><a href=#texttracklist>TextTrackList</a></code> object.</p>
 
+  <p>The <dfn id=dom-texttracklist-gettrackbyid title=dom-TextTrackList-getTrackById><code>getTrackById(<var title="">id</var>)</code></dfn> method must return the first <code><a href=#texttrack>TextTrack</a></code> in the
+  <code><a href=#texttracklist>TextTrackList</a></code> object whose <code title=dom-TextTrack-id><a href=#dom-texttrack-id>id</a></code> IDL attribute
+  would return a value equal to the value of the <var title="">id</var> argument. When no tracks
+  match the given argument, the method must return null.</p>
+
   </div>
 
   <hr><pre class=idl>enum <dfn id=texttrackmode>TextTrackMode</dfn> {<!--
@@ -31407,6 +31422,8 @@ interface <dfn id=texttrack>TextTrack</dfn> : <a href=#eventtarget>EventTarget</
   readonly attribute <a href=#texttrackkind>TextTrackKind</a> <a href=#dom-texttrack-kind title=dom-TextTrack-kind>kind</a>;
   readonly attribute DOMString <a href=#dom-texttrack-label title=dom-TextTrack-label>label</a>;
   readonly attribute DOMString <a href=#dom-texttrack-language title=dom-TextTrack-language>language</a>;
+
+  readonly attribute DOMString <a href=#dom-texttrack-id title=dom-TextTrack-id>id</a>;
   readonly attribute DOMString <a href=#dom-texttrack-inbandmetadatatrackdispatchtype title=dom-TextTrack-inBandMetadataTrackDispatchType>inBandMetadataTrackDispatchType</a>;
 
            attribute <a href=#texttrackmode>TextTrackMode</a> <a href=#dom-texttrack-mode title=dom-TextTrack-mode>mode</a>;
@@ -31443,6 +31460,19 @@ interface <dfn id=texttrack>TextTrack</dfn> : <a href=#eventtarget>EventTarget</
     <p>Returns the <a href=#text-track-language>text track language</a> string.</p>
    </dd>
 
+   <dt><var title="">textTrack</var> . <code title=dom-TextTrack-id><a href=#dom-texttrack-id>id</a></code></dt>
+   <dd>
+
+    <p>Returns the ID of the given track.</p>
+
+    <p>For in-band tracks, 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=dom-TextTrackList-getTrackById><a href=#dom-texttracklist-gettrackbyid>getTrackById()</a></code> method. <a href=#refsMEDIAFRAG>[MEDIAFRAG]</a></p>
+
+    <p>For <code><a href=#texttrack>TextTrack</a></code> objects corresponding to <code><a href=#the-track-element>track</a></code> elements, this is the
+    ID of the <code><a href=#the-track-element>track</a></code> element.</p>
+
+   </dd>
+
    <dt><var title="">textTrack</var> . <code title=dom-TextTrack-inBandMetadataTrackDispatchType><a href=#dom-texttrack-inbandmetadatatrackdispatchtype>inBandMetadataTrackDispatchType</a></code></dt>
    <dd>
     <p>Returns the <a href=#text-track-in-band-metadata-track-dispatch-type>text track in-band metadata track dispatch type</a> string.</p>
@@ -31546,6 +31576,14 @@ interface <dfn id=texttrack>TextTrack</dfn> : <a href=#eventtarget>EventTarget</
   <a href=#text-track-language>text track language</a> of the <a href=#text-track>text track</a> that the <code><a href=#texttrack>TextTrack</a></code>
   object represents.</p>
 
+  <p>The <dfn id=dom-texttrack-id title=dom-TextTrack-id><code>id</code></dfn> attribute returns the track's
+  identifier, if it has one, or the empty string otherwise. For tracks that correspond to
+  <code><a href=#the-track-element>track</a></code> elements, the track's identifier is the value of the element's <code title=attr-id><a href=#the-id-attribute>id</a></code> attribute, if any. For in-band tracks, the track's identifier is
+  specified by the <a href=#media-resource>media resource</a>. 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-texttrack-inbandmetadatatrackdispatchtype title=dom-TextTrack-inBandMetadataTrackDispatchType><code>inBandMetadataTrackDispatchType</code></dfn>
   attribute must return the <a href=#text-track-in-band-metadata-track-dispatch-type>text track in-band metadata track dispatch type</a> of the
   <a href=#text-track>text track</a> that the <code><a href=#texttrack>TextTrack</a></code> object represents.</p>