- From: CVS User abergkvi <cvsmail@w3.org>
- Date: Thu, 17 Oct 2013 11:17:27 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv27569
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20131017 archived version.
--- /sources/public/2011/webrtc/editor/getusermedia.html 2013/08/30 07:40:31 1.23
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2013/10/17 11:17:27 1.24
@@ -30,20 +30,7 @@
<section id="sotd">
<p>This document is not complete. It is subject to major changes and, while
early experimentations are encouraged, it is therefore not intended for
- implementation. The API is based on preliminary work done in the WHATWG.
- The Media Capture Task Force expects this specification to evolve
- significantly based on:</p>
-
- <ul>
- <li>Privacy issues that arise when exposing local capabilities and local
- streams.</li>
-
- <li>Technical discussions within the task force.</li>
-
- <li>Experience gained through early experimentations.</li>
-
- <li>Feedback received from other groups and individuals.</li>
- </ul>
+ implementation. The API is based on preliminary work done in the WHATWG.</p>
</section>
<section class="informative" id="intro">
@@ -54,7 +41,7 @@
real-time communication, recording, and surveillance.</p>
<p>This document defines the APIs used to get access to local devices that
- can generate multimedia stream data. This document also defines the stream
+ can generate multimedia stream data. This document also defines the MediaStream
API by which JavaScript is able to manipulate the stream data or otherwise
process it.</p>
</section>
@@ -98,7 +85,7 @@
</p>
</dd>
- <dt><dfn title="source" id="dfn-source">source</dfn></dt>
+ <dt><dfn>source</dfn></dt>
<dd>
<p>A source is the "thing" providing the source of a media stream
track. The source is the broadcaster of the media itself. A
@@ -148,8 +135,7 @@
the same answer).</p>
</dd>
- <dt><dfn title=""
- id="dfn-state">State (Source State)</dfn></dt>
+ <dt><dfn title="state">State (Source State)</dfn></dt>
<dd>
<p>State refers to the immediate, current value of the
source's (optionally constrained) capabilities. State is
@@ -163,10 +149,8 @@
<p>A source's state is directly exposed to audio and video
track objects through individual read-only attributes. These
attributes share the same name as their
- corresponding <a class="internalDFN"
- href="#dfn-capabilities">capabilities</a>
- and <a class="internalDFN"
- href="#dfn-constraints">constraints</a>.</p>
+ corresponding <a>capabilities</a>
+ and <a>constraints</a>.</p>
<p>Events are available that signal to the application that
source state has changed.</p>
<p>A conforming user-agent <em title="must"
@@ -239,7 +223,7 @@
<p>Constraints that are intended for video sources will be
ignored by audio sources and vice-versa. Similarly,
constraints that are not recognized will be preserved in the
- constraint structure, but ignored by the application. This
+ constraint structure, but ignored by the UA. This
will allow future constraints to be defined in a backward
compatible manner.</p>
@@ -253,7 +237,7 @@
</section>
<section id="stream-api">
- <h2>Stream API</h2>
+ <h2>MediaStream API</h2>
<section>
<h2>Introduction</h2>
@@ -310,7 +294,7 @@
<code><a>MediaStream</a></code> object, in which case all the tracks of
the given stream are added to the new <code><a>MediaStream</a></code>
object, or an array of <code><a>MediaStreamTrack</a></code> objects. The
- latter from makes it possible to compose a stream from different source
+ latter form makes it possible to compose a stream from different source
streams.</p>
<p><img alt="A MediaStream" src="images/media-stream.png" width=
@@ -339,8 +323,8 @@
<p>The <dfn id="dom-mediastream"> <code>MediaStream()</code></dfn>
constructor composes a new stream out of existing tracks. It takes an
optional argument of type <code><a>MediaStream</a></code> or an array of
- <code><a>MediaStreamTrack</a></code> objects. When the constructor is
- invoked, the UA must run the following steps:</p>
+ <code><a>MediaStreamTrack</a></code> objects. <dfn id='mediastream-constructor'>When the constructor is
+ invoked</dfn>, the UA must run the following steps:</p>
<ol>
<li>
@@ -373,11 +357,8 @@
</li>
<li>
- <p>If <var>track</var> has <a>ended</a> or if there is already
- a <code><a>MediaStreamTrack</a></code> contained within
- <var>stream</var> that has the same underlying source as
- <var>track</var>, then abort these steps and continue with the
- next track (if any).</p>
+ <p>If <var>track</var> has <a href="#track-ended">ended</a>, then abort these
+ steps and continue with the next track (if any).</p>
</li>
<li>
@@ -400,6 +381,13 @@
</li>
<li>
+ <p>If <var>stream</var>'s <a href="#track-set">track set</a> is
+ empty, set <var>stream</var>'s <code><a href=
+ "#dom-mediastream-inactive">inactive</a></code> attribute to
+ <code>true</code>, otherwise set it to <code>false</code>.</p>
+ </li>
+
+ <li>
<p>Return <var>stream</var>.</p>
</li>
</ol>
@@ -422,59 +410,46 @@
<p>An object that reads data from the output of a
<code><a>MediaStream</a></code> is referred to as a
<code><a>MediaStream</a></code> <dfn>consumer</dfn>. The list of
- <code><a>MediaStream</a></code> consumers currently includes the media
- elements and the <code><a>PeerConnection</a></code> API specified in
- [[!WEBRTC10]].</p>
+ <code><a>MediaStream</a></code> consumers currently include the media
+ elements [[!HTML5]], <code>RTCPeerConnection</code> [[!WEBRTC10]],
+ <code>MediaRecorder</code> [[!mediastream-rec]] and
+ <code>ImageCapture</code> [[!mediastream-imagecap]].</p>
<p class="note"><code><a>MediaStream</a></code> consumers must be able to
handle tracks being added and removed. This behavior is specified per
consumer.</p>
<p>A <code><a>MediaStream</a></code> object is said to be
- <dfn>finished</dfn> when all tracks belonging to the stream have
- <a>ended</a>. When this happens for any reason other than the
- <code><a href="#dom-mediastreamtrack-stop">stop()</a></code> method being
- invoked, the user agent MUST queue a task that runs the following
- steps:</p>
-
- <ol>
- <li>
- <p>If the object's <code><a href=
- "#dom-mediastream-ended">ended</a></code> attribute has the value
- true already, then abort these steps. (The <code><a href=
- "#dom-mediastreamtrack-stop">stop()</a></code> method was probably called
- just before the stream stopped for other reasons, e.g. the user
- clicked an in-page stop button and then the user agent provided stop
- button.)</p>
- </li>
-
- <li>
- <p>Set the object's <code><a href=
- "#dom-mediastream-ended">ended</a></code> attribute to true.</p>
- </li>
+ <dfn id="stream-inactive">inactive</dfn> when it does not have any tracks
+ or all tracks belonging to the stream have <a href="#track-ended">ended</a>. Otherwise the
+ stream is active. A <code><a>MediaStream</a></code> can start its life as
+ inactive if it is constructed without any tracks.</p>
+
+ <p>When a <code><a>MediaStream</a></code> goes from being active to
+ inactive, the user agent MUST queue a task that sets the object's
+ <code><a href="#dom-mediastream-inactive">inactive</a></code> attribute
+ to <code>true</code> and fire a simple event named <code><a href=
+ "#event-mediastream-inactive">inactive</a></code> at the object. When a
+ <code><a>MediaStream</a></code> goes from being inactive to active, the
+ user agent MUST queue a task that sets the object's <code><a href=
+ "#dom-mediastream-inactive">inactive</a></code> attribute to
+ <code>false</code> and fire a simple event named <code><a href=
+ "#event-mediastream-active">active</a></code> at the object.</p>
- <li>
- <p>Fire a simple event named <code title=
- "event-MediaStream-ended"><a href=
- "#event-mediastream-ended">ended</a></code> at the object.</p>
- </li>
- </ol>
-
- <p>If the end of the stream was reached due to a user request, the task
+ <p>If the stream's activity status changed due to a user request, the task
source for this <span title="concept-task">task</span> is the user
interaction task source. Otherwise the task source for this <span title=
"concept-task">task</span> is the networking task source.</p>
- <!-- The "<>" in sequence<MediaStreamTrack> breaks rendering if added
- directly to the constructor declaration -->
- <dl class="idl" title="typedef sequence<MediaStreamTrack> MediaStreamTrackSequence"></dl>
-
<dl class="idl"
- title="[Constructor,
- Constructor (MediaStream stream),
- Constructor (MediaStreamTrackSequence tracks)]
- interface MediaStream : EventTarget">
- <dt>readonly attribute DOMString id</dt>
+ title="interface MediaStream : EventTarget">
+ <dt>Constructor()</dt>
+ <dd>See the <a href="#mediastream-constructor">MediaStream constructor algorithm</a></dd>
+ <dt>Constructor(MediaStream stream)</dt>
+ <dd>See the <a href="#mediastream-constructor">MediaStream constructor algorithm</a></dd>
+ <dt>Constructor(sequence<MediaStreamTrack> tracks)</dt>
+ <dd>See the <a href="#mediastream-constructor">MediaStream constructor algorithm</a></dd>
+ <dt>readonly attribute DOMString id</dt>
<dd>
<p>When a <code><a>MediaStream</a></code> object is created, the
@@ -640,30 +615,33 @@
</ol>
</dd>
- <dt>readonly attribute boolean ended</dt>
+ <dt>readonly attribute boolean inactive</dt>
<dd>
<p>The <dfn id=
- "dom-mediastream-ended"><code>MediaStream.ended</code></dfn>
- attribute MUST return true if the <code><a>MediaStream</a></code> has
- <a>finished</a>, and false otherwise.</p>
+ "dom-mediastream-inactive"><code>MediaStream.inactive</code></dfn>
+ attribute returns true if the <code><a>MediaStream</a></code> is
+ <a href="#stream-inactive">inactive</a>, and false otherwise.</p>
<p>When a <code><a>MediaStream</a></code> object is created, its
- <code><a href="#dom-mediastream-ended">ended</a></code> attribute
- MUST be set to false, unless it is being created using the
- <code><a href="#dom-mediastream">MediaStream()</a></code> constructor
- whose arguments are lists of <code><a>MediaStreamTrack</a></code>
- objects that are all <a>ended</a>, in which case the
- <code><a>MediaStream</a></code> object MUST be created with its
- <code><a href="#dom-mediastream-ended">ended</a></code> attribute set
- to true.</p>
+ <code><a href="#dom-mediastream-inactive">inactive</a></code>
+ attribute MUST be set to false, unless stated otherwise (for example
+ by the <code><a href="#dom-mediastream">MediaStream()</a></code>
+ constructor algorithm).</p>
</dd>
- <dt>attribute EventHandler onended</dt>
+ <dt>attribute EventHandler onactive</dt>
<dd>This event handler, of type <code><a href=
- "#event-mediastream-ended">ended</a></code>, MUST be supported by all
- objects implementing the <code><a>MediaStream</a></code>
+ "#event-mediastream-active">active</a></code>, MUST be supported by
+ all objects implementing the <code><a>MediaStream</a></code>
+ interface.</dd>
+
+ <dt>attribute EventHandler oninactive</dt>
+
+ <dd>This event handler, of type <code><a href=
+ "#event-mediastream-inactive">inactive</a></code>, MUST be supported by
+ all objects implementing the <code><a>MediaStream</a></code>
interface.</dd>
<dt>attribute EventHandler onaddtrack</dt>
@@ -700,17 +678,24 @@
<h3>Life-cycle and Media Flow</h3>
<p>A <code><a>MediaStreamTrack</a></code> has three stages in its
- lifecycle. A track begins as <code>new</code> prior to being connected to
- an active source.</p>
+ lifecycle; <code>new</code>, <code>live</code> and <code>ended</code>.
+ A track begins as <code>new</code> prior to being connected to an
+ active source.</p>
- <p>Once connected, the <code>started</code> event fires and the track
+ <p>Once connected, the <code><a href="#event-mediastreamtrack-started"
+ >started</a></code> event fires and the track
becomes <code>live</code>. In the <code>live</code> state, the track is
active and media is available for rendering at a <code>
<a>MediaStream</a></code> <a>consumer</a>.</p>
<p>A muted or disabled <code><a>MediaStreamTrack</a></code> renders either
silence (audio), black frames (video), or a zero-information-content
- equivalent. The muted/unmuted state of a track reflects if the source
+ equivalent. For example, a video element sourced by a muted or disabled
+ <code><a>MediaStreamTrack</a></code> (contained within a
+ <code><a>MediaStream</a></code>), is playing but the rendered content
+ is the muted output.
+
+ <p>The muted/unmuted state of a track reflects if the source
provides any media at this moment. The enabled/disabled state is under
application control and determines if the track outputs media (to its
consumers). Hence, media from the source only flows when a <code>
@@ -749,7 +734,7 @@
end has been reached and the user has not requested that it be looped, or
because the UA has instructed the track to end for any reason, or because
the reference count of the track's underlying media source has reached
- zero), it is said to be <dfn>ended</dfn>. When track instance
+ zero), it is said to be <dfn id="track-ended">ended</dfn>. When track instance
<var>track</var> ends for any reason other than the <code><a href=
"#dom-mediastreamtrack-stop">stop()</a></code> method being invoked on the
<code><a>MediaStreamTrack</a></code> object that represents
@@ -760,7 +745,10 @@
<li>
<p>If the track's <code><a href=
"#dom-mediastreamtrack-readystate">readyState</a></code> attribute
- has the value <code>ended</code> already, then abort these steps.</p>
+ has the value <code>ended</code> already, then abort these steps.
+ (The <code><a href="#dom-mediastreamtrack-stop">stop()</a></code>
+ method was probably called just before the track stopped for other
+ reasons.)</p>
</li>
<li>
@@ -808,7 +796,7 @@
<p>When track constraints change, a user agent <em title="must"
class="rfc2119">must</em> queue a task to evaluate those changes
when the task queue is next serviced. Similarly, if
- the <a class="internalDFN" href="#dfn-sourcetype">sourceType</a>
+ the <a href="#widl-MediaSourceStates-sourceType"><code>sourceType</code></a>
changes, then the user agent should perform the same actions to
re-evaluate the constraints of each track affected by that
source change.</p>
@@ -912,8 +900,8 @@
<dd>
If the track (audio or video) is backed by a read-only
source such as a file, or the track source is a local
- microphone or camera, but is shared so that this track
- cannot modify any of the source's settings, the <dfn id=
+ microphone or camera, but is shared so that constraints applied to
+ the track cannot modify the source's state, the <dfn id=
"dom-mediastreamtrack-readonly"><code>readonly</code></dfn>
attribute MUST return the value <code>true</code>.
Otherwise, it must return the value <code>false</code>.
@@ -952,10 +940,12 @@
all objects implementing the <code><a>MediaStreamTrack</a></code>
interface.</dd>
- <dt>static sequence<SourceInfo> getSourceInfos()</dt>
+ <dt>static void getSources(SourceInfoCallback resultCallback)</dt>
<dd>
- Returns authorized information for all available sources.
+ <p>The static <dfn id="dom-mediastreamtrack-getsources">
+ <code>getSources()</code></dfn> method collects authorized
+ information for all available sources.</p>
</dd>
<dt>MediaTrackConstraints? constraints()</dt>
@@ -995,8 +985,7 @@
translate and scale the hardware's setting onto the mapping
provided by this specification. If this is not possible due
to the user agent's inability to retrieve a given
- capability from a source, then for <a class="idlType"
- href="#idl-def-CapabilityRange"><code>CapabilityRange</code></a>-typed
+ capability from a source, then for <a><code>CapabilityRange</code></a>-typed
capabilities, the <code>min</code> and <code>max</code>
fields will not be present on the returned dictionary, and
the <code>supported</code> field will
@@ -1016,13 +1005,12 @@
0 should map to "medium". Constraints imposing a strict
value of 3 will cause the user agent to attempt to set the
value of "medium" on the hardware, and return a
- fluxCapacitance <a class="internalDFN"
- href="#dfn-state">state</a> of 0, the closest supported
+ fluxCapacitance <a>state</a> of 0, the closest supported
setting. No error event is raised in this
scenario.</p>
</div>
- <p><code><a>CapabilityList</code></a> objects should order their enumerated
+ <p><code><a>CapabilityList</a></code> objects should order their enumerated
values from minimum to maximum where it makes sense, or in
the order defined by the enumerated type where
applicable.</p>
@@ -1097,10 +1085,7 @@
<p>When a <code><a>MediaStreamTrack</a></code>
object's <dfn id=
"dom-mediastreamtrack-stop"><code>stop()</code></dfn> method
- is invoked, if no source is attached
- (e.g., <code><a>sourceType</a></code> is "none"), then this
- call returns immediately (e.g., is a no-op). Otherwise, the
- user agent MUST queue a task that runs the following steps:</p>
+ is invoked, the user agent MUST run following steps:</p>
<ol>
<li>
@@ -1109,8 +1094,16 @@
</li>
<li>
- <p><a title="ended">End</a> <var>track</var>. The track starts
- outputting only silence and/or blackness, as appropriate.</p>
+ <p>If <var>track</var> has no source attached
+ (<code><a>sourceType</a></code> is "none") or if the source is
+ provided by an <code>RTCPeerConnection</code>, then abort these
[612 lines skipped]
--- /sources/public/2011/webrtc/editor/getusermedia.js 2013/08/24 14:10:53 1.15
+++ /sources/public/2011/webrtc/editor/getusermedia.js 2013/10/17 11:17:27 1.16
@@ -19,7 +19,7 @@
// copyrightStart: "2005",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD
- prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20130704/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20130824/getusermedia.html",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "http://dev.w3.org/2011/webrtc/editor/getusermedia.html",
@@ -66,5 +66,27 @@
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
- wgPatentURI: ["http://www.w3.org/2004/01/pp-impl/47318/status","http://www.w3.org/2004/01/pp-impl/43696/status"]
+ wgPatentURI: ["http://www.w3.org/2004/01/pp-impl/47318/status","http://www.w3.org/2004/01/pp-impl/43696/status"],
+
+ localBiblio: {
+ "mediastream-rec": {
+ title: "MediaStream Recording",
+ href: "https://dvcs.w3.org/hg/dap/raw-file/tip/media-stream-capture/MediaRecorder.html",
+ authors: [
+ "Jim Barnett",
+ "Travis Leithead"
+ ],
+ status: "WD",
+ publisher: "W3C"
+ },
+ "mediastream-imagecap": {
+ title: "MediaStream Image Capture",
+ href: "http://www.w3.org/TR/image-capture/",
+ authors: [
+ "Giridhar Mandyam"
+ ],
+ status: "WD",
+ publisher: "W3C"
+ }
+ }
};
Received on Thursday, 17 October 2013 11:17:29 UTC