[html5] r6275 - / images
whatwg at whatwg.org
whatwg at whatwg.org
Thu Jun 30 16:52:45 PDT 2011
Author: ianh
Date: 2011-06-30 16:52:43 -0700 (Thu, 30 Jun 2011)
New Revision: 6275
Added:
images/media-stream-1.png
images/media-stream-2.png
Modified:
complete.html
index
source
Log:
[giow] (0) Revamp how audioTracks and videoTracks work on HTMLMediaElement and MediaStream.
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=12530
Modified: complete.html
===================================================================
--- complete.html 2011-06-24 00:32:39 UTC (rev 6274)
+++ complete.html 2011-06-30 23:52:43 UTC (rev 6275)
@@ -239,7 +239,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>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Living Standard — Last Updated 24 June 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 30 June 2011</h2>
</hgroup><dl><dt>Multiple-page version:</dt>
<dd><a href=http://www.whatwg.org/specs/web-apps/current-work/complete/>http://www.whatwg.org/specs/web-apps/current-work/complete/</a></dd>
<dt>One-page version:</dt>
@@ -577,7 +577,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>
@@ -1009,7 +1009,10 @@
<ol>
<li><a href=#introduction-10><span class=secno>9.1 </span>Introduction</a></li>
<li><a href=#obtaining-local-multimedia-content><span class=secno>9.2 </span>Obtaining local multimedia content</a></li>
- <li><a href=#stream-api><span class=secno>9.3 </span>Stream API</a></li>
+ <li><a href=#stream-api><span class=secno>9.3 </span>Stream API</a>
+ <ol>
+ <li><a href=#introduction-11><span class=secno>9.3.1 </span>Introduction</a></li>
+ <li><a href=#interface-definitions><span class=secno>9.3.2 </span>Interface definitions</a></ol></li>
<li><a href=#peer-to-peer-connections><span class=secno>9.4 </span>Peer-to-peer connections</a></li>
<li><a href=#the-data-stream><span class=secno>9.5 </span>The data stream</a>
<ol>
@@ -1019,7 +1022,7 @@
<li><a href=#event-summary><span class=secno>9.8 </span>Event Summary</a></ol></li>
<li><a href=#workers><span class=secno>10 </span>Web workers</a>
<ol>
- <li><a href=#introduction-11><span class=secno>10.1 </span>Introduction</a>
+ <li><a href=#introduction-12><span class=secno>10.1 </span>Introduction</a>
<ol>
<li><a href=#scope-0><span class=secno>10.1.1 </span>Scope</a></li>
<li><a href=#tutorial><span class=secno>10.1.2 </span>Tutorial</a>
@@ -1080,7 +1083,7 @@
<li><a href=#garbage-collection-2><span class=secno>11.3.3.2 </span>Garbage collection</a></ol></ol></li>
<li><a href=#web-messaging><span class=secno>11.4 </span>Cross-document messaging</a>
<ol>
- <li><a href=#introduction-12><span class=secno>11.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-13><span class=secno>11.4.1 </span>Introduction</a></li>
<li><a href=#security-postmsg><span class=secno>11.4.2 </span>Security</a>
<ol>
<li><a href=#authors><span class=secno>11.4.2.1 </span>Authors</a></li>
@@ -1088,14 +1091,14 @@
<li><a href=#posting-messages><span class=secno>11.4.3 </span>Posting messages</a></ol></li>
<li><a href=#channel-messaging><span class=secno>11.5 </span>Channel messaging</a>
<ol>
- <li><a href=#introduction-13><span class=secno>11.5.1 </span>Introduction</a></li>
+ <li><a href=#introduction-14><span class=secno>11.5.1 </span>Introduction</a></li>
<li><a href=#message-channels><span class=secno>11.5.2 </span>Message channels</a></li>
<li><a href=#message-ports><span class=secno>11.5.3 </span>Message ports</a>
<ol>
<li><a href=#ports-and-garbage-collection><span class=secno>11.5.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
<li><a href=#webstorage><span class=secno>12 </span>Web storage</a>
<ol>
- <li><a href=#introduction-14><span class=secno>12.1 </span>Introduction</a></li>
+ <li><a href=#introduction-15><span class=secno>12.1 </span>Introduction</a></li>
<li><a href=#storage><span class=secno>12.2 </span>The API</a>
<ol>
<li><a href=#the-storage-interface><span class=secno>12.2.1 </span>The <code>Storage</code> interface</a></li>
@@ -1274,10 +1277,10 @@
<li><a href=#parsing-xhtml-fragments><span class=secno>14.4 </span>Parsing XHTML fragments</a></ol></li>
<li><a href=#rendering><span class=secno>15 </span>Rendering</a>
<ol>
- <li><a href=#introduction-15><span class=secno>15.1 </span>Introduction</a></li>
+ <li><a href=#introduction-16><span class=secno>15.1 </span>Introduction</a></li>
<li><a href=#the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>15.2 </span>The CSS user agent style sheet and presentational hints</a>
<ol>
- <li><a href=#introduction-16><span class=secno>15.2.1 </span>Introduction</a></li>
+ <li><a href=#introduction-17><span class=secno>15.2.1 </span>Introduction</a></li>
<li><a href=#display-types><span class=secno>15.2.2 </span>Display types</a></li>
<li><a href=#margins-and-padding><span class=secno>15.2.3 </span>Margins and padding</a></li>
<li><a href=#alignment><span class=secno>15.2.4 </span>Alignment</a></li>
@@ -1303,7 +1306,7 @@
<li><a href=#toolbars-0><span class=secno>15.3.6 </span>Toolbars</a></ol></li>
<li><a href=#bindings><span class=secno>15.4 </span>Bindings</a>
<ol>
- <li><a href=#introduction-17><span class=secno>15.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-18><span class=secno>15.4.1 </span>Introduction</a></li>
<li><a href=#the-button-element-0><span class=secno>15.4.2 </span>The <code>button</code> element</a></li>
<li><a href=#the-details-element-0><span class=secno>15.4.3 </span>The <code>details</code> element</a></li>
<li><a href=#the-input-element-as-a-text-entry-widget><span class=secno>15.4.4 </span>The <code>input</code> element as a text entry widget</a></li>
@@ -3585,9 +3588,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
@@ -26920,9 +26923,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>
@@ -29479,9 +29482,7 @@
</div>
-<!--PEERCONNECTION-->
<h5 id=media-resources-with-multiple-media-tracks><span class=secno>4.8.10.10 </span>Media resources with multiple media tracks</h5>
-<!--PEERCONNECTION-->
<p>A <a href=#media-resource>media resource</a> can have multiple embedded audio
and video tracks. For example, in addition to the primary video and
@@ -29493,7 +29494,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>
@@ -29502,7 +29503,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>
@@ -29511,23 +29512,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>
@@ -29552,9 +29554,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; <!-- should escape this probably -->
sign.autoplay = true;
sign.controller = controller;
container.appendChild(sign);
@@ -29568,42 +29570,45 @@
</div>
-<!--PEERCONNECTION-->
- <h6 id=tracklist-objects><span class=secno>4.8.10.10.1 </span><code><a href=#tracklist>TrackList</a></code> objects</h6>
+ <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>
- <!-- should probably move this section out since it is also used by
- the video conferencing stuff -->
+ <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.</p>
-<!--PEERCONNECTION-->
- <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>
-<!--PEERCONNECTION-->
+ <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>;
+};
- <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);
+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=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=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=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);
+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="">tracks</var> . <code title=dom-TrackList-length><a href=#dom-tracklist-length>length</a></code></dt>
+ <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>
@@ -29611,65 +29616,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>
@@ -29677,42 +29691,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
@@ -29723,110 +29801,110 @@
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>
+ <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><!-- added because of the volume of use cases, but we should remove it if none of the formats start supporting it --><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>
+ interpretation), then the method must return the empty string, as if
+ the track had no language.</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-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>
- <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>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-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-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-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>
+ <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 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>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>An <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object represents a track list
- where exactly one track is selected at a time.</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-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>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>
-
<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>
@@ -29865,7 +29943,6 @@
selection -->
</div>
-<!--PEERCONNECTION-->
<h5 id=synchronising-multiple-media-elements><span class=secno>4.8.10.11 </span>Synchronising multiple media elements</h5>
@@ -31493,7 +31570,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>
@@ -31528,8 +31605,10 @@
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>
+<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>
@@ -31905,15 +31984,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>
@@ -74893,14 +74972,14 @@
stream.</p>
<p>If <var title="">audio</var> is true, then the provided media
- should include an audio component. If <var title="">audio</var>
+ should include an audio track. If <var title="">audio</var>
is false, then the provided media must not include an audio
- component.</p>
+ track.</p>
<p>If <var title="">video</var> is true, then the provided media
- should include a video component. If <var title="">video</var> is
+ should include a video track. If <var title="">video</var> is
false, then the provided media must not include a video
- component.</p>
+ track.</p>
<p>User agents are encouraged to default to using the user's
primary or system default camera and/or microphone (as
@@ -74987,6 +75066,8 @@
<h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
+ <h4 id=introduction-11><span class=secno>9.3.1 </span>Introduction</h4>
+
<p>The <code><a href=#mediastream>MediaStream</a></code> interface is used to represent
streams of media data, typically (but not necessarily) of audio
and/or video content, e.g. from a local camera or a remote site. The
@@ -74996,7 +75077,318 @@
user agents to manipulate media streams in whatever fashion is most
suitable on the user's platform.</p>
- <p>The <code><a href=#localmediastream>LocalMediaStream</a></code> interface is used when the user
+ <p>Each <code><a href=#mediastream>MediaStream</a></code> object can represent zero or more
+ tracks, in particular audio and video tracks. Tracks can contain
+ multiple channels of parallel data; for example a single audio track
+ could have nine channels of audio data to represent a 7.2 surround
+ sound audio track.</p>
+
+ <p>Each track represented by a <code><a href=#mediastream>MediaStream</a></code> object has a
+ corresponding <code><a href=#streamtrack>StreamTrack</a></code> object.</p>
+
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object has an input and an output. The
+ input depends on how the object was created: a
+ <code><a href=#localmediastream>LocalMediaStream</a></code> object generated by a <code title=dom-navigator-getUserMedia><a href=#dom-navigator-getusermedia>getUserMedia()</a></code> call, for
+ instance, might take its input from the user's local camera, while a
+ <code><a href=#mediastream>MediaStream</a></code> created by a <code><a href=#peerconnection>PeerConnection</a></code>
+ object will take as input the data received from a remote peer. The
+ output of the object controls how the object is used, e.g. what is
+ saved if the object is written to a file, what is displayed if the
+ object is used in a <code><a href=#the-video-element>video</a></code> element, or indeed what is
+ transmitted to a remote peer if the object is used with a
+ <code><a href=#peerconnection>PeerConnection</a></code> object.</p>
+
+ <p>Each track in a <code><a href=#mediastream>MediaStream</a></code> object can be disabled,
+ meaning that it does not appear in the object's output. All tracks
+ are initially enabled.</p>
+
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object's output can be "forked" by
+ creating a new <code><a href=#mediastream>MediaStream</a></code> object from it using the
+ <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream()</a></code> constructor. The
+ new <code><a href=#mediastream>MediaStream</a></code> object's input is the output of the
+ object from which it was created, and its output is therefore at
+ most a subset of the "parent" object.</p>
+
+ <p><img alt="" src=http://images.whatwg.org/media-stream-1.png></p><!-- no alt since
+ it's all described in the previous paragraphs: this is just a
+ summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ stroke();
+ }
+ mediaStream(c,50,10, true);
+
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText('MediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>This can be used, for instance, in a video-conferencing scenario
+ to display the local video from the user's camera and microphone in
+ a local monitor, while only transmitting the audio to the remote
+ peer (e.g. in response to the user using a "video mute"
+ feature).</p>
+
+ <p><img alt="" src=http://images.whatwg.org/media-stream-2.png></p><!-- again, no
+ alt since it's all described in the previous paragraphs: this is
+ just a summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ lineTo(550, 210);
+ lineTo(50, 210);
+ lineTo(50, 320);
+ lineTo(550, 320);
+ lineTo(550,420);
+ stroke();
+ beginPath();
+ moveTo(50,320);
+ lineTo(50,420);
+ stroke();
+ restore();
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ fillText('<video>', 50, 440);
+ fillText('PeerConnection', 550, 440);
+ font = '100 8px "Press Start 2P", sans-serif';
+ }
+ cameraIcon(c,25,98)
+ mediaStream(c,50,10, true);
+ mediaStream(c,50,233, false);
+
+ with (c) {
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'middle';
+ fillStyle = 'gray';
+
+ fillText('from', 4, 130);
+ fillText('getUserMedia()', 4, 140);
+
+ fillText('via URL.getObjectURL()', 4, 450);
+
+ textAlign = 'center';
+ fillText('via addStream()', 550, 450);
+ }
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText(!vid ? 'MediaStream' : 'LocalMediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>If a track in a <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is disabled, it does not have a corresponding
+ track in any <code><a href=#mediastream>MediaStream</a></code> objects that were created from
+ <var title="">parent</var>. When a track in a
+ <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is disabled, any
+ <code><a href=#streamtrack>StreamTrack</a></code> objects corresponding to the tracks in any
+ <code><a href=#mediastream>MediaStream</a></code> objects that were created from <var title="">parent</var> are disassociated from any track, and must not
+ be reused for tracks again. If a disabled track in a
+ <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is re-enabled,
+ from the perspective of any <code><a href=#mediastream>MediaStream</a></code> objects that
+ were created from <var title="">parent</var> it is a new track and
+ thus new <code><a href=#streamtrack>StreamTrack</a></code> objects must be created for the
+ tracks that correspond to the re-enabled track.</p>
+
+ <hr><p>The <code><a href=#localmediastream>LocalMediaStream</a></code> interface is used when the user
agent is generating the stream's data (e.g. from a camera or
streaming it from a local video file). It allows authors to control
individual tracks during the generation of the content, e.g. to
@@ -75010,14 +75402,20 @@
live video from pre-recorded video, which can help protect the
user's privacy.</p>
+
+ <h4 id=interface-definitions><span class=secno>9.3.2 </span>Interface definitions</h4>
+
<!-- v2: support reading the bits from the stream directly, for use
with streaming over WebSocket? Or do we rely on FileReader for that?
sicking suggests defining a DataStream or BlobStream interface that
you can get from a Stream to get to the underlying data; such an
object would then be readable using the File API -->
- <pre class=idl>interface <dfn id=mediastream>MediaStream</dfn> {
+ <pre class=idl>[<a href=#dom-mediastream title=dom-MediaStream>Constructor</a>(in <a href=#mediastream>MediaStream</a> parentStream)]
+interface <dfn id=mediastream>MediaStream</dfn> {
readonly attribute DOMString <a href=#dom-mediastream-label title=dom-MediaStream-label>label</a>;
+ readonly attribute <a href=#streamtracklist>StreamTrackList</a> <a href=#dom-mediastream-tracks title=dom-MediaStream-tracks>tracks</a>;
+
<a href=#mediastreamrecorder>MediaStreamRecorder</a> <a href=#dom-mediastream-record title=dom-MediaStream-record>record</a>();
<!--
const unsigned short <span title="dom-MediaStream-LOADING">LOADING</span> = 0; -->
@@ -75030,16 +75428,29 @@
interface <dfn id=localmediastream>LocalMediaStream</dfn> : <a href=#mediastream>MediaStream</a> {
void <a href=#dom-mediastream-stop title=dom-MediaStream-stop>stop</a>();
+};
- // track control
- readonly attribute <a href=#multipletracklist>MultipleTrackList</a> <a href=#dom-mediastream-audiotracks title=dom-MediaStream-audioTracks>audioTracks</a>;
- readonly attribute <a href=#exclusivetracklist>ExclusiveTrackList</a> <a href=#dom-mediastream-videotracks title=dom-MediaStream-videoTracks>videoTracks</a>;
+typedef <a href=#streamtrack>StreamTrack</a>[] <dfn id=streamtracklist>StreamTrackList</dfn>;
+
+interface <dfn id=streamtrack>StreamTrack</dfn> {
+ readonly attribute DOMString <a href=#dom-streamtrack-kind title=dom-StreamTrack-kind>kind</a>;
+ readonly attribute DOMString <a href=#dom-streamtrack-label title=dom-StreamTrack-label>label</a>;
+ attribute boolean <a href=#dom-streamtrack-enabled title=dom-StreamTrack-enabled>enabled</a>;
};</pre>
- <dl class=domintro><dt><var title="">stream</var> . <code title=dom-MediaStream-label><a href=#dom-mediastream-label>label</a></code></dt>
+ <dl class=domintro><dt><var title="">stream</var> = new <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream</a></code>( <var title="">parentStream</var> )</dt>
<dd>
+ <p>Creates a new <code><a href=#mediastream>MediaStream</a></code> object whose tracks are the enabled tracks of <var title="">parentStream</var>.</p>
+
+ </dd>
+
+
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-label><a href=#dom-mediastream-label>label</a></code></dt>
+
+ <dd>
+
<p>Returns a label that is unique to this stream, so that streams
can be recognised after they are sent through the
<code><a href=#peerconnection>PeerConnection</a></code> API.</p>
@@ -75067,29 +75478,71 @@
</dd>
- <dt><var title="">stream</var> . <code title=dom-MediaStream-audioTracks><a href=#dom-mediastream-audiotracks>audioTracks</a></code></dt>
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code></dt>
<dd>
- <p>Returns a <code><a href=#multipletracklist>MultipleTrackList</a></code> object representing
- the audio tracks available for mixing into the
- <code><a href=#localmediastream>LocalMediaStream</a></code>'s stream.</p>
+ <p>Returns a <code><a href=#streamtracklist>StreamTrackList</a></code> object representing
+ the tracks that can be enabled and disabled.</p>
</dd>
- <dt><var title="">stream</var> . <code title=dom-MediaStream-videoTracks><a href=#dom-mediastream-videotracks>videoTracks</a></code></dt>
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code> . <code title=dom-StreamTrackList-length>length</code></dt>
+
<dd>
- <p>Returns an <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object representing
- the video tracks available for the <code><a href=#localmediastream>LocalMediaStream</a></code>'s
- stream.</p>
+ <p>Returns the number of tracks in the list.</p>
</dd>
+ <dt><var title="">track</var> = <var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the specified <code><a href=#streamtrack>StreamTrack</a></code> object.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code></dt>
+
+ <dd>
+
+ <p>Returns the string "<code title="">audio</code>" if the track
+ is an audio track, and the string "<code title="">video</code>" if
+ it is a video track.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code></dt>
+
+ <dd>
+
+ <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-enabled><a href=#dom-streamtrack-enabled>enabled</a></code> [ = <var title="">value</var> ]</dt>
+
+ <dd>
+
+ <p>Returns true if the given track is active in the <code><a href=#mediastream>MediaStream</a></code>'s output, and false otherwise.</p>
+
+ <p>Can be set, to change whether the track is enabled or not.</p>
+
+ </dd>
+
</dl><div class=impl>
+ <p>The <dfn id=dom-mediastream title=dom-MediaStream><code>MediaStream(<var title="">parentStream</var>)</code></dfn> constructor must return a
+ new <code><a href=#mediastream>MediaStream</a></code> object whose tracks at any moment in
+ time are the enabled tracks of <var title="">parentStream</var> at
+ that moment.</p>
+
<p>The <dfn id=dom-mediastream-readystate title=dom-MediaStream-readyState><code>readyState</code></dfn>
attribute represents the state of the stream. It must return the
value to which the user agent last set it (as defined below). It can
@@ -75106,18 +75559,32 @@
or generating data, and will never receive or generate more data
for this stream).</dd>
- </dl><p>When a <code><a href=#mediastream>MediaStream</a></code> object is created, its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute must be
- set to <code title=dom-MediaStream-LIVE><a href=#dom-mediastream-live>LIVE</a></code> (1).</p>
+ </dl><p>When a <code><a href=#mediastream>MediaStream</a></code> object is created, its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute must
+ be set to <code title=dom-MediaStream-LIVE><a href=#dom-mediastream-live>LIVE</a></code> (1), unless
+ it is being created using the <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream()</a></code> constructor whose
+ argument is a <code><a href=#mediastream>MediaStream</a></code> object whose <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute has
+ the value <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2), in
+ which case the <code><a href=#mediastream>MediaStream</a></code> object must be created with
+ its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code>
+ attribute set to <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code>
+ (2).</p>
- <p>When a <code><a href=#mediastream>MediaStream</a></code> object ends for any reason other than
- the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method being invoked
- (e.g. because the user rescinds the permission for the page to use
- the local camera, or because the data comes from a finite file and
- the file's end has been reached and the user has not requested that
- it be looped, or because the stream comes from a remote peer and the
- remote peer has permanently stopped sending data), the user agent
- must <a href=#queue-a-task>queue a task</a> that runs the following steps:</p>
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object is said to <i>end</i> when the
+ user agent learns that no more data will ever be forthcoming for
+ this stream.</p>
+ <p>When a <code><a href=#mediastream>MediaStream</a></code> object ends for any reason other
+ than the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method
+ being invoked (e.g. because the user rescinds the permission for the
+ page to use the local camera, or because the data comes from a
+ finite file and the file's end has been reached and the user has not
+ requested that it be looped, or because the stream comes from a
+ remote peer and the remote peer has permanently stopped sending
+ data, or because the <code><a href=#mediastream>MediaStream</a></code> was created from
+ another <code><a href=#mediastream>MediaStream</a></code> and that stream has just itself
+ ended), the user agent must <a href=#queue-a-task>queue a task</a> that runs the
+ following steps:</p>
+
<ol><li><p>If the object's <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute has the
value <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2) already, then
abort these steps. (The <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code>
@@ -75171,7 +75638,7 @@
source, then the user agent should remove any active "on-air"
indicator. If the data is being generated from a prerecorded source
(e.g. a video file), any remaining content in the file is
- ignored.</li>
+ ignored. The stream has <i>ended</i>.</li>
<li><p>Set the object's <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute to
<code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2).</li>
@@ -75181,44 +75648,60 @@
</ol><p>The <a href=#task-source>task source</a> for the <a href=#concept-task title=concept-task>tasks</a> queued for the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method is the <a href=#dom-manipulation-task-source>DOM
manipulation task source</a>.</p>
- <hr><p>A <code><a href=#localmediastream>LocalMediaStream</a></code> can have multiple audio and video
+ <hr><p>A <code><a href=#mediastream>MediaStream</a></code> can have multiple audio and video
sources (e.g. because the user has multiple microphones, or because
the real source of the stream is a <a href=#media-resource>media resource</a> with
many media tracks). The stream represented by a
- <code><a href=#localmediastream>LocalMediaStream</a></code> has either zero or one audio track and
- either zero or one video track.</p>
+ <code><a href=#mediastream>MediaStream</a></code> thus has zero or more tracks.</p>
- <div class=impl>
+ <hr><p>The <dfn id=dom-mediastream-tracks title=dom-MediaStream-tracks><code>tracks</code></dfn>
+ attribute must return an <a href=#array-host-objects title="array host objects">array host
+ object</a> for objects of type <code><a href=#streamtrack>StreamTrack</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>
- <p>The <dfn id=dom-mediastream-audiotracks title=dom-MediaStream-audioTracks><code>audioTracks</code></dfn>
- attribute of a <code><a href=#localmediastream>LocalMediaStream</a></code> object must return a
- <a href=#live>live</a> <code><a href=#multipletracklist>MultipleTrackList</a></code> object representing
- the audio sources available to the <code><a href=#localmediastream>LocalMediaStream</a></code>. The
- same object must be returned each time. The
- <code><a href=#localmediastream>LocalMediaStream</a></code>'s output audio track must be the result
- of mixing all the enabled audio sources, if any.</p>
+ <p>The array must contain the <code><a href=#streamtrack>StreamTrack</a></code> objects that
+ correspond to the the tracks of the stream. The relative order of
+ all tracks in a user agent must be stable. All audio tracks must
+ precede all video tracks. Tracks that come from a <a href=#media-resource>media
+ resource</a> whose format defines an order must be in the order
+ defined by the format; tracks that come from a <a href=#media-resource>media
+ resource</a> whose format does not define an order must be in the
+ relative order in which the tracks are declared in that <a href=#media-resource>media
+ resource</a>. Within these constraints, the order is user-agent
+ defined.</p> <!-- doesn't matter currently since I can't think of
+ any way that you can get multiple tracks together. It would matter
+ if we allowed a MediaStream() constructor that took an array of
+ streams, though, or if getUserMedia() could return multiple audio or
+ video tracks. -->
- <p>The <dfn id=dom-mediastream-videotracks title=dom-MediaStream-videoTracks><code>videoTracks</code></dfn>
- attribute of a <code><a href=#localmediastream>LocalMediaStream</a></code> object must return a
- <a href=#live>live</a> <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object
- representing the video sources available to the
- <code><a href=#localmediastream>LocalMediaStream</a></code>. The same object must be returned each
- time. The <code><a href=#localmediastream>LocalMediaStream</a></code>'s output video track must be
- the selected video source, if any.</p>
+ <p>The <dfn id=dom-streamtrack-kind title=dom-StreamTrack-kind><code>StreamTrack.kind</code></dfn>
+ attribute must return the string "<code title="">audio</code>" if
+ the object's corresponding track is or was an audio track, "<code title="">video</code>" if the corresponding track is or was a video
+ track, and a user-agent defined string otherwise.</p>
<p>User agents may label audio and video sources (e.g. "Internal
- microphone" or "External USB Webcam"), in which case the <code title=dom-TrackList-getLabel><a href=#dom-tracklist-getlabel>getLabel()</a></code> methods (on the
- <code><a href=#multipletracklist>MultipleTrackList</a></code> and <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code>
- objects) must use the labels the user agent has assigned as the
- track labels of the source tracks of the <code><a href=#localmediastream>LocalMediaStream</a></code>
- object. Otherwise, the <code title=dom-TrackList-getLabel><a href=#dom-tracklist-getlabel>getLabel()</a></code> methods must use the
- empty string as the track labels of the source tracks of the
- <code><a href=#localmediastream>LocalMediaStream</a></code> object. The <code title=dom-TrackList-getLanguage><a href=#dom-tracklist-getlanguage>getLanguage()</a></code> methods must
- use the empty string as the track language for all the source tracks
- of the <code><a href=#localmediastream>LocalMediaStream</a></code> object.</p>
+ microphone" or "External USB Webcam"). The <dfn id=dom-streamtrack-label title=dom-StreamTrack-label><code>StreamTrack.label</code></dfn>
+ attribute must return the label of the object's corresponding track,
+ if any. If the corresponding track has or had no label, the
+ attribute must instead return the empty string.</p>
- </div>
+ <p class=note>Thus the <code title=dom-StreamTrack-kind><a href=#dom-streamtrack-kind>kind</a></code> and <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code> attributes do not change
+ value, even if the <code><a href=#streamtrack>StreamTrack</a></code> object is disassociated
+ from its corresponding track.</p>
+ <p>The <dfn id=dom-streamtrack-enabled title=dom-StreamTrack-enabled><code>StreamTrack.enabled</code></dfn>
+ attribute, on getting, must return the last value to which it was
+ set. On setting, it must be set to the new value, and then, if the
+ <code><a href=#streamtrack>StreamTrack</a></code> object is still associated with a track,
+ must enable the track if the new value is true, and disable it
+ otherwise.</p>
+
+ <p class=note>Thus, after a <code><a href=#streamtrack>StreamTrack</a></code> is
+ disassociated from its track, its <code title=dom-StreamTrack-enabled><a href=#dom-streamtrack-enabled>enabled</a></code> attribute still
+ changes value when set, it just doesn't do anything with that new
+ value.</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
@@ -76552,7 +77035,7 @@
- <h3 id=introduction-11><span class=secno>10.1 </span>Introduction</h3>
+ <h3 id=introduction-12><span class=secno>10.1 </span>Introduction</h3>
<h4 id=scope-0><span class=secno>10.1.1 </span>Scope</h4>
@@ -80317,7 +80800,7 @@
</div>
- <h4 id=introduction-12><span class=secno>11.4.1 </span>Introduction</h4>
+ <h4 id=introduction-13><span class=secno>11.4.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -80573,7 +81056,7 @@
<h3 id=channel-messaging><span class=secno>11.5 </span><dfn>Channel messaging</dfn></h3>
- <h4 id=introduction-13><span class=secno>11.5.1 </span>Introduction</h4>
+ <h4 id=introduction-14><span class=secno>11.5.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -80860,9 +81343,9 @@
<p>If any of the objects in <var title="">transfer</var> are
either the <var title="">source port</var> or the <var title="">target port</var> (if any), then throw a
<code><a href=#data_clone_err>DATA_CLONE_ERR</a></code> exception and abort these
- steps.</li>
+ steps.</p>
- </ol></li>
+ </li>
<li>
@@ -80878,8 +81361,10 @@
</li>
- </ol><li>
+ </ol></li>
+ <li>
+
<p>Make <var title="">new ports</var> into a <a href=#dfn-read-only-array title=dfn-read-only-array>read only</a> array.</p>
</li>
@@ -80919,9 +81404,7 @@
<li><p>Add the event to the <a href=#port-message-queue>port message queue</a> of <var title="">target port</var>.</li>
-
-
-<!--
+ </ol><!--
<hr>
<p>The <dfn
@@ -80981,8 +81464,7 @@
title="">target port</var>.</p></li>
</ol>
--->
- <hr><p>The <dfn id=dom-messageport-start title=dom-MessagePort-start><code>start()</code></dfn>
+--><hr><p>The <dfn id=dom-messageport-start title=dom-MessagePort-start><code>start()</code></dfn>
method must enable its port's <a href=#port-message-queue>port message queue</a>, if it
is not already enabled.</p>
@@ -81076,7 +81558,7 @@
- <h3 id=introduction-14><span class=secno>12.1 </span>Introduction</h3>
+ <h3 id=introduction-15><span class=secno>12.1 </span>Introduction</h3>
<p><i>This section is non-normative.</i></p>
@@ -91229,7 +91711,7 @@
"must".</i></p>
- <h3 id=introduction-15><span class=secno>15.1 </span>Introduction</h3>
+ <h3 id=introduction-16><span class=secno>15.1 </span>Introduction</h3>
<p>In general, user agents are expected to support CSS, and many of
the suggestions in this section are expressed in CSS terms. User
@@ -91267,7 +91749,7 @@
<h3 id=the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>15.2 </span>The CSS user agent style sheet and presentational hints</h3>
- <h4 id=introduction-16><span class=secno>15.2.1 </span>Introduction</h4>
+ <h4 id=introduction-17><span class=secno>15.2.1 </span>Introduction</h4>
<p>The CSS rules given in these subsections are, except where
otherwise specified, expected to be used as part of the user-agent
@@ -93409,7 +93891,7 @@
<h3 id=bindings><span class=secno>15.4 </span>Bindings</h3>
- <h4 id=introduction-17><span class=secno>15.4.1 </span>Introduction</h4>
+ <h4 id=introduction-18><span class=secno>15.4.1 </span>Introduction</h4>
<p>A number of elements have their rendering defined in terms of the
'binding' property. <a href=#refsBECSS>[BECSS]</a></p>
Added: images/media-stream-1.png
===================================================================
(Binary files differ)
Property changes on: images/media-stream-1.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Added: images/media-stream-2.png
===================================================================
(Binary files differ)
Property changes on: images/media-stream-2.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Modified: index
===================================================================
--- index 2011-06-24 00:32:39 UTC (rev 6274)
+++ index 2011-06-30 23:52:43 UTC (rev 6275)
@@ -243,7 +243,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 — Last Updated 24 June 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 30 June 2011</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>
@@ -577,7 +577,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>
@@ -1009,7 +1009,10 @@
<ol>
<li><a href=#introduction-10><span class=secno>9.1 </span>Introduction</a></li>
<li><a href=#obtaining-local-multimedia-content><span class=secno>9.2 </span>Obtaining local multimedia content</a></li>
- <li><a href=#stream-api><span class=secno>9.3 </span>Stream API</a></li>
+ <li><a href=#stream-api><span class=secno>9.3 </span>Stream API</a>
+ <ol>
+ <li><a href=#introduction-11><span class=secno>9.3.1 </span>Introduction</a></li>
+ <li><a href=#interface-definitions><span class=secno>9.3.2 </span>Interface definitions</a></ol></li>
<li><a href=#peer-to-peer-connections><span class=secno>9.4 </span>Peer-to-peer connections</a></li>
<li><a href=#the-data-stream><span class=secno>9.5 </span>The data stream</a>
<ol>
@@ -1022,7 +1025,7 @@
<li><a href=#event-definitions-1><span class=secno>10.1 </span>Event definitions</a></li>
<li><a href=#web-messaging><span class=secno>10.2 </span>Cross-document messaging</a>
<ol>
- <li><a href=#introduction-11><span class=secno>10.2.1 </span>Introduction</a></li>
+ <li><a href=#introduction-12><span class=secno>10.2.1 </span>Introduction</a></li>
<li><a href=#security-postmsg><span class=secno>10.2.2 </span>Security</a>
<ol>
<li><a href=#authors><span class=secno>10.2.2.1 </span>Authors</a></li>
@@ -1030,7 +1033,7 @@
<li><a href=#posting-messages><span class=secno>10.2.3 </span>Posting messages</a></ol></li>
<li><a href=#channel-messaging><span class=secno>10.3 </span>Channel messaging</a>
<ol>
- <li><a href=#introduction-12><span class=secno>10.3.1 </span>Introduction</a></li>
+ <li><a href=#introduction-13><span class=secno>10.3.1 </span>Introduction</a></li>
<li><a href=#message-channels><span class=secno>10.3.2 </span>Message channels</a></li>
<li><a href=#message-ports><span class=secno>10.3.3 </span>Message ports</a>
<ol>
@@ -1192,10 +1195,10 @@
<li><a href=#parsing-xhtml-fragments><span class=secno>12.4 </span>Parsing XHTML fragments</a></ol></li>
<li><a href=#rendering><span class=secno>13 </span>Rendering</a>
<ol>
- <li><a href=#introduction-13><span class=secno>13.1 </span>Introduction</a></li>
+ <li><a href=#introduction-14><span class=secno>13.1 </span>Introduction</a></li>
<li><a href=#the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>13.2 </span>The CSS user agent style sheet and presentational hints</a>
<ol>
- <li><a href=#introduction-14><span class=secno>13.2.1 </span>Introduction</a></li>
+ <li><a href=#introduction-15><span class=secno>13.2.1 </span>Introduction</a></li>
<li><a href=#display-types><span class=secno>13.2.2 </span>Display types</a></li>
<li><a href=#margins-and-padding><span class=secno>13.2.3 </span>Margins and padding</a></li>
<li><a href=#alignment><span class=secno>13.2.4 </span>Alignment</a></li>
@@ -1221,7 +1224,7 @@
<li><a href=#toolbars-0><span class=secno>13.3.6 </span>Toolbars</a></ol></li>
<li><a href=#bindings><span class=secno>13.4 </span>Bindings</a>
<ol>
- <li><a href=#introduction-15><span class=secno>13.4.1 </span>Introduction</a></li>
+ <li><a href=#introduction-16><span class=secno>13.4.1 </span>Introduction</a></li>
<li><a href=#the-button-element-0><span class=secno>13.4.2 </span>The <code>button</code> element</a></li>
<li><a href=#the-details-element-0><span class=secno>13.4.3 </span>The <code>details</code> element</a></li>
<li><a href=#the-input-element-as-a-text-entry-widget><span class=secno>13.4.4 </span>The <code>input</code> element as a text entry widget</a></li>
@@ -3487,9 +3490,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
@@ -26792,9 +26795,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>
@@ -29351,9 +29354,7 @@
</div>
-<!--PEERCONNECTION-->
<h5 id=media-resources-with-multiple-media-tracks><span class=secno>4.8.10.10 </span>Media resources with multiple media tracks</h5>
-<!--PEERCONNECTION-->
<p>A <a href=#media-resource>media resource</a> can have multiple embedded audio
and video tracks. For example, in addition to the primary video and
@@ -29365,7 +29366,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>
@@ -29374,7 +29375,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>
@@ -29383,23 +29384,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>
@@ -29424,9 +29426,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; <!-- should escape this probably -->
sign.autoplay = true;
sign.controller = controller;
container.appendChild(sign);
@@ -29440,42 +29442,45 @@
</div>
-<!--PEERCONNECTION-->
- <h6 id=tracklist-objects><span class=secno>4.8.10.10.1 </span><code><a href=#tracklist>TrackList</a></code> objects</h6>
+ <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>
- <!-- should probably move this section out since it is also used by
- the video conferencing stuff -->
+ <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.</p>
-<!--PEERCONNECTION-->
- <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>
-<!--PEERCONNECTION-->
+ <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>;
+};
- <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);
+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=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=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=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);
+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="">tracks</var> . <code title=dom-TrackList-length><a href=#dom-tracklist-length>length</a></code></dt>
+ <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>
@@ -29483,65 +29488,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>
@@ -29549,42 +29563,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
@@ -29595,110 +29673,110 @@
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>
+ <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><!-- added because of the volume of use cases, but we should remove it if none of the formats start supporting it --><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>
+ interpretation), then the method must return the empty string, as if
+ the track had no language.</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-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>
- <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>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-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-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-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>
+ <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 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>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>An <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object represents a track list
- where exactly one track is selected at a time.</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-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>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>
-
<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>
@@ -29737,7 +29815,6 @@
selection -->
</div>
-<!--PEERCONNECTION-->
<h5 id=synchronising-multiple-media-elements><span class=secno>4.8.10.11 </span>Synchronising multiple media elements</h5>
@@ -31365,7 +31442,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>
@@ -31400,8 +31477,10 @@
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>
+<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>
@@ -31777,15 +31856,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>
@@ -74791,14 +74870,14 @@
stream.</p>
<p>If <var title="">audio</var> is true, then the provided media
- should include an audio component. If <var title="">audio</var>
+ should include an audio track. If <var title="">audio</var>
is false, then the provided media must not include an audio
- component.</p>
+ track.</p>
<p>If <var title="">video</var> is true, then the provided media
- should include a video component. If <var title="">video</var> is
+ should include a video track. If <var title="">video</var> is
false, then the provided media must not include a video
- component.</p>
+ track.</p>
<p>User agents are encouraged to default to using the user's
primary or system default camera and/or microphone (as
@@ -74885,6 +74964,8 @@
<h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
+ <h4 id=introduction-11><span class=secno>9.3.1 </span>Introduction</h4>
+
<p>The <code><a href=#mediastream>MediaStream</a></code> interface is used to represent
streams of media data, typically (but not necessarily) of audio
and/or video content, e.g. from a local camera or a remote site. The
@@ -74894,7 +74975,318 @@
user agents to manipulate media streams in whatever fashion is most
suitable on the user's platform.</p>
- <p>The <code><a href=#localmediastream>LocalMediaStream</a></code> interface is used when the user
+ <p>Each <code><a href=#mediastream>MediaStream</a></code> object can represent zero or more
+ tracks, in particular audio and video tracks. Tracks can contain
+ multiple channels of parallel data; for example a single audio track
+ could have nine channels of audio data to represent a 7.2 surround
+ sound audio track.</p>
+
+ <p>Each track represented by a <code><a href=#mediastream>MediaStream</a></code> object has a
+ corresponding <code><a href=#streamtrack>StreamTrack</a></code> object.</p>
+
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object has an input and an output. The
+ input depends on how the object was created: a
+ <code><a href=#localmediastream>LocalMediaStream</a></code> object generated by a <code title=dom-navigator-getUserMedia><a href=#dom-navigator-getusermedia>getUserMedia()</a></code> call, for
+ instance, might take its input from the user's local camera, while a
+ <code><a href=#mediastream>MediaStream</a></code> created by a <code><a href=#peerconnection>PeerConnection</a></code>
+ object will take as input the data received from a remote peer. The
+ output of the object controls how the object is used, e.g. what is
+ saved if the object is written to a file, what is displayed if the
+ object is used in a <code><a href=#the-video-element>video</a></code> element, or indeed what is
+ transmitted to a remote peer if the object is used with a
+ <code><a href=#peerconnection>PeerConnection</a></code> object.</p>
+
+ <p>Each track in a <code><a href=#mediastream>MediaStream</a></code> object can be disabled,
+ meaning that it does not appear in the object's output. All tracks
+ are initially enabled.</p>
+
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object's output can be "forked" by
+ creating a new <code><a href=#mediastream>MediaStream</a></code> object from it using the
+ <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream()</a></code> constructor. The
+ new <code><a href=#mediastream>MediaStream</a></code> object's input is the output of the
+ object from which it was created, and its output is therefore at
+ most a subset of the "parent" object.</p>
+
+ <p><img alt="" src=http://images.whatwg.org/media-stream-1.png></p><!-- no alt since
+ it's all described in the previous paragraphs: this is just a
+ summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ stroke();
+ }
+ mediaStream(c,50,10, true);
+
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText('MediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>This can be used, for instance, in a video-conferencing scenario
+ to display the local video from the user's camera and microphone in
+ a local monitor, while only transmitting the audio to the remote
+ peer (e.g. in response to the user using a "video mute"
+ feature).</p>
+
+ <p><img alt="" src=http://images.whatwg.org/media-stream-2.png></p><!-- again, no
+ alt since it's all described in the previous paragraphs: this is
+ just a summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ lineTo(550, 210);
+ lineTo(50, 210);
+ lineTo(50, 320);
+ lineTo(550, 320);
+ lineTo(550,420);
+ stroke();
+ beginPath();
+ moveTo(50,320);
+ lineTo(50,420);
+ stroke();
+ restore();
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ fillText('<video>', 50, 440);
+ fillText('PeerConnection', 550, 440);
+ font = '100 8px "Press Start 2P", sans-serif';
+ }
+ cameraIcon(c,25,98)
+ mediaStream(c,50,10, true);
+ mediaStream(c,50,233, false);
+
+ with (c) {
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'middle';
+ fillStyle = 'gray';
+
+ fillText('from', 4, 130);
+ fillText('getUserMedia()', 4, 140);
+
+ fillText('via URL.getObjectURL()', 4, 450);
+
+ textAlign = 'center';
+ fillText('via addStream()', 550, 450);
+ }
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText(!vid ? 'MediaStream' : 'LocalMediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>If a track in a <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is disabled, it does not have a corresponding
+ track in any <code><a href=#mediastream>MediaStream</a></code> objects that were created from
+ <var title="">parent</var>. When a track in a
+ <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is disabled, any
+ <code><a href=#streamtrack>StreamTrack</a></code> objects corresponding to the tracks in any
+ <code><a href=#mediastream>MediaStream</a></code> objects that were created from <var title="">parent</var> are disassociated from any track, and must not
+ be reused for tracks again. If a disabled track in a
+ <code><a href=#mediastream>MediaStream</a></code> <var title="">parent</var> is re-enabled,
+ from the perspective of any <code><a href=#mediastream>MediaStream</a></code> objects that
+ were created from <var title="">parent</var> it is a new track and
+ thus new <code><a href=#streamtrack>StreamTrack</a></code> objects must be created for the
+ tracks that correspond to the re-enabled track.</p>
+
+ <hr><p>The <code><a href=#localmediastream>LocalMediaStream</a></code> interface is used when the user
agent is generating the stream's data (e.g. from a camera or
streaming it from a local video file). It allows authors to control
individual tracks during the generation of the content, e.g. to
@@ -74908,14 +75300,20 @@
live video from pre-recorded video, which can help protect the
user's privacy.</p>
+
+ <h4 id=interface-definitions><span class=secno>9.3.2 </span>Interface definitions</h4>
+
<!-- v2: support reading the bits from the stream directly, for use
with streaming over WebSocket? Or do we rely on FileReader for that?
sicking suggests defining a DataStream or BlobStream interface that
you can get from a Stream to get to the underlying data; such an
object would then be readable using the File API -->
- <pre class=idl>interface <dfn id=mediastream>MediaStream</dfn> {
+ <pre class=idl>[<a href=#dom-mediastream title=dom-MediaStream>Constructor</a>(in <a href=#mediastream>MediaStream</a> parentStream)]
+interface <dfn id=mediastream>MediaStream</dfn> {
readonly attribute DOMString <a href=#dom-mediastream-label title=dom-MediaStream-label>label</a>;
+ readonly attribute <a href=#streamtracklist>StreamTrackList</a> <a href=#dom-mediastream-tracks title=dom-MediaStream-tracks>tracks</a>;
+
<a href=#mediastreamrecorder>MediaStreamRecorder</a> <a href=#dom-mediastream-record title=dom-MediaStream-record>record</a>();
<!--
const unsigned short <span title="dom-MediaStream-LOADING">LOADING</span> = 0; -->
@@ -74928,16 +75326,29 @@
interface <dfn id=localmediastream>LocalMediaStream</dfn> : <a href=#mediastream>MediaStream</a> {
void <a href=#dom-mediastream-stop title=dom-MediaStream-stop>stop</a>();
+};
- // track control
- readonly attribute <a href=#multipletracklist>MultipleTrackList</a> <a href=#dom-mediastream-audiotracks title=dom-MediaStream-audioTracks>audioTracks</a>;
- readonly attribute <a href=#exclusivetracklist>ExclusiveTrackList</a> <a href=#dom-mediastream-videotracks title=dom-MediaStream-videoTracks>videoTracks</a>;
+typedef <a href=#streamtrack>StreamTrack</a>[] <dfn id=streamtracklist>StreamTrackList</dfn>;
+
+interface <dfn id=streamtrack>StreamTrack</dfn> {
+ readonly attribute DOMString <a href=#dom-streamtrack-kind title=dom-StreamTrack-kind>kind</a>;
+ readonly attribute DOMString <a href=#dom-streamtrack-label title=dom-StreamTrack-label>label</a>;
+ attribute boolean <a href=#dom-streamtrack-enabled title=dom-StreamTrack-enabled>enabled</a>;
};</pre>
- <dl class=domintro><dt><var title="">stream</var> . <code title=dom-MediaStream-label><a href=#dom-mediastream-label>label</a></code></dt>
+ <dl class=domintro><dt><var title="">stream</var> = new <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream</a></code>( <var title="">parentStream</var> )</dt>
<dd>
+ <p>Creates a new <code><a href=#mediastream>MediaStream</a></code> object whose tracks are the enabled tracks of <var title="">parentStream</var>.</p>
+
+ </dd>
+
+
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-label><a href=#dom-mediastream-label>label</a></code></dt>
+
+ <dd>
+
<p>Returns a label that is unique to this stream, so that streams
can be recognised after they are sent through the
<code><a href=#peerconnection>PeerConnection</a></code> API.</p>
@@ -74965,29 +75376,71 @@
</dd>
- <dt><var title="">stream</var> . <code title=dom-MediaStream-audioTracks><a href=#dom-mediastream-audiotracks>audioTracks</a></code></dt>
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code></dt>
<dd>
- <p>Returns a <code><a href=#multipletracklist>MultipleTrackList</a></code> object representing
- the audio tracks available for mixing into the
- <code><a href=#localmediastream>LocalMediaStream</a></code>'s stream.</p>
+ <p>Returns a <code><a href=#streamtracklist>StreamTrackList</a></code> object representing
+ the tracks that can be enabled and disabled.</p>
</dd>
- <dt><var title="">stream</var> . <code title=dom-MediaStream-videoTracks><a href=#dom-mediastream-videotracks>videoTracks</a></code></dt>
+ <dt><var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code> . <code title=dom-StreamTrackList-length>length</code></dt>
+
<dd>
- <p>Returns an <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object representing
- the video tracks available for the <code><a href=#localmediastream>LocalMediaStream</a></code>'s
- stream.</p>
+ <p>Returns the number of tracks in the list.</p>
</dd>
+ <dt><var title="">track</var> = <var title="">stream</var> . <code title=dom-MediaStream-tracks><a href=#dom-mediastream-tracks>tracks</a></code>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the specified <code><a href=#streamtrack>StreamTrack</a></code> object.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code></dt>
+
+ <dd>
+
+ <p>Returns the string "<code title="">audio</code>" if the track
+ is an audio track, and the string "<code title="">video</code>" if
+ it is a video track.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code></dt>
+
+ <dd>
+
+ <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title=dom-StreamTrack-enabled><a href=#dom-streamtrack-enabled>enabled</a></code> [ = <var title="">value</var> ]</dt>
+
+ <dd>
+
+ <p>Returns true if the given track is active in the <code><a href=#mediastream>MediaStream</a></code>'s output, and false otherwise.</p>
+
+ <p>Can be set, to change whether the track is enabled or not.</p>
+
+ </dd>
+
</dl><div class=impl>
+ <p>The <dfn id=dom-mediastream title=dom-MediaStream><code>MediaStream(<var title="">parentStream</var>)</code></dfn> constructor must return a
+ new <code><a href=#mediastream>MediaStream</a></code> object whose tracks at any moment in
+ time are the enabled tracks of <var title="">parentStream</var> at
+ that moment.</p>
+
<p>The <dfn id=dom-mediastream-readystate title=dom-MediaStream-readyState><code>readyState</code></dfn>
attribute represents the state of the stream. It must return the
value to which the user agent last set it (as defined below). It can
@@ -75004,18 +75457,32 @@
or generating data, and will never receive or generate more data
for this stream).</dd>
- </dl><p>When a <code><a href=#mediastream>MediaStream</a></code> object is created, its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute must be
- set to <code title=dom-MediaStream-LIVE><a href=#dom-mediastream-live>LIVE</a></code> (1).</p>
+ </dl><p>When a <code><a href=#mediastream>MediaStream</a></code> object is created, its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute must
+ be set to <code title=dom-MediaStream-LIVE><a href=#dom-mediastream-live>LIVE</a></code> (1), unless
+ it is being created using the <code title=dom-MediaStream><a href=#dom-mediastream>MediaStream()</a></code> constructor whose
+ argument is a <code><a href=#mediastream>MediaStream</a></code> object whose <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute has
+ the value <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2), in
+ which case the <code><a href=#mediastream>MediaStream</a></code> object must be created with
+ its <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code>
+ attribute set to <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code>
+ (2).</p>
- <p>When a <code><a href=#mediastream>MediaStream</a></code> object ends for any reason other than
- the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method being invoked
- (e.g. because the user rescinds the permission for the page to use
- the local camera, or because the data comes from a finite file and
- the file's end has been reached and the user has not requested that
- it be looped, or because the stream comes from a remote peer and the
- remote peer has permanently stopped sending data), the user agent
- must <a href=#queue-a-task>queue a task</a> that runs the following steps:</p>
+ <p>A <code><a href=#mediastream>MediaStream</a></code> object is said to <i>end</i> when the
+ user agent learns that no more data will ever be forthcoming for
+ this stream.</p>
+ <p>When a <code><a href=#mediastream>MediaStream</a></code> object ends for any reason other
+ than the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method
+ being invoked (e.g. because the user rescinds the permission for the
+ page to use the local camera, or because the data comes from a
+ finite file and the file's end has been reached and the user has not
+ requested that it be looped, or because the stream comes from a
+ remote peer and the remote peer has permanently stopped sending
+ data, or because the <code><a href=#mediastream>MediaStream</a></code> was created from
+ another <code><a href=#mediastream>MediaStream</a></code> and that stream has just itself
+ ended), the user agent must <a href=#queue-a-task>queue a task</a> that runs the
+ following steps:</p>
+
<ol><li><p>If the object's <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute has the
value <code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2) already, then
abort these steps. (The <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code>
@@ -75069,7 +75536,7 @@
source, then the user agent should remove any active "on-air"
indicator. If the data is being generated from a prerecorded source
(e.g. a video file), any remaining content in the file is
- ignored.</li>
+ ignored. The stream has <i>ended</i>.</li>
<li><p>Set the object's <code title=dom-MediaStream-readyState><a href=#dom-mediastream-readystate>readyState</a></code> attribute to
<code title=dom-MediaStream-ENDED><a href=#dom-mediastream-ended>ENDED</a></code> (2).</li>
@@ -75079,44 +75546,60 @@
</ol><p>The <a href=#task-source>task source</a> for the <a href=#concept-task title=concept-task>tasks</a> queued for the <code title=dom-MediaStream-stop><a href=#dom-mediastream-stop>stop()</a></code> method is the <a href=#dom-manipulation-task-source>DOM
manipulation task source</a>.</p>
- <hr><p>A <code><a href=#localmediastream>LocalMediaStream</a></code> can have multiple audio and video
+ <hr><p>A <code><a href=#mediastream>MediaStream</a></code> can have multiple audio and video
sources (e.g. because the user has multiple microphones, or because
the real source of the stream is a <a href=#media-resource>media resource</a> with
many media tracks). The stream represented by a
- <code><a href=#localmediastream>LocalMediaStream</a></code> has either zero or one audio track and
- either zero or one video track.</p>
+ <code><a href=#mediastream>MediaStream</a></code> thus has zero or more tracks.</p>
- <div class=impl>
+ <hr><p>The <dfn id=dom-mediastream-tracks title=dom-MediaStream-tracks><code>tracks</code></dfn>
+ attribute must return an <a href=#array-host-objects title="array host objects">array host
+ object</a> for objects of type <code><a href=#streamtrack>StreamTrack</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>
- <p>The <dfn id=dom-mediastream-audiotracks title=dom-MediaStream-audioTracks><code>audioTracks</code></dfn>
- attribute of a <code><a href=#localmediastream>LocalMediaStream</a></code> object must return a
- <a href=#live>live</a> <code><a href=#multipletracklist>MultipleTrackList</a></code> object representing
- the audio sources available to the <code><a href=#localmediastream>LocalMediaStream</a></code>. The
- same object must be returned each time. The
- <code><a href=#localmediastream>LocalMediaStream</a></code>'s output audio track must be the result
- of mixing all the enabled audio sources, if any.</p>
+ <p>The array must contain the <code><a href=#streamtrack>StreamTrack</a></code> objects that
+ correspond to the the tracks of the stream. The relative order of
+ all tracks in a user agent must be stable. All audio tracks must
+ precede all video tracks. Tracks that come from a <a href=#media-resource>media
+ resource</a> whose format defines an order must be in the order
+ defined by the format; tracks that come from a <a href=#media-resource>media
+ resource</a> whose format does not define an order must be in the
+ relative order in which the tracks are declared in that <a href=#media-resource>media
+ resource</a>. Within these constraints, the order is user-agent
+ defined.</p> <!-- doesn't matter currently since I can't think of
+ any way that you can get multiple tracks together. It would matter
+ if we allowed a MediaStream() constructor that took an array of
+ streams, though, or if getUserMedia() could return multiple audio or
+ video tracks. -->
- <p>The <dfn id=dom-mediastream-videotracks title=dom-MediaStream-videoTracks><code>videoTracks</code></dfn>
- attribute of a <code><a href=#localmediastream>LocalMediaStream</a></code> object must return a
- <a href=#live>live</a> <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object
- representing the video sources available to the
- <code><a href=#localmediastream>LocalMediaStream</a></code>. The same object must be returned each
- time. The <code><a href=#localmediastream>LocalMediaStream</a></code>'s output video track must be
- the selected video source, if any.</p>
+ <p>The <dfn id=dom-streamtrack-kind title=dom-StreamTrack-kind><code>StreamTrack.kind</code></dfn>
+ attribute must return the string "<code title="">audio</code>" if
+ the object's corresponding track is or was an audio track, "<code title="">video</code>" if the corresponding track is or was a video
+ track, and a user-agent defined string otherwise.</p>
<p>User agents may label audio and video sources (e.g. "Internal
- microphone" or "External USB Webcam"), in which case the <code title=dom-TrackList-getLabel><a href=#dom-tracklist-getlabel>getLabel()</a></code> methods (on the
- <code><a href=#multipletracklist>MultipleTrackList</a></code> and <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code>
- objects) must use the labels the user agent has assigned as the
- track labels of the source tracks of the <code><a href=#localmediastream>LocalMediaStream</a></code>
- object. Otherwise, the <code title=dom-TrackList-getLabel><a href=#dom-tracklist-getlabel>getLabel()</a></code> methods must use the
- empty string as the track labels of the source tracks of the
- <code><a href=#localmediastream>LocalMediaStream</a></code> object. The <code title=dom-TrackList-getLanguage><a href=#dom-tracklist-getlanguage>getLanguage()</a></code> methods must
- use the empty string as the track language for all the source tracks
- of the <code><a href=#localmediastream>LocalMediaStream</a></code> object.</p>
+ microphone" or "External USB Webcam"). The <dfn id=dom-streamtrack-label title=dom-StreamTrack-label><code>StreamTrack.label</code></dfn>
+ attribute must return the label of the object's corresponding track,
+ if any. If the corresponding track has or had no label, the
+ attribute must instead return the empty string.</p>
- </div>
+ <p class=note>Thus the <code title=dom-StreamTrack-kind><a href=#dom-streamtrack-kind>kind</a></code> and <code title=dom-StreamTrack-label><a href=#dom-streamtrack-label>label</a></code> attributes do not change
+ value, even if the <code><a href=#streamtrack>StreamTrack</a></code> object is disassociated
+ from its corresponding track.</p>
+ <p>The <dfn id=dom-streamtrack-enabled title=dom-StreamTrack-enabled><code>StreamTrack.enabled</code></dfn>
+ attribute, on getting, must return the last value to which it was
+ set. On setting, it must be set to the new value, and then, if the
+ <code><a href=#streamtrack>StreamTrack</a></code> object is still associated with a track,
+ must enable the track if the new value is true, and disable it
+ otherwise.</p>
+
+ <p class=note>Thus, after a <code><a href=#streamtrack>StreamTrack</a></code> is
+ disassociated from its track, its <code title=dom-StreamTrack-enabled><a href=#dom-streamtrack-enabled>enabled</a></code> attribute still
+ changes value when set, it just doesn't do anything with that new
+ value.</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
@@ -76585,7 +77068,7 @@
</div>
- <h4 id=introduction-11><span class=secno>10.2.1 </span>Introduction</h4>
+ <h4 id=introduction-12><span class=secno>10.2.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -76841,7 +77324,7 @@
<h3 id=channel-messaging><span class=secno>10.3 </span><dfn>Channel messaging</dfn></h3>
- <h4 id=introduction-12><span class=secno>10.3.1 </span>Introduction</h4>
+ <h4 id=introduction-13><span class=secno>10.3.1 </span>Introduction</h4>
<p><i>This section is non-normative.</i></p>
@@ -77128,9 +77611,9 @@
<p>If any of the objects in <var title="">transfer</var> are
either the <var title="">source port</var> or the <var title="">target port</var> (if any), then throw a
<code><a href=#data_clone_err>DATA_CLONE_ERR</a></code> exception and abort these
- steps.</li>
+ steps.</p>
- </ol></li>
+ </li>
<li>
@@ -77146,8 +77629,10 @@
</li>
- </ol><li>
+ </ol></li>
+ <li>
+
<p>Make <var title="">new ports</var> into a <a href=#dfn-read-only-array title=dfn-read-only-array>read only</a> array.</p>
</li>
@@ -77187,9 +77672,7 @@
<li><p>Add the event to the <a href=#port-message-queue>port message queue</a> of <var title="">target port</var>.</li>
-
-
-<!--
+ </ol><!--
<hr>
<p>The <dfn
@@ -77249,8 +77732,7 @@
title="">target port</var>.</p></li>
</ol>
--->
- <hr><p>The <dfn id=dom-messageport-start title=dom-MessagePort-start><code>start()</code></dfn>
+--><hr><p>The <dfn id=dom-messageport-start title=dom-MessagePort-start><code>start()</code></dfn>
method must enable its port's <a href=#port-message-queue>port message queue</a>, if it
is not already enabled.</p>
@@ -86800,7 +87282,7 @@
"must".</i></p>
- <h3 id=introduction-13><span class=secno>13.1 </span>Introduction</h3>
+ <h3 id=introduction-14><span class=secno>13.1 </span>Introduction</h3>
<p>In general, user agents are expected to support CSS, and many of
the suggestions in this section are expressed in CSS terms. User
@@ -86838,7 +87320,7 @@
<h3 id=the-css-user-agent-style-sheet-and-presentational-hints><span class=secno>13.2 </span>The CSS user agent style sheet and presentational hints</h3>
- <h4 id=introduction-14><span class=secno>13.2.1 </span>Introduction</h4>
+ <h4 id=introduction-15><span class=secno>13.2.1 </span>Introduction</h4>
<p>The CSS rules given in these subsections are, except where
otherwise specified, expected to be used as part of the user-agent
@@ -88980,7 +89462,7 @@
<h3 id=bindings><span class=secno>13.4 </span>Bindings</h3>
- <h4 id=introduction-15><span class=secno>13.4.1 </span>Introduction</h4>
+ <h4 id=introduction-16><span class=secno>13.4.1 </span>Introduction</h4>
<p>A number of elements have their rendering defined in terms of the
'binding' property. <a href=#refsBECSS>[BECSS]</a></p>
Modified: source
===================================================================
--- source 2011-06-24 00:32:39 UTC (rev 6274)
+++ source 2011-06-30 23:52:43 UTC (rev 6275)
@@ -2498,9 +2498,10 @@
specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
<p>The terms <dfn>supported property indices</dfn>, <dfn>supported
- property names</dfn>, and <dfn 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>determine the value of an indexed
+ property</dfn>, <dfn>array host objects</dfn>, and <dfn
+ 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
@@ -29068,9 +29069,9 @@
attribute boolean <span title="dom-media-defaultMuted">defaultMuted</span>;
// tracks
- readonly attribute <span>MultipleTrackList</span> <span title="dom-media-audioTracks">audioTracks</span>;
- readonly attribute <span>ExclusiveTrackList</span> <span title="dom-media-videoTracks">videoTracks</span>;
- readonly attribute <span>TextTrack</span>[] <span title="dom-media-textTracks">textTracks</span>;
+ readonly attribute <span>AudioTrackList</span> <span title="dom-media-audioTracks">audioTracks</span>;
+ readonly attribute <span>VideoTrackList</span> <span title="dom-media-videoTracks">videoTracks</span>;
+ readonly attribute <span>TextTrackList</span> <span title="dom-media-textTracks">textTracks</span>;
<span>MutableTextTrack</span> <span title="dom-media-addTextTrack">addTextTrack</span>(in DOMString kind, in optional DOMString label, in optional DOMString language);
};</pre>
@@ -32124,9 +32125,7 @@
</div>
-<!--START rtc--><!--PEERCONNECTION-->
<h5>Media resources with multiple media tracks</h5>
-<!--END rtc--><!--PEERCONNECTION-->
<p>A <span>media resource</span> can have multiple embedded audio
and video tracks. For example, in addition to the primary video and
@@ -32140,7 +32139,7 @@
<dd>
- <p>Returns a <code>MultipleTrackList</code> object representing
+ <p>Returns an <code>AudioTrackList</code> object representing
the audio tracks available in the <span>media resource</span>.</p>
</dd>
@@ -32149,7 +32148,7 @@
<dd>
- <p>Returns an <code>ExclusiveTrackList</code> object representing
+ <p>Returns an <code>VideoTrackList</code> object representing
the video tracks available in the <span>media resource</span>.</p>
</dd>
@@ -32161,7 +32160,7 @@
<p>The <dfn
title="dom-media-audioTracks"><code>audioTracks</code></dfn>
attribute of a <span>media element</span> must return a
- <span>live</span> <code>MultipleTrackList</code> object representing
+ <span>live</span> <code>AudioTrackList</code> object representing
the audio tracks available in the <span>media element</span>'s
<span>media resource</span>. The same object must be returned each
time.</p>
@@ -32169,16 +32168,17 @@
<p>The <dfn
title="dom-media-videoTracks"><code>videoTracks</code></dfn>
attribute of a <span>media element</span> must return a
- <span>live</span> <code>ExclusiveTrackList</code> object
+ <span>live</span> <code>VideoTrackList</code> object
representing the video tracks available in the <span>media
element</span>'s <span>media resource</span>. The same object must
be returned each time.</p>
- <p class="note">There are only ever two <code>TrackList</code>
- objects (one <code>MultipleTrackList</code> object and one
- <code>ExclusiveTrackList</code> object) per <span>media
+ <p class="note">There are only ever one <code>AudioTrackList</code>
+ object and one <code>VideoTrackList</code> object per <span>media
element</span>, even if another <span>media resource</span> is
- loaded into the element: the objects are reused.</p>
+ loaded into the element: the objects are reused. (The
+ <code>AudioTrack</code> and <code>VideoTrack</code> objects are
+ not, though.)</p>
</div>
@@ -32203,9 +32203,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; <!-- should escape this probably -->
sign.autoplay = true;
sign.controller = controller;
container.appendChild(sign);
@@ -32219,44 +32219,47 @@
</div>
-<!--START rtc--><!--PEERCONNECTION-->
- <h6><code>TrackList</code> objects</h6>
+ <h6><code>AudioTrackList</code> and <code>VideoTrackList</code> objects</h6>
- <!-- should probably move this section out since it is also used by
- the video conferencing stuff -->
+ <p>The <code>AudioTrackList</code> and <code>VideoTrackList</code>
+ interfaces are used by attributes defined in the previous
+ section.</p>
-<!--END rtc--><!--PEERCONNECTION-->
- <p>The <code>MultipleTrackList</code> and
- <code>ExclusiveTrackList</code> interfaces, used by the attributes
- defined in the previous section, are substantially similar. Their
- common features are defined in the <code>TrackList</code> interface,
- from which they both inherit.</p>
-<!--START rtc--><!--PEERCONNECTION-->
+ <pre class="idl">interface <dfn>AudioTrackList</dfn> {
+ readonly attribute unsigned long <span title="dom-AudioTrackList-length">length</span>;
+ getter <span>AudioTrack</span> (in unsigned long index);
+ <span>AudioTrack</span>? <span title="dom-AudioTrackList-getTrackById">getTrackById</span>(in DOMString id);
+ attribute <span>Function</span>? <span title="handler-TrackList-onchange">onchange</span>;
+};
- <pre class="idl">interface <dfn>TrackList</dfn> {
- readonly attribute unsigned long <span title="dom-TrackList-length">length</span>;
- DOMString <span title="dom-TrackList-getID">getID</span>(in unsigned long index);
- DOMString <span title="dom-TrackList-getKind">getKind</span>(in unsigned long index);
- DOMString <span title="dom-TrackList-getLabel">getLabel</span>(in unsigned long index);
- DOMString <span title="dom-TrackList-getLanguage">getLanguage</span>(in unsigned long index);
+interface <dfn>AudioTrack</dfn> {
+ readonly attribute DOMString <span title="dom-AudioTrack-id">id</span>;
+ readonly attribute DOMString <span title="dom-AudioTrack-kind">kind</span>;
+ readonly attribute DOMString <span title="dom-AudioTrack-label">label</span>;
+ readonly attribute DOMString <span title="dom-AudioTrack-language">language</span>;
+ attribute boolean <span title="dom-AudioTrack-enabled">enabled</span>;
+};
+interface <dfn>VideoTrackList</dfn> {
+ readonly attribute unsigned long <span title="dom-VideoTrackList-length">length</span>;
+ getter <span>VideoTrack</span> (in unsigned long index);
+ <span>VideoTrack</span>? <span title="dom-VideoTrackList-getTrackById">getTrackById</span>(in DOMString id);
+ readonly attribute long <span title="dom-VideoTrackList-selectedIndex">selectedIndex</span>;
attribute <span>Function</span>? <span title="handler-TrackList-onchange">onchange</span>;
};
-interface <dfn>MultipleTrackList</dfn> : <span>TrackList</span> {
- boolean <span title="dom-TrackList-isEnabled">isEnabled</span>(in unsigned long index);
- void <span title="dom-TrackList-enable">enable</span>(in unsigned long index);
- void <span title="dom-TrackList-disable">disable</span>(in unsigned long index);
-};
-
-interface <dfn>ExclusiveTrackList</dfn> : <span>TrackList</span> {
- readonly attribute long <span title="dom-TrackList-selectedIndex">selectedIndex</span>;
- void <span title="dom-TrackList-select">select</span>(in unsigned long index);
+interface <dfn>VideoTrack</dfn> {
+ readonly attribute DOMString <span title="dom-VideoTrack-id">id</span>;
+ readonly attribute DOMString <span title="dom-VideoTrack-kind">kind</span>;
+ readonly attribute DOMString <span title="dom-VideoTrack-label">label</span>;
+ readonly attribute DOMString <span title="dom-VideoTrack-language">language</span>;
+ attribute boolean <span title="dom-VideoTrack-selected">selected</span>;
};</pre>
<dl class="domintro">
- <dt><var title="">tracks</var> . <code title="dom-TrackList-length">length</code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-audioTracks">audioTracks</code> . <code title="dom-AudioTrackList-length">length</code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-videoTracks">videoTracks</code> . <code title="dom-VideoTrackList-length">length</code></dt>
<dd>
@@ -32264,66 +32267,75 @@
</dd>
- <dt><var title="">id</var> = <var title="">tracks</var> . <code title="dom-TrackList-getID">getID</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks">audioTracks</code>[<var title="">index</var>]</dt>
+ <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks">videoTracks</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>AudioTrack</code> or <code>VideoTrack</code> object.</p>
</dd>
- <dt><var title="">kind</var> = <var title="">tracks</var> . <code title="dom-TrackList-getKind">getKind</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks">audioTracks</code> . <code title="dom-AudioTrackList-getTrackById">getTrackById</code>( <var title="">id</var> )</dt>
+ <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks">videoTracks</code> . <code title="dom-VideoTrackList-getTrackById">getTrackById</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>AudioTrack</code> or <code>VideoTrack</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">getLabel</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-id">id</code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-id">id</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">getLanguage</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-kind">kind</code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-kind">kind</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">isEnabled</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-label">label</code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-label">label</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">enable</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-language">language</code></dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-language">language</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">disable</code>( <var title="">index</var> )</dt>
+ <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-enabled">enabled</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">selectedIndex</code></dt>
+ <dt><var title="">media</var> . <code title="dom-media-videoTracks">videoTracks</code> . <code title="dom-VideoTrackList-selectedIndex">selectedIndex</code></dt>
<dd>
@@ -32331,46 +32343,120 @@
</dd>
- <dt><var title="">videoTracks</var> . <code title="dom-TrackList-select">select</code>( <var title="">index</var> )</dt>
+ <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-selected">selected</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 title="dom-TrackList-length"><code>length</code></dfn>
- attribute must return the number of tracks represented by the
- <code>TrackList</code> object at the time of getting.</p>
+ <p>An <code>AudioTrackList</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>AudioTrack</code> object.</p>
- <p>Tracks in a <code>TrackList</code> object must be consistently
- ordered. If the <span>media resource</span> 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
- <span>media resource</span>. 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.</p>
+ <p>A <code>VideoTrackList</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>VideoTrack</code>
+ object.</p>
- <p>The <dfn 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>INDEX_SIZE_ERR</code> exception. If the <span>media
- resource</span> 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>AudioTrackList</code> and
+ <code>VideoTrackList</code> objects must be consistently ordered. If
+ the <span>media resource</span> 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
+ <span>media resource</span>. 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 <span>media
+ resource</span> dynamically adds or removes audio or video tracks,
+ then the indices of the tracks will change dynamically. If the
+ <span>media resource</span> changes entirely, then all the previous
+ tracks will be removed and replaced with new tracks.</p>
+
+ <p>The <dfn
+ title="dom-AudioTrackList-length"><code>AudioTrackList.length</code></dfn>
+ and <dfn
+ 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 <span>supported property indices</span> of
+ <code>AudioTrackList</code> and <code>VideoTrackList</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>AudioTrackList</code> or
+ <code>VideoTrackList</code> object represents no tracks, it has no
+ <span>supported property indices</span>.</p>
+
+ <p>To <span>determine the value of an indexed property</span> for a
+ given index <var title="">index</var> in an
+ <code>AudioTrackList</code> or <code>VideoTrackList</code> object
+ <var title="">list</var>, the user agent must return the
+ <code>AudioTrack</code> or <code>VideoTrack</code> object that
+ represents the <var title="">index</var>th track in <var
+ title="">list</var>.</p>
+
+ <p>The <dfn
+ title="dom-AudioTrackList-getTrackById"><code>AudioTrackList.getTrackById(<var
+ title="">id</var>)</code></dfn> and <dfn
+ title="dom-VideoTrackList-getTrackById"><code>VideoTrackList.getTrackById(<var
+ title="">id</var>)</code></dfn> methods must return the first
+ <code>AudioTrack</code> or <code>VideoTrack</code> object
+ (respectively) in the <code>AudioTrack</code> or
+ <code>VideoTrack</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>AudioTrack</code> and <code>VideoTrack</code> objects
+ represent specific tracks of a <span>media resource</span>. 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 <span>media resource</span>'s
+ <code>AudioTrackList</code> or <code>VideoTrackList</code> objects,
+ those aspects do not change.</p>
+
+ <p>In addition, <code>AudioTrack</code> objects can each be enabled
+ or disabled; this is the audio track's <i>enabled state</i>. When an
+ <code>AudioTrack</code> is created, its <i>enabled state</i> must be
+ set to false (disabled). The <span
+ title="concept-media-load-resource">resource fetch algorithm</span>
+ can override this.</p>
+
+ <p>Similarly, a single <code>VideoTrack</code> object per
+ <code>VideoTrackList</code> object can be selected, this is the
+ video track's <i>selection state</i>. When an
+ <code>VideoTrack</code> is created, its <i>selection state</i> must
+ be set to false (not selected). The <span
+ title="concept-media-load-resource">resource fetch algorithm</span>
+ can override this.</p>
+
+ <p>The <dfn
+ title="dom-AudioTrack-id"><code>AudioTrack.id</code></dfn> and <dfn
+ 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 <span>media resource</span> 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 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>INDEX_SIZE_ERR</code> exception.</p>
+ <p>The <dfn
+ title="dom-AudioTrack-kind"><code>AudioTrack.kind</code></dfn> and
+ <dfn 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
@@ -32381,12 +32467,15 @@
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>AudioTrack</code> objects if they are appropriate
+ for audio, and must only be returned for <code>VideoTrack</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">getKind()</code></caption>
+ <caption>Return values for <code title="dom-AudioTrack-kind">AudioTrack.kind()</code> and <code title="dom-VideoTrack-kind">VideoTrack.kind()</code></caption>
<thead>
<tr>
<th>Category
@@ -32396,37 +32485,43 @@
<tbody>
<tr>
- <td>"<dfn title="dom-TrackList-getKind-alternate"><code>alternative</code></dfn>"
+ <td>"<dfn 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 title="dom-TrackList-getKind-description"><code>description</code></dfn>"
+ <td>"<dfn 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 title="dom-TrackList-getKind-main"><code>main</code></dfn>"
+ <td>"<dfn 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 title="dom-TrackList-getKind-sign"><code>sign</code></dfn>"
+ <td>"<dfn 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 title="dom-TrackList-getKind-translation"><code>translation</code></dfn>"
+ <td>"<dfn 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> <!-- added because of the volume of use cases, but we should remove it if none of the formats start supporting it -->
+ <td>"<dfn 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 title="dom-TrackList-getKind-none"><code></code></dfn>" (empty string)
+ <td>"<dfn 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.
@@ -32435,85 +32530,72 @@
<div class="impl">
- <p>The <dfn 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>INDEX_SIZE_ERR</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
+ title="dom-AudioTrack-label"><code>AudioTrack.label</code></dfn> and
+ <dfn
+ 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 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>INDEX_SIZE_ERR</code> exception. If there is a track with
- index <var title="">index</var>, but it has no language, or the user
+ <p>The <dfn
+ title="dom-AudioTrack-language"><code>AudioTrack.language</code></dfn>
+ and <dfn
+ 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 <span>media
resource</span>'s format is a free-form string without a defined
- interpretation), then the method must return the empty string.</p>
+ interpretation), then the method must return the empty string, as if
+ the track had no language.</p>
- <hr>
+ <p>The <dfn
+ 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>AudioTrackList</code> object, then the track
+ being enabled or disabled has no effect beyond changing the value of
+ the attribute on the <code>AudioTrack</code> object.)</p>
- <p>A <code>MultipleTrackList</code> object represents a track list
- where multiple tracks can be enabled simultaneously. Each track is
- either enabled or disabled.</p>
+ <p>Whenever an audio track in an <code>AudioTrackList</code> is
+ enabled or disabled, the user agent must <span>queue a task</span>
+ to <span>fire a simple event</span> named <code
+ title="event-media-change">change</code> at the
+ <code>AudioTrackList</code> object.</p>
- <p>The <dfn 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>INDEX_SIZE_ERR</code> exception if there is no track with
- index <var title="">index</var>.</p>
+ <p>The <dfn
+ title="dom-VideoTrackList-selectedIndex"><code>VideoTrackList.selectedIndex</code></dfn>
+ attribute must return the index of the currently selected track, if
+ any. If the <code>VideoTrackList</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 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>INDEX_SIZE_ERR</code> exception.</p>
-
- <p>The <dfn 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>INDEX_SIZE_ERR</code> exception.</p>
-
- <p>Whenever a track is enabled or disabled, the user agent must
- <span>queue a task</span> to <span>fire a simple event</span> named
- <code title="event-media-change">change</code> at the
- <code>MultipleTrackList</code> object.</p>
-
- <hr>
-
- <p>An <code>ExclusiveTrackList</code> object represents a track list
- where exactly one track is selected at a time.</p>
-
<p>The <dfn
- title="dom-TrackList-selectedIndex"><code>selectedIndex</code></dfn>
- attribute must return the index of the currently selected track. If
- the <code>ExclusiveTrackList</code> object does not represent any
- tracks, it must instead return −1.</p>
+ 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>VideoTrackList</code>, then all the other
+ <code>VideoTrack</code> objects in that list must be unselected. (If
+ the track is no longer in a <code>VideoTrackList</code> object, then
+ the track being selected or unselected has no effect beyond changing
+ the value of the attribute on the <code>VideoTrack</code>
+ object.)</p>
- <p>The <dfn 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>INDEX_SIZE_ERR</code> exception.</p>
+ <p>Whenever a track in a <code>VideoTrackList</code> that was
+ previously not selected is selected, the user agent must <span>queue
+ a task</span> to <span>fire a simple event</span> named <code
+ title="event-media-change">change</code> at the
+ <code>VideoTrackList</code> object.</p>
- <p>Whenever the selected track is changed, the user agent must
- <span>queue a task</span> to <span>fire a simple event</span> named
- <code title="event-media-change">change</code> at the
- <code>MultipleTrackList</code> object.</p>
-
<hr>
<p>The following are the <span>event handlers</span> (and their
corresponding <span title="event handler event type">event handler
event types</span>) that must be supported, as IDL attributes, by
- all objects implementing the <code>TrackList</code>
- interface:</p>
+ all objects implementing the <code>AudioTrackList</code> and
+ <code>VideoTrackList</code> interfaces:</p>
<table>
<thead>
@@ -32562,7 +32644,6 @@
selection -->
</div>
-<!--END rtc--><!--PEERCONNECTION-->
<h5>Synchronising multiple media elements</h5>
@@ -34448,8 +34529,10 @@
attribute <span>Function</span>? <span title="handler-TextTrack-oncuechange">oncuechange</span>;
};
-<span>TextTrack</span> implements <span>EventTarget</span>;</pre>
+<span>TextTrack</span> implements <span>EventTarget</span>;
+typedef <span>TextTrack</span>[] <dfn>TextTrackList</dfn>;</pre>
+
<dl class="domintro">
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-kind">kind</code></dt>
@@ -34881,13 +34964,13 @@
cue">cues</span> in the list represented by the
<code>TextTrackCueList</code> object.</p>
- <p>The <span>supported property indicies</span> of a
+ <p>The <span>supported property indices</span> of a
<code>TextTrackCueList</code> object at any instant are the numbers
from zero to the number of <span title="text track cue">cues</span>
in the list represented by the <code>TextTrackCueList</code> object
minus one, if any. If there are no <span title="text track
cue">cues</span> in the list, there are no <span>supported property
- indicies</span>.</p>
+ indices</span>.</p>
<p>To <span>determine the value of an indexed property</span> for a
given index <var title="">index</var>, the user agent must return
@@ -85503,14 +85586,14 @@
stream.</p>
<p>If <var title="">audio</var> is true, then the provided media
- should include an audio component. If <var title="">audio</var>
+ should include an audio track. If <var title="">audio</var>
is false, then the provided media must not include an audio
- component.</p>
+ track.</p>
<p>If <var title="">video</var> is true, then the provided media
- should include a video component. If <var title="">video</var> is
+ should include a video track. If <var title="">video</var> is
false, then the provided media must not include a video
- component.</p>
+ track.</p>
<p>User agents are encouraged to default to using the user's
primary or system default camera and/or microphone (as
@@ -85611,6 +85694,8 @@
<h3>Stream API</h3>
+ <h4>Introduction</h4>
+
<p>The <code>MediaStream</code> interface is used to represent
streams of media data, typically (but not necessarily) of audio
and/or video content, e.g. from a local camera or a remote site. The
@@ -85620,6 +85705,322 @@
user agents to manipulate media streams in whatever fashion is most
suitable on the user's platform.</p>
+ <p>Each <code>MediaStream</code> object can represent zero or more
+ tracks, in particular audio and video tracks. Tracks can contain
+ multiple channels of parallel data; for example a single audio track
+ could have nine channels of audio data to represent a 7.2 surround
+ sound audio track.</p>
+
+ <p>Each track represented by a <code>MediaStream</code> object has a
+ corresponding <code>StreamTrack</code> object.</p>
+
+ <p>A <code>MediaStream</code> object has an input and an output. The
+ input depends on how the object was created: a
+ <code>LocalMediaStream</code> object generated by a <code
+ title="dom-navigator-getUserMedia">getUserMedia()</code> call, for
+ instance, might take its input from the user's local camera, while a
+ <code>MediaStream</code> created by a <code>PeerConnection</code>
+ object will take as input the data received from a remote peer. The
+ output of the object controls how the object is used, e.g. what is
+ saved if the object is written to a file, what is displayed if the
+ object is used in a <code>video</code> element, or indeed what is
+ transmitted to a remote peer if the object is used with a
+ <code>PeerConnection</code> object.</p>
+
+ <p>Each track in a <code>MediaStream</code> object can be disabled,
+ meaning that it does not appear in the object's output. All tracks
+ are initially enabled.</p>
+
+ <p>A <code>MediaStream</code> object's output can be "forked" by
+ creating a new <code>MediaStream</code> object from it using the
+ <code title="dom-MediaStream">MediaStream()</code> constructor. The
+ new <code>MediaStream</code> object's input is the output of the
+ object from which it was created, and its output is therefore at
+ most a subset of the "parent" object.</p>
+
+ <p><img src="images/media-stream-1.png" alt=""></p><!-- no alt since
+ it's all described in the previous paragraphs: this is just a
+ summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ stroke();
+ }
+ mediaStream(c,50,10, true);
+
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText('MediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>This can be used, for instance, in a video-conferencing scenario
+ to display the local video from the user's camera and microphone in
+ a local monitor, while only transmitting the audio to the remote
+ peer (e.g. in response to the user using a "video mute"
+ feature).</p>
+
+ <p><img src="images/media-stream-2.png" alt=""></p><!-- again, no
+ alt since it's all described in the previous paragraphs: this is
+ just a summary -->
+
+<!--
+c.clearRect(0, 0, 640, 480);
+c.save();
+try {
+ with (c) {
+ save();
+ strokeStyle = '#AA0000';
+ lineWidth = 20;
+ beginPath();
+ moveTo(50,98);
+ lineTo(550, 98);
+ lineTo(550, 210);
+ lineTo(50, 210);
+ lineTo(50, 320);
+ lineTo(550, 320);
+ lineTo(550,420);
+ stroke();
+ beginPath();
+ moveTo(50,320);
+ lineTo(50,420);
+ stroke();
+ restore();
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ fillText('<video>', 50, 440);
+ fillText('PeerConnection', 550, 440);
+ font = '100 8px "Press Start 2P", sans-serif';
+ }
+ cameraIcon(c,25,98)
+ mediaStream(c,50,10, true);
+ mediaStream(c,50,233, false);
+
+ with (c) {
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'middle';
+ fillStyle = 'gray';
+
+ fillText('from', 4, 130);
+ fillText('getUserMedia()', 4, 140);
+
+ fillText('via URL.getObjectURL()', 4, 450);
+
+ textAlign = 'center';
+ fillText('via addStream()', 550, 450);
+ }
+} finally {
+ c.restore();
+}
+
+function cameraIcon(c,x,y) {
+ with (c) { save(); try {
+ translate(x,y);
+ fillRect(-10,-10,20,20);
+ beginPath();
+ moveTo(7,0);
+ lineTo(20,-10);
+ lineTo(20,10);
+ fill();
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'top';
+ fillText('Camera', 4, 15);
+ } finally { restore(); } }
+}
+
+function mediaStream(c,x,y,vid) {
+ with (c) {
+ save();
+ translate(x-10,y-97);
+
+ // cable
+ fillStyle = 'black';
+ font = '100 10px "Press Start 2P", sans-serif';
+ textAlign = 'right';
+ fillText('Input', 95, 170);
+ textAlign = 'left';
+ fillText('Output', 407, 170);
+
+ // media stream
+ fillStyle = '#EE8800';
+ strokeStyle = '#FFCC00';
+ lineWidth = 6;
+ fillRect(100,100,300,170);
+ strokeRect(100,100,300,170);
+ fillStyle = 'black';
+ font = '900 12px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ fillText(!vid ? 'MediaStream' : 'LocalMediaStream', 110, 123);
+
+ // tracks
+ textAlign = 'left';
+ strokeStyle = '#CC3300';
+ fillStyle = '#FFFF00';
+ lineWidth = 4;
+ globalAlpha = vid ? 1 : 0.4;
+ fillRect(120,140,100,110);
+ strokeRect(120,140,100,110);
+ globalAlpha = 1;
+ fillRect(238,140,100,110);
+ strokeRect(238,140,100,110);
+ fillStyle = 'black';
+ font = '900 10px "Press Start 2P", sans-serif';
+ globalAlpha = vid ? 1 : 0.4;
+ fillText('Track', 123, 155);
+ fillText('(video)', 123, 170);
+ globalAlpha = 1;
+ fillText('Track', 241, 155);
+ fillText('(stereo', 241, 170);
+ fillText(' audio)', 241, 185);
+
+ // channels
+ strokeStyle = '#999999';
+ fillStyle = '#FFFFFF';
+ lineWidth = 2;
+ fillRect(245,191,86,23);
+ strokeRect(245,191,86,23);
+ fillRect(245,220,86,23);
+ strokeRect(245,220,86,23);
+ fillStyle = 'black';
+ font = '100 8px "Press Start 2P", sans-serif';
+ textAlign = 'left';
+ textBaseline = 'alphabetic';
+ fillText('left', 249, 202);
+ fillText('channel', 249, 211);
+ fillText('right', 249, 231);
+ fillText('channel', 249, 240);
+
+ // track check marks
+ fillStyle = 'black';
+ font = '900 35px "Lucida Grande", sans-serif';
+ textAlign = 'center';
+ textBaseline = 'middle';
+ fillText(vid ? '\u2713' : '\u2716', 220, 245);
+ fillText('\u2713', 338, 245);
+
+ restore();
+ }
+}
+-->
+
+ <p>If a track in a <code>MediaStream</code> <var
+ title="">parent</var> is disabled, it does not have a corresponding
+ track in any <code>MediaStream</code> objects that were created from
+ <var title="">parent</var>. When a track in a
+ <code>MediaStream</code> <var title="">parent</var> is disabled, any
+ <code>StreamTrack</code> objects corresponding to the tracks in any
+ <code>MediaStream</code> objects that were created from <var
+ title="">parent</var> are disassociated from any track, and must not
+ be reused for tracks again. If a disabled track in a
+ <code>MediaStream</code> <var title="">parent</var> is re-enabled,
+ from the perspective of any <code>MediaStream</code> objects that
+ were created from <var title="">parent</var> it is a new track and
+ thus new <code>StreamTrack</code> objects must be created for the
+ tracks that correspond to the re-enabled track.</p>
+
+ <hr>
+
<p>The <code>LocalMediaStream</code> interface is used when the user
agent is generating the stream's data (e.g. from a camera or
streaming it from a local video file). It allows authors to control
@@ -85634,14 +86035,20 @@
live video from pre-recorded video, which can help protect the
user's privacy.</p>
+
+ <h4>Interface definitions</h4>
+
<!-- v2: support reading the bits from the stream directly, for use
with streaming over WebSocket? Or do we rely on FileReader for that?
sicking suggests defining a DataStream or BlobStream interface that
you can get from a Stream to get to the underlying data; such an
object would then be readable using the File API -->
- <pre class="idl">interface <dfn>MediaStream</dfn> {
+ <pre class="idl">[<span title="dom-MediaStream">Constructor</span>(in <span>MediaStream</span> parentStream)]
+interface <dfn>MediaStream</dfn> {
readonly attribute DOMString <span title="dom-MediaStream-label">label</span>;
+ readonly attribute <span>StreamTrackList</span> <span title="dom-MediaStream-tracks">tracks</span>;
+
<span>MediaStreamRecorder</span> <span title="dom-MediaStream-record">record</span>();
<!--
const unsigned short <span title="dom-MediaStream-LOADING">LOADING</span> = 0; -->
@@ -85654,14 +86061,27 @@
interface <dfn>LocalMediaStream</dfn> : <span>MediaStream</span> {
void <span title="dom-MediaStream-stop">stop</span>();
+};
- // track control
- readonly attribute <span>MultipleTrackList</span> <span title="dom-MediaStream-audioTracks">audioTracks</span>;
- readonly attribute <span>ExclusiveTrackList</span> <span title="dom-MediaStream-videoTracks">videoTracks</span>;
+typedef <span>StreamTrack</span>[] <dfn>StreamTrackList</dfn>;
+
+interface <dfn>StreamTrack</dfn> {
+ readonly attribute DOMString <span title="dom-StreamTrack-kind">kind</span>;
+ readonly attribute DOMString <span title="dom-StreamTrack-label">label</span>;
+ attribute boolean <span title="dom-StreamTrack-enabled">enabled</span>;
};</pre>
<dl class="domintro">
+ <dt><var title="">stream</var> = new <code title="dom-MediaStream">MediaStream</code>( <var title="">parentStream</var> )</dt>
+
+ <dd>
+
+ <p>Creates a new <code>MediaStream</code> object whose tracks are the enabled tracks of <var title="">parentStream</var>.</p>
+
+ </dd>
+
+
<dt><var title="">stream</var> . <code title="dom-MediaStream-label">label</code></dt>
<dd>
@@ -85693,31 +86113,74 @@
</dd>
- <dt><var title="">stream</var> . <code title="dom-MediaStream-audioTracks">audioTracks</code></dt>
+ <dt><var title="">stream</var> . <code title="dom-MediaStream-tracks">tracks</code></dt>
<dd>
- <p>Returns a <code>MultipleTrackList</code> object representing
- the audio tracks available for mixing into the
- <code>LocalMediaStream</code>'s stream.</p>
+ <p>Returns a <code>StreamTrackList</code> object representing
+ the tracks that can be enabled and disabled.</p>
</dd>
- <dt><var title="">stream</var> . <code title="dom-MediaStream-videoTracks">videoTracks</code></dt>
+ <dt><var title="">stream</var> . <code title="dom-MediaStream-tracks">tracks</code> . <code title="dom-StreamTrackList-length">length</code></dt>
+
<dd>
- <p>Returns an <code>ExclusiveTrackList</code> object representing
- the video tracks available for the <code>LocalMediaStream</code>'s
- stream.</p>
+ <p>Returns the number of tracks in the list.</p>
</dd>
+ <dt><var title="">track</var> = <var title="">stream</var> . <code title="dom-MediaStream-tracks">tracks</code>[<var title="">index</var>]</dt>
+
+ <dd>
+
+ <p>Returns the specified <code>StreamTrack</code> object.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title="dom-StreamTrack-label">label</code></dt>
+
+ <dd>
+
+ <p>Returns the string "<code title="">audio</code>" if the track
+ is an audio track, and the string "<code title="">video</code>" if
+ it is a video track.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title="dom-StreamTrack-label">label</code></dt>
+
+ <dd>
+
+ <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
+
+ </dd>
+
+
+ <dt><var title="">track</var> . <code title="dom-StreamTrack-enabled">enabled</code> [ = <var title="">value</var> ]</dt>
+
+ <dd>
+
+ <p>Returns true if the given track is active in the <code>MediaStream</code>'s output, and false otherwise.</p>
+
+ <p>Can be set, to change whether the track is enabled or not.</p>
+
+ </dd>
+
</dl>
<div class="impl">
+ <p>The <dfn title="dom-MediaStream"><code>MediaStream(<var
+ title="">parentStream</var>)</code></dfn> constructor must return a
+ new <code>MediaStream</code> object whose tracks at any moment in
+ time are the enabled tracks of <var title="">parentStream</var> at
+ that moment.</p>
+
<p>The <dfn
title="dom-MediaStream-readyState"><code>readyState</code></dfn>
attribute represents the state of the stream. It must return the
@@ -85740,18 +86203,34 @@
</dl>
<p>When a <code>MediaStream</code> object is created, its <code
- title="dom-MediaStream-readyState">readyState</code> attribute must be
- set to <code title="dom-MediaStream-LIVE">LIVE</code> (1).</p>
+ title="dom-MediaStream-readyState">readyState</code> attribute must
+ be set to <code title="dom-MediaStream-LIVE">LIVE</code> (1), unless
+ it is being created using the <code
+ title="dom-MediaStream">MediaStream()</code> constructor whose
+ argument is a <code>MediaStream</code> object whose <code
+ title="dom-MediaStream-readyState">readyState</code> attribute has
+ the value <code title="dom-MediaStream-ENDED">ENDED</code> (2), in
+ which case the <code>MediaStream</code> object must be created with
+ its <code title="dom-MediaStream-readyState">readyState</code>
+ attribute set to <code title="dom-MediaStream-ENDED">ENDED</code>
+ (2).</p>
- <p>When a <code>MediaStream</code> object ends for any reason other than
- the <code title="dom-MediaStream-stop">stop()</code> method being invoked
- (e.g. because the user rescinds the permission for the page to use
- the local camera, or because the data comes from a finite file and
- the file's end has been reached and the user has not requested that
- it be looped, or because the stream comes from a remote peer and the
- remote peer has permanently stopped sending data), the user agent
- must <span>queue a task</span> that runs the following steps:</p>
+ <p>A <code>MediaStream</code> object is said to <i>end</i> when the
+ user agent learns that no more data will ever be forthcoming for
+ this stream.</p>
+ <p>When a <code>MediaStream</code> object ends for any reason other
+ than the <code title="dom-MediaStream-stop">stop()</code> method
+ being invoked (e.g. because the user rescinds the permission for the
+ page to use the local camera, or because the data comes from a
+ finite file and the file's end has been reached and the user has not
+ requested that it be looped, or because the stream comes from a
+ remote peer and the remote peer has permanently stopped sending
+ data, or because the <code>MediaStream</code> was created from
+ another <code>MediaStream</code> and that stream has just itself
+ ended), the user agent must <span>queue a task</span> that runs the
+ following steps:</p>
+
<ol>
<li><p>If the object's <code
@@ -85827,7 +86306,7 @@
source, then the user agent should remove any active "on-air"
indicator. If the data is being generated from a prerecorded source
(e.g. a video file), any remaining content in the file is
- ignored.</p></li>
+ ignored. The stream has <i>ended</i>.</p></li>
<li><p>Set the object's <code
title="dom-MediaStream-readyState">readyState</code> attribute to
@@ -85845,49 +86324,70 @@
<hr>
- <p>A <code>LocalMediaStream</code> can have multiple audio and video
+ <p>A <code>MediaStream</code> can have multiple audio and video
sources (e.g. because the user has multiple microphones, or because
the real source of the stream is a <span>media resource</span> with
many media tracks). The stream represented by a
- <code>LocalMediaStream</code> has either zero or one audio track and
- either zero or one video track.</p>
+ <code>MediaStream</code> thus has zero or more tracks.</p>
- <div class="impl">
+ <hr>
- <p>The <dfn
- title="dom-MediaStream-audioTracks"><code>audioTracks</code></dfn>
- attribute of a <code>LocalMediaStream</code> object must return a
- <span>live</span> <code>MultipleTrackList</code> object representing
- the audio sources available to the <code>LocalMediaStream</code>. The
- same object must be returned each time. The
- <code>LocalMediaStream</code>'s output audio track must be the result
- of mixing all the enabled audio sources, if any.</p>
+ <p>The <dfn title="dom-MediaStream-tracks"><code>tracks</code></dfn>
+ attribute must return an <span title="array host objects">array host
+ object</span> for objects of type <code>StreamTrack</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>
+ <p>The array must contain the <code>StreamTrack</code> objects that
+ correspond to the the tracks of the stream. The relative order of
+ all tracks in a user agent must be stable. All audio tracks must
+ precede all video tracks. Tracks that come from a <span>media
+ resource</span> whose format defines an order must be in the order
+ defined by the format; tracks that come from a <span>media
+ resource</span> whose format does not define an order must be in the
+ relative order in which the tracks are declared in that <span>media
+ resource</span>. Within these constraints, the order is user-agent
+ defined.</p> <!-- doesn't matter currently since I can't think of
+ any way that you can get multiple tracks together. It would matter
+ if we allowed a MediaStream() constructor that took an array of
+ streams, though, or if getUserMedia() could return multiple audio or
+ video tracks. -->
+
<p>The <dfn
- title="dom-MediaStream-videoTracks"><code>videoTracks</code></dfn>
- attribute of a <code>LocalMediaStream</code> object must return a
- <span>live</span> <code>ExclusiveTrackList</code> object
- representing the video sources available to the
- <code>LocalMediaStream</code>. The same object must be returned each
- time. The <code>LocalMediaStream</code>'s output video track must be
- the selected video source, if any.</p>
+ title="dom-StreamTrack-kind"><code>StreamTrack.kind</code></dfn>
+ attribute must return the string "<code title="">audio</code>" if
+ the object's corresponding track is or was an audio track, "<code
+ title="">video</code>" if the corresponding track is or was a video
+ track, and a user-agent defined string otherwise.</p>
<p>User agents may label audio and video sources (e.g. "Internal
- microphone" or "External USB Webcam"), in which case the <code
- title="dom-TrackList-getLabel">getLabel()</code> methods (on the
- <code>MultipleTrackList</code> and <code>ExclusiveTrackList</code>
- objects) must use the labels the user agent has assigned as the
- track labels of the source tracks of the <code>LocalMediaStream</code>
- object. Otherwise, the <code
- title="dom-TrackList-getLabel">getLabel()</code> methods must use the
- empty string as the track labels of the source tracks of the
- <code>LocalMediaStream</code> object. The <code
- title="dom-TrackList-getLanguage">getLanguage()</code> methods must
- use the empty string as the track language for all the source tracks
- of the <code>LocalMediaStream</code> object.</p>
+ microphone" or "External USB Webcam"). The <dfn
+ title="dom-StreamTrack-label"><code>StreamTrack.label</code></dfn>
+ attribute must return the label of the object's corresponding track,
+ if any. If the corresponding track has or had no label, the
+ attribute must instead return the empty string.</p>
- </div>
+ <p class="note">Thus the <code
+ title="dom-StreamTrack-kind">kind</code> and <code
+ title="dom-StreamTrack-label">label</code> attributes do not change
+ value, even if the <code>StreamTrack</code> object is disassociated
+ from its corresponding track.</p>
+ <p>The <dfn
+ title="dom-StreamTrack-enabled"><code>StreamTrack.enabled</code></dfn>
+ attribute, on getting, must return the last value to which it was
+ set. On setting, it must be set to the new value, and then, if the
+ <code>StreamTrack</code> object is still associated with a track,
+ must enable the track if the new value is true, and disable it
+ otherwise.</p>
+
+ <p class="note">Thus, after a <code>StreamTrack</code> is
+ disassociated from its track, its <code
+ title="dom-StreamTrack-enabled">enabled</code> attribute still
+ changes value when set, it just doesn't do anything with that new
+ value.</p>
+
<hr>
<p>The following are the <span>event handlers</span> (and their
@@ -91757,7 +92257,7 @@
either the <var title="">source port</var> or the <var
title="">target port</var> (if any), then throw a
<code>DATA_CLONE_ERR</code> exception and abort these
- steps.</p></li>
+ steps.</p>
</li>
More information about the Commit-Watchers
mailing list