[agiow] (0) Change how pausing media is exposed in GeneratedStream, a…

…nd expose multiple tracks. git-svn-id: http://svn.whatwg.org/webapps@5965 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Mar 25, 2011 · 9b783f3 · 9b783f3
1 parent 4e57ced
commit 9b783f3
Show file tree

Hide file tree

Showing 3 changed files with 180 additions and 253 deletions.
diff --git a/complete.html b/complete.html
@@ -28163,11 +28163,20 @@ <h5 id=media-resources-with-multiple-media-tracks><span class=secno>4.8.10.10 </
   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
+  element</a>, even if another <a href=#media-resource>media resource</a> is
+  loaded into the element: the objects are reused.</p>
+
   </div>
 
 
   <h6 id=tracklist-objects><span class=secno>4.8.10.10.1 </span><code><a href=#tracklist>TrackList</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=#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
@@ -28257,12 +28266,6 @@ <h6 id=tracklist-objects><span class=secno>4.8.10.10.1 </span><code><a href=#tra
 
   </dl><div class=impl>
 
-  <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
-  element</a>, even if another <a href=#media-resource>media resource</a> is
-  loaded into the element: the objects are reused.</p>
-
   <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>
@@ -72069,9 +72072,10 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
 
   <p>The <code><a href=#generatedstream>GeneratedStream</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 pause
-  the generation of the content, e.g. to allow the user to temporarily
-  disable a local camera during a video-conference chat.</p>
+  streaming it from a local video file). It allows authors to control
+  individual tracks during the generation of the content, e.g. to
+  allow the user to temporarily disable a local camera during a
+  video-conference chat.</p>
 
   <p>When a <code><a href=#generatedstream>GeneratedStream</a></code> object is being generated
   from a local file (as opposed to a live audio/video source), the
@@ -72098,12 +72102,9 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
 interface <dfn id=generatedstream>GeneratedStream</dfn> : <a href=#stream>Stream</a> {
   void <a href=#dom-stream-stop title=dom-stream-stop>stop</a>();
 
-  // temporarily pausing the stream
-  const unsigned short <a href=#dom-stream-paused title=dom-stream-PAUSED>PAUSED</a> = 3;
-  void <a href=#dom-stream-pause title=dom-stream-pause>pause</a>();
-  void <a href=#dom-stream-resume title=dom-stream-resume>resume</a>();
-           attribute <a href=#function>Function</a> <a href=#handler-stream-onpause title=handler-stream-onpause>onpause</a>;
-           attribute <a href=#function>Function</a> <a href=#handler-stream-onplay title=handler-stream-onplay>onplay</a>;
+  // track control
+  readonly attribute <a href=#multipletracklist>MultipleTrackList</a> <a href=#dom-stream-audiotracks title=dom-stream-audioTracks>audioTracks</a>;
+  readonly attribute <a href=#exclusivetracklist>ExclusiveTrackList</a> <a href=#dom-stream-videotracks title=dom-stream-videoTracks>videoTracks</a>;
 };</pre>
 
   <dl class=domintro><dt><var title="">stream</var> . <code title=dom-stream-label><a href=#dom-stream-label>label</a></code></dt>
@@ -72137,32 +72138,26 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
    </dd>
 
 
-   <dt><var title="">stream</var> . <code title=dom-stream-paused><a href=#dom-stream-paused>paused</a></code></dt>
+   <dt><var title="">stream</var> . <code title=dom-stream-audioTracks><a href=#dom-stream-audiotracks>audioTracks</a></code></dt>
 
    <dd>
 
-    <p>Returns false if the stream is generating data; true if it is pause.</p>
+    <p>Returns a <code><a href=#multipletracklist>MultipleTrackList</a></code> object representing
+    the audio tracks available for mixing into the <code><a href=#generatedstream>GeneratedStream</a></code>'s stream.</p>
 
    </dd>
 
-
-   <dt><var title="">stream</var> . <code title=dom-stream-pause><a href=#dom-stream-pause>pause</a></code>()</dt>
+   <dt><var title="">stream</var> . <code title=dom-stream-videoTracks><a href=#dom-stream-videotracks>videoTracks</a></code></dt>
 
    <dd>
 
-    <p>Temporarily stops the generation of media data for the stream.</p>
+    <p>Returns an <code><a href=#exclusivetracklist>ExclusiveTrackList</a></code> object representing
+    the video tracks available for the <code><a href=#generatedstream>GeneratedStream</a></code>'s
+    stream.</p>
 
    </dd>
 
 
-   <dt><var title="">stream</var> . <code title=dom-stream-resume><a href=#dom-stream-resume>resume</a></code>()</dt>
-
-   <dd>
-
-    <p>Resumes the generation of media data for the stream if it was temporarily stopped.</p>
-
-   </dd>
-
   </dl><div class=impl>
 
   <p>The <dfn id=dom-stream-readystate title=dom-stream-readyState><code>readyState</code></dfn>
@@ -72181,12 +72176,6 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
    or generating data, and will never receive or generate more data
    for this stream).</dd>
 
-   <dt><dfn id=dom-stream-paused title=dom-stream-PAUSED><code>PAUSED</code></dfn> (numeric value 3)</dt>
-
-   <dd>The stream is not generating data at this time, but could still
-   be resumed. Only <code><a href=#generatedstream>GeneratedStream</a></code> objects can be in
-   this state.</dd>
-
   </dl><p>When a <code><a href=#stream>Stream</a></code> object is created, its <code title=dom-stream-readyState><a href=#dom-stream-readystate>readyState</a></code> attribute must be
   set to <code title=dom-stream-LIVE><a href=#dom-stream-live>LIVE</a></code> (1).</p>
 
@@ -72258,43 +72247,46 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
 
    <li><p><a href=#fire-a-simple-event>Fire a simple event</a> named <code title=event-stream-ended>ended</code> at the object.</li>
 
-  </ol><hr><p>When a <code><a href=#generatedstream>GeneratedStream</a></code> object's <dfn id=dom-stream-pause title=dom-stream-pause><code>pause()</code></dfn> method is
-  invoked, 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-stream-readyState><a href=#dom-stream-readystate>readyState</a></code> attribute is not in
-   the <code title=dom-stream-LIVE><a href=#dom-stream-live>LIVE</a></code> (1) state, then abort
-   these steps.</li>
-
-   <li><p>Pause the generation of data for the stream. If the data is
-   being generated from a live source (e.g. a microphone or camera),
-   then data collected for this stream while the stream is paused must
-   be discarded. If the data is being generated from a prerecorded
-   source (e.g. a video file), the user agent should follow user
-   preferences for handling a pause (either skipping over data in real
-   time or resuming from the same point when the stream is later
-   resumed).</li>
-
-   <li><p>Set the object's <code title=dom-stream-readyState><a href=#dom-stream-readystate>readyState</a></code> attribute to <code title=dom-stream-PAUSED><a href=#dom-stream-paused>PAUSED</a></code> (3).</li>
-
-   <li><p><a href=#fire-a-simple-event>Fire a simple event</a> named <code title=event-stream-pause>pause</code> at the object.</li>
+  </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-stream-stop><a href=#dom-stream-stop>stop()</a></code> method is the <a href=#dom-manipulation-task-source>DOM
+  manipulation task source</a>.</p>
 
-  </ol><p>When a <code><a href=#generatedstream>GeneratedStream</a></code> object's <dfn id=dom-stream-resume title=dom-stream-resume><code>resume()</code></dfn> method is
-  invoked, the user agent must <a href=#queue-a-task>queue a task</a> that runs the
-  following steps:</p>
+  <hr><p>A <code><a href=#generatedstream>GeneratedStream</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=#generatedstream>GeneratedStream</a></code> has either zero or one audio track and
+  either zero or one video track.</p>
 
-  <ol><li><p>If the object's <code title=dom-stream-readyState><a href=#dom-stream-readystate>readyState</a></code> attribute is not in
-   the <code title=dom-stream-PAUSED><a href=#dom-stream-paused>PAUSED</a></code> (3) state, then
-   abort these steps.</li>
+  <div class=impl>
 
-   <li><p>Resume the generation of data for the stream.</li>
+  <p>The <dfn id=dom-stream-audiotracks title=dom-stream-audioTracks><code>audioTracks</code></dfn>
+  attribute of a <code><a href=#generatedstream>GeneratedStream</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=#generatedstream>GeneratedStream</a></code>. The
+  same object must be returned each time. The
+  <code><a href=#generatedstream>GeneratedStream</a></code>'s output audio track must be the result
+  of mixing all the enabled audio sources, if any.</p>
 
-   <li><p>Set the object's <code title=dom-stream-readyState><a href=#dom-stream-readystate>readyState</a></code> attribute to <code title=dom-stream-LIVE><a href=#dom-stream-live>LIVE</a></code> (1).</li>
+  <p>The <dfn id=dom-stream-videotracks title=dom-stream-videoTracks><code>videoTracks</code></dfn>
+  attribute of a <code><a href=#generatedstream>GeneratedStream</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=#generatedstream>GeneratedStream</a></code>. The same object must be returned each
+  time. The <code><a href=#generatedstream>GeneratedStream</a></code>'s output video track must be
+  the selected video source, if any.</p>
 
-   <li><p><a href=#fire-a-simple-event>Fire a simple event</a> named <code title=event-stream-play>play</code> at the object.</li>
+  <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-getName><a href=#dom-tracklist-getname>getName()</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 names of the source tracks of the <code><a href=#generatedstream>GeneratedStream</a></code>
+  object. Otherwise, the <code title=dom-TrackList-getName><a href=#dom-tracklist-getname>getName()</a></code> methods must use the
+  empty string as the track names of the source tracks of the
+  <code><a href=#generatedstream>GeneratedStream</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=#generatedstream>GeneratedStream</a></code> object.</p>
 
-  </ol><hr><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-stream-stop><a href=#dom-stream-stop>stop()</a></code>, <code title=dom-stream-pause><a href=#dom-stream-pause>pause()</a></code>, and <code title=dom-stream-resume><a href=#dom-stream-resume>resume()</a></code> methods is the <a href=#dom-manipulation-task-source>DOM
-  manipulation task source</a>.</p>
+  </div>
 
   <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
@@ -72303,15 +72295,6 @@ <h3 id=stream-api><span class=secno>9.3 </span>Stream API</h3>
 
   <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-stream-onended title=handler-stream-onended><code>onended</code></dfn> <td> <code title=event-stream-ended>ended</code>
-  </table><p>The following are the additional <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=#generatedstream>GeneratedStream</a></code> interface:</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-stream-onpause title=handler-stream-onpause><code>onpause</code></dfn> <td> <code title=event-stream-pause>pause</code>
-    <tr><td><dfn id=handler-stream-onplay title=handler-stream-onplay><code>onplay</code></dfn> <td> <code title=event-stream-play>play</code>
   </table></div>
 
   <div class=example>