- From: CVS User dburnett <cvsmail@w3.org>
- Date: Thu, 08 May 2014 02:05:54 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor/sources
In directory roscoe:/tmp/cvs-serv11542/sources
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20140507 archived version.
--- /sources/public/2011/webrtc/editor/sources/getusermedia.html 2014/02/19 02:04:14 1.3
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.html 2014/05/08 02:05:54 1.4
@@ -181,6 +181,31 @@
<p>A conforming user-agent <em title="must" class="rfc2119">must</em>
support all the setting names defined in this spec.</p>
+
+ <p>As represented in this specification, a source is the
+ realization of a device as presented by the User Agent. Thus,
+ it is possible that the actual settings of the device may
+ differ from those presented by the User Agent. As an example,
+ there are some operating systems and native device APIs that
+ will treat a camera with a single native capture resolution as
+ if it can produce any resolution less than that value,
+ downsampling as necessary. Even though the camera technically
+ has only one specific width and one specific height it can
+ support, it is likely that the User Agent will represent this
+ camera as a source with a range of supported widths and
+ heights. To enable the application to determine when this has
+ occurred, tracks provide both
+ a <code><a>getSettings()</a></code> method (which always
+ returns a setting that satisfies the constraints applied to
+ the track) and a <code><a>getNativeSettings()</a></code>
+ method (which always returns, to the best of the User Agent's
+ determination, the actual setting of the native device). Note
+ that both the track settings and the native settings are
+ snapshots and can change without application involvement. In
+ particular, changes in the native settings could cause changes
+ in the track settings that would result in the latter values
+ being outside of the constraints and thus causing
+ overconstrained events for all affected tracks.</p>
</dd>
@@ -288,6 +313,15 @@
not need to be synchronized.</p>
+ <p class="note">While the intent is to synchronize tracks, it could be
+ better in some circumstances to permit tracks to lose synchronization.In
+ particular, when tracks are remotely sourced and real-time [[!WEBRTC10]],
+ it can be better to allow loss of synchronization than to accumulate
+ delays or risk glitches and other artifacts. Implementations are expected
+ to understand the implications of choices regarding synchronization of
+ playback and the effect that these have on user perception.</p>
+
+
<p>Each track in a MediaStream object has a corresponding
<code><a>MediaStreamTrack</a></code> object.</p>
@@ -410,13 +444,6 @@
<li>
- <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>
<p>Add <var>track</var> to <var>stream</var>'s <a href=
"#track-set">track set</a>.</p>
</li>
@@ -438,8 +465,8 @@
<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-active">active</a></code> attribute to
+ empty or only contains ended tracks, set <var>stream</var>'s
+ <code><a href="#dom-mediastream-active">active</a></code> attribute to
<code>false</code>, otherwise set it to <code>true</code>.</p>
</li>
@@ -635,12 +662,6 @@
<li>
- <p>If <var>stream</var> is <a>finished</a>, throw an
- <code>INVALID_STATE_ERR</code> exception.</p>
- </li>
-
-
- <li>
<p>If <var>track</var> is already in <var>stream's</var> <a href=
"#track-set">track set</a>, then abort these steps.</p>
</li>
@@ -664,29 +685,9 @@
<p>When the <dfn id=
"dom-mediastream-removetrack"><code>removeTrack()</code></dfn> method
- is invoked, the user agent MUST run the following steps:</p>
-
-
- <ol>
- <li>
- <p>Let <var>track</var> be the
- <code><a>MediaStreamTrack</a></code> argument and
- <var>stream</var> this <code><a>MediaStream</a></code>
- object.</p>
- </li>
-
-
- <li>
- <p>If <var>stream</var> is <a>finished</a>, throw an
- <code>INVALID_STATE_ERR</code> exception.</p>
- </li>
-
-
- <li>
- <p>If <var>track</var> is in <var>stream</var>'s <a href=
- "#track-set">track set</a>, remove it.</p>
- </li>
- </ol>
+ is invoked, the user agent MUST remove the track, indicated by the
+ method's argument, from the stream's <a href="#track-set">track
+ set</a>, if present.</p>
</dd>
@@ -855,11 +856,7 @@
action is outside the control of the application. This could be as a
result of the user hitting a hardware switch, or toggling a control in
the operating system or browser chrome. A track can also be muted by
- the user agent. For example, a track that is a member of a
- <code><a>MediaStream</a></code>, received via a
- <code><a>RTCPeerConnection</a></code> [[!WEBRTC10]], is muted if the
- application on the other side disables the corresponding track in the
- <code>MediaStream</code> being sent.</p>
+ the user agent.</p>
<p>Applications are able to <dfn id="track-enabled">enable</dfn> or
@@ -911,6 +908,14 @@
to <code>ended</code>.</p>
</li>
+ <li>
+ <p>Detach <var>track's</var> source.</p>
+
+
+ <p>If no other <code><a>MediaStreamTrack</a></code> is using
+ the same source, the source will be <a href=
+ "#source-stopped">stopped</a>.</p>
+ </li>
<li>
<p>Fire a simple event named <code><a href=
@@ -929,11 +934,7 @@
<h3>Tracks and Constraints</h3>
- <p>Constraints are set on a per-track basis rather than on the
- source itself. However, if the
- <code><a>sourceType</a></code> is "none" or the
- <code><a>remote</a></code> attribute is <code>true</code>, the track's
- constraints will not be applied to the source.</p>
+ <p>Constraints are set on tracks and may affect sources.</p>
<p>Whether <code><a>Constraints</a></code> were provided at track
@@ -961,19 +962,18 @@
re-evaluate the constraints of each track affected by that source
change.</p>
- <p>If the <code><a>MediaError</a></code> event named
+ <p>If the <code><a>MediaStreamError</a></code> event named
'overconstrained' is thrown, the track MUST be muted until
either new satisfiable constraints are applied or the existing
constraints become satisfiable.</p>
</section>
- <section>
+ <section id="media-stream-track-interface-definition">
<h3>Interface Definition</h3>
- <div class="idl" title="MediaStreamTrack implements Constrainable">
- </div>
+
<dl class="idl" title="interface MediaStreamTrack : EventTarget">
@@ -1091,7 +1091,7 @@
<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 constraints applied to the track cannot modify
- the source's state, the <dfn id=
+ the source's settings, 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>.</dd>
@@ -1135,6 +1135,24 @@
interface.</dd>
+ <dt>Settings getNativeSettings()</dt>
+
+
+ <dd>The <dfn>getNativeSettings()</dfn> method returns the
+ native settings of all the properties of the object. Note
+ that the actual setting of a property <em title="must"
+ class="rfc2119">must</em> be a single value. Unlike the
+ return value from the <code><a>getSettings()</a></code>
+ method, this return object a) MUST reflect, to the best of
+ the User Agent's ability, the actual native settings of the
+ source device, b) MAY have values that do not match the
+ current composite set of constraints applied by all tracks
+ associated with this source, only to the extent necessary to
+ reflect the native settings of the source device, and c)
+ MUST be the same for all tracks associated with this same
+ source.</dd>
+
+
<dt>MediaStreamTrack clone()</dt>
@@ -1165,7 +1183,8 @@
<p>Let <var>trackClone</var> inherit this track's underlying
source, <code><a href=
"#dom-mediastreamtrack-kind">kind</a></code>, <code><a href=
- "#dom-mediastreamtrack-label">label</a></code> and
+ "#dom-mediastreamtrack-label">label</a></code>, <code><a href=
+ "#dom-mediastreamtrack-readystate">readyState</a></code>, and
<code><a href=
"#dom-mediastreamtrack-enabled">enabled</a></code>
attributes, as well as its currently active constraints.</p>
@@ -1226,6 +1245,53 @@
"#dom-mediastreamtrack-stop">stop()</a></code> method is the DOM
manipulation task source.</p>
</dd>
+
+ <dt>Capabilities getCapabilities()</dt>
+
+
+ <dd>
+ <p>See <a href="#constraintable-interface">Constrainable Interface</a>
+ for the definition of this method.</p>
+ </dd>
+
+
+ <dt>MediaTrackConstraints getConstraints()</dt>
+
+
+ <dd>See <a href="#constraintable-interface">Constrainable Interface</a>
+ for the definition of this method.
+ </dd>
+
+
+ <dt>Settings getSettings()</dt>
+
+
+ <dd>See <a href="#constraintable-interface">Constrainable Interface</a>
+ for the definition of this method.
+</dd>
+ <dt>void applyConstraints()</dt>
+ <dd>
+ <dl class="parameters">
+ <dt>MediaTrackConstraints constraints</dt>
+
+
+ <dd>A new constraint structure to apply to this object.</dd>
+
+
+ <dt>VoidFunction successCallback</dt>
+
+
+ <dd>Called if the required constraints can be satisfied.</dd>
+
+
+ <dt>ConstraintErrorCallback errorCallback</dt>
+
+
+ <dd>Called if the required constraints cannot be satisfied.</dd>
+ </dl>
+ See <a href="#constraintable-interface">Constrainable Interface</a>
+ for the definition of this method.</dd>
+ <dd>
</dl>
@@ -1286,20 +1352,44 @@
<dt>camera</dt>
- <dd>A valid source type only for
- <code><a>VideoStreamTrack</a></code>s. The source is a local
+ <dd>A valid source type only for video
+ <code><a>MediaStreamTrack</a></code>s. The source is a local
video-producing camera source.</dd>
<dt>microphone</dt>
- <dd>A valid source type only for
- <code><a>AudioStreamTrack</a></code>s. The source is a local
+ <dd>A valid source type only for audio
+ <code><a>MediaStreamTrack</a></code>s. The source is a local
audio-producing microphone source.</dd>
</dl>
</section>
-
+<section id="media-track-constraints">
+ <h2>MediaTrackConstraints</h2>
+ <dl class="idl" title="dictionary MediaTrackConstraints : MediaTrackConstraintSet">
+ <dt>sequence<MediaTrackConstraintSet> advanced</dt>
+ <dd>See <a href="#constraints">Constraints and ConstraintSet</a> for
+ the definition of this element.</dd>
+ <dt>sequence<DOMString> require</dt>
+ <dd>See <a href="#constraints">Constraints and ConstraintSet</a> for
+ the definition of this element.</dd>
+ </dl>
+
+ <dl class="idl" title="dictionary MediaTrackConstraintSet">
+ <dt>ConstrainLong width</dt> <dd> </dd>
+ <dt>ConstrainLong height</dt> <dd> </dd>
+ <dt>ConstrainDouble aspectRatio</dt><dd> </dd>
+ <dt>ConstrainDouble frameRate</dt> <dd> </dd>
+ <dt>ConstrainVideoFacingMode facingMode</dt> <dd> </dd>
+ <dt>ConstrainDouble volume</dt> <dd> </dd>
+ <dt>ConstrainLong sampleRate</dt> <dd> </dd>
+ <dt>ConstrainLong sampleSize</dt><dd> </dd>
+ <dt>boolean echoCancelation</dt><dd> </dd>
+ <dt>ConstrainDOMString sourceId</dt> <dd> </dd>
+
+ </dl>
+ </section>
<section>
<h2>Isolated Media Streams</h2>
@@ -1403,112 +1493,10 @@
</dd>
</dl>
</section>
-
-
- <section>
- <h2>Video and Audio Tracks</h2>
-
-
- <p>The <code><a>MediaStreamTrack</a></code> object cannot be instantiated
- directly. To create an instance of a
- <code><a>MediaStreamTrack</a></code>, one of its derived track types may
- be instantiated. These derived types are defined in this section.</p>
-
-
- <p>Note that the camera's <q>green light</q> doesn't come on when a new
- track is created; nor does the user get prompted to enable the
- camera/microphone. Those actions only happen after the developer has
- requested that a media stream containing <code>"new"</code> tracks be
- bound to a source via <code><a>getUserMedia()</a></code>. Until that
- point tracks are inert.</p>
-
-
- <section>
- <h2>VideoStreamTrack interface</h2>
-
-
- <p>Video tracks may be instantiated with optional media track
- constraints. These constraints can be later modified on the track as
- needed by the application, or created after-the-fact if the initial
- constraints are unknown to the application.</p>
-
-
- <div class="note">
- <p><strong>Example:</strong> <code><a>VideoStreamTrack</a></code>
- objects are instantiated in JavaScript using the new operator:</p>
-
- <pre xml:space="preserve" class="example highlight">
-new VideoStreamTrack();
-</pre>or
-
- <pre xml:space="preserve" class="example highlight">
-new VideoStreamTrack({
- "optional": [{
- sourceId: "20983-20o198-109283-098-09812"
- }, {
- width: {
- min: 800,
- max: 1200
- }
- }, {
- height: {
- min: 600
- }
- }]
-});
-</pre>
- </div>
-
-
- <dl class="idl" title="interface VideoStreamTrack : MediaStreamTrack">
- <dt>Constructor(optional Constraints videoConstraints)</dt>
-
-
- <dd>
- <p>TODO</p>
[1244 lines skipped]
--- /sources/public/2011/webrtc/editor/sources/getusermedia.js 2014/02/19 02:04:15 1.3
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.js 2014/05/08 02:05:54 1.4
@@ -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/20131225/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20140321/getusermedia.html",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "http://dev.w3.org/2011/webrtc/editor/getusermedia.html",
Received on Thursday, 8 May 2014 02:05:56 UTC