- From: CVS User dburnett <cvsmail@w3.org>
- Date: Thu, 26 Dec 2013 03:19:20 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor/sources
In directory roscoe:/tmp/cvs-serv14100/sources
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20131225 archived version.
--- /sources/public/2011/webrtc/editor/sources/getusermedia.html 2013/11/05 18:10:45 1.1
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.html 2013/12/26 03:19:20 1.2
@@ -378,8 +378,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-inactive">inactive</a></code> attribute to
- <code>true</code>, otherwise set it to <code>false</code>.</p>
+ "#dom-mediastream-active">active</a></code> attribute to
+ <code>false</code>, otherwise set it to <code>true</code>.</p>
</li>
<li>
@@ -422,13 +422,13 @@
<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=
+ <code><a href="#dom-mediastream-active">active</a></code> attribute
+ to <code>false</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=
+ "#dom-mediastream-active">active</a></code> attribute to
+ <code>true</code> and fire a simple event named <code><a href=
"#event-mediastream-active">active</a></code> at the object.</p>
<p>If the stream's activity status changed due to a user request, the task
@@ -610,17 +610,18 @@
</ol>
</dd>
- <dt>readonly attribute boolean inactive</dt>
+ <dt>readonly attribute boolean active</dt>
<dd>
<p>The <dfn id=
- "dom-mediastream-inactive"><code>MediaStream.inactive</code></dfn>
+ "dom-mediastream-active"><code>MediaStream.active</code></dfn>
attribute returns true if the <code><a>MediaStream</a></code> is
- <a href="#stream-inactive">inactive</a>, and false otherwise.</p>
+ active (see <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-inactive">inactive</a></code>
- attribute MUST be set to false, unless stated otherwise (for example
+ <code><a href="#dom-mediastream-active">active</a></code>
+ attribute MUST be set to true, unless stated otherwise (for example
by the <code><a href="#dom-mediastream">MediaStream()</a></code>
constructor algorithm).</p>
</dd>
@@ -665,9 +666,18 @@
<code><a href="#dom-navigator-getusermedia">getUserMedia()</a></code>
.</p>
- <p>Note that a web application can revoke all given permissions
- with <code><a href=
- "#dom-mediastreamtrack-stop">MediaStreamTrack.stop()</a></code>.</p>
+ <p>A script can indicate that a track no longer needs its source with the
+ <code><a href=
+ "#dom-mediastreamtrack-stop">MediaStreamTrack.stop()</a></code> method.
+ When all tracks using a source have been stopped, the given permission
+ for that source is revoked and the source is <dfn id=
+ "source-stopped">stopped</dfn>. If the data is being generated from a
+ live source (e.g., a microphone or camera), then the user agent SHOULD
+ remove any active "on-air" indicator for that source. If the data is being
+ generated from a prerecorded source (e.g. a video file), any remaining
+ content in the file is ignored. An implementation may use a per source
+ reference count to keep track of source usage, but the specifics are out
+ of scope for this specification.</p>
<section>
<h3>Life-cycle and Media Flow</h3>
@@ -727,9 +737,8 @@
(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 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 id="track-ended">ended</dfn>. When track instance
+ because the UA has instructed the track to end for any reason, 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
@@ -1002,17 +1011,11 @@
</li>
<li>
- <p>Permanently stop the generation of data for <var>track</var>'s
- source. If the data is being generated from a live source (e.g.,
- a microphone or camera), then the user agent SHOULD remove any
- active "on-air" indicator for that source. If the data is being
- generated from a prerecorded source (e.g. a video file), any
- remaining content in the file is ignored.</p>
-
- <p class="note">This will effectively
- <a href="#track-ended">end</a> all other
- <code><a>MediaStreamTrack</a></code> objects sharing the same
- source as <var>track</var>.</p>
+ <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>
</ol>
@@ -1401,7 +1404,7 @@
<p>It is possible that <a>constraints</a> can be applied to a track
which a source is unable to satisfy. When this happens, the user
- agent is required to fire an <a>overconstrained</a> event to the
+ agent is required to fire an <a>overconstrained</a> MediaErrorEvent to the
track informing it of this condition, and the track becomes
muted. There is no mandatory side-effect on the source itself as
a result of this condition.</p>
@@ -1412,7 +1415,7 @@
there is only a single thread of control, it is always possible
for the browser to determine which track created the
overconstrained condition. In this situation, the user agent
- MUST send the <a>overconstrained</a> event only to the track that
+ MUST send the <a>overconstrained</a> MediaErrorEvent only to the track that
created the condition and MUST not apply any of the constraints
newly requested for that track. Here is an example of this
behavior.</p>
@@ -1918,7 +1921,63 @@
</table>
</section>
</section>
+<section>
+ <h2>Error Handling</h2>
+ <p>All errors defined in this specification implement the following
+ interface:</p>
+
+ <dl class="idl" title=
+ "[NoInterfaceObject] interface MediaError">
+ <dt>readonly attribute DOMString name</dt>
+ <dd><p>The name of the error</p></dd>
+ <dt>readonly attribute DOMString? message</dt>
+ <dd>A UA-dependent string offering extra human-readable information about
+ the error.</dd>
+ <dt>readonly attribute DOMString? constraintName</dt>
+
+ <dd>
+ <p>This attribute is only used for some types of errors. For <code>
+ <a>MediaError</a></code> with a name of
+ <code>ConstraintNotSatisfiedError</code>, this attribute MUST be set
+ to the name of the constraint that caused the error.</p>
+ </dd>
+
+ </dl>
+<div class="note">Open Issue: We may make MediaError inherit from DOMError
+ once the definition of DOMError is stable.</div>
+
+ <div class="note">Open Issue: Do we want to allow the constraintName attribute to
+ contain multiple constraint names? In many cases the error is raised as soon
+ as a single unsatisfied mandatory constraint is found, but in others it may
+ be possible to determine that multiple constraints are not satisfied.</div>
+
+<p> The following interface is defined for cases when a MediaError is raised
+as an event:</p>
+
+
+
+ <dl class="idl" data-merge="MediaErrorEventInit" title=
+ "interface MediaErrorEvent : Event">
+ <dt>Constructor(DOMString type, MediaErrorEventInit eventInitDict)</dt>
+ <dd></dd>
+ <dt>readonly attribute MediaError error</dt>
+
+ <dd>
+
+ </dd>
+ </dl>
+
+ <dl class="idl" title="dictionary MediaErrorEventInit : EventInit">
+ <dt>MediaError error</dt>
+
+ <dd>
+ <p> </p>
+ </dd>
+ </dl>
+
+
+ </section>
<section class="informative">
<h2>Event summary</h2>
@@ -2077,11 +2136,11 @@
</td>
<td>
- <code>Event</code>
+ <code>MediaErrorEvent</code>
</td>
<td>
- <p>This event fires asynchronously for each affected
+ <p>This error event fires asynchronously for each affected
track (when multiple tracks share the same source) after
the user agent has evaluated the current constraints
against a given <code><a>sourceId</a></code> and is not
@@ -2094,11 +2153,7 @@
the <code>"muted"</code> <a>readyState</a>) until the
application adjusts the constraints to accommodate the
source's capabilities.</p>
- <p>The "overconstrained" event is a simple event of
- type <code>Event</code>; it carries no information about
- which constraints caused the source to be
- over-constrained (the application has all the necessary
- APIs to figure it out).</p>
+
</td>
</tr>
@@ -2179,7 +2234,7 @@
<li>
<p>If <var>device</var> is represented by a
<code><a>MediaDeviceInfo</a></code> object in
- <var>oldList</var>, move that object to
+ <var>oldList</var>, append that object to
<var>resultList</var>, abort these steps and continue with
the next device (if any).</p>
</li>
@@ -2357,7 +2412,7 @@
<li>
<p>If <var>requestedMediaTypes</var> is the empty set, let
<var>error</var> be a new
- <code><a>NavigatorUserMediaError</a></code> object whose
+ <code><a>MediaError</a></code> object whose
<code><a>name</a></code> attribute has the value
<code>NotSupportedError</code> and jump to the step labeled
<em>Error Task</em> below.</p>
@@ -2491,14 +2546,8 @@
media type in requestedMediaTypes from the <var>finalSet</var>.
The decision of which tracks to choose from the
<var>finalSet</var> is completely up to the user agent and may be
- determined by asking the user. Unless and until a new set of
- constraints is provided, the user agent MAY change its choice of
- track at any point, provided that 1) the new choice does not
- violate given user permissions, and 2) it notifies the
- application code by raising an event. It may wish to do this, for
- example, if the user interface or network congestion changes. Note
- that no such change will have an effect on the presence or absence
- of each type of track, merely the contents.</p>
+ determined by asking the user. Once selected, the source of a
+ <code><a>MediaStreamTrack</a></code> MUST not change.</p>
<p class="issue">Define the event that should be raised when the
user agent changes its choice of track.</p>
@@ -2536,7 +2585,7 @@
<li>
<p><em>Permission Failure</em>: Let <var>error</var> be a new
- <code><a>NavigatorUserMediaError</a></code> object whose
+ <code><a>MediaError</a></code> object whose
<code><a>name</a></code> attribute has the value
<code>PermissionDeniedError</code> and jump to the step
labeled <em>Error Task</em> below.</p>
@@ -2544,10 +2593,10 @@
<li>
<p><em>Constraint Failure</em>: Let <var>error</var> be a new
- <code><a>NavigatorUserMediaError</a></code> object whose
+ <code><a>MediaError</a></code> object whose
<code><a>name</a></code> attribute has the value
<code>ConstraintNotSatisfiedError</code> and whose
- <code><a href="#widl-NavigatorUserMediaError-constraintName"
+ <code><a href="#widl-MediaError-constraintName"
>constraintName</a></code> attribute is set to the name of the
constraint that caused the error.</p>
</li>
@@ -2621,36 +2670,14 @@
</section>
<section>
- <h2>NavigatorUserMediaError and NavigatorUserMediaErrorCallback</h2>
-
- <dl class="idl" title=
- "[NoInterfaceObject] interface NavigatorUserMediaError : DOMError">
-
- <dt>readonly attribute DOMString? constraintName</dt>
-
- <dd>
- <p>This attribute is only used for some types of errors. For <code>
- <a>NavigatorUserMediaError</a></code> with a name of
- <code>ConstraintNotSatisfiedError</code>, this attribute MUST be set
- to the name of the constraint that caused the error.</p>
- </dd>
-
- </dl>
-
- <div class="note">
- <p>Ask the DOM team to extend their list with the following errors.</p>
+ <h2>NavigatorUserMediaErrorCallback</h2>
- <ul>
- <li>PermissionDeniedError: User denied permission for scripts from
- this origin to access the media device.</li>
+
- <li>ConstraintNotSatisfiedError: One of the mandatory constraints
- could not be satisfied.</li>
- </ul>
- </div>
+
<dl class="idl" title="callback NavigatorUserMediaErrorCallback = void">
- <dt>NavigatorUserMediaError error</dt>
+ <dt>MediaError error</dt>
<dd><p class="issue">Add explanation of handleEvent</p></dd>
</dl>
@@ -2847,6 +2874,17 @@
the <code>optional</code> field will not be present (it will be
undefined). If neither optional nor mandatory constraints have been
created, the value will be <code>null</code>.</p>
+
+ <p>The UA MUST raise a <code>MediaErrorEvent</code> named "overconstrained" if changing circumstances at runtime
+ result in the currently valid mandatory constraints no longer being satisfied. This MediaErrorEvent
+ MUST contain a MediaError whose <code>name</code> is "overconstrainedError", and whose
+ <code>constraintName</code> attribute is set to one of the mandatory constraints that
+ can no longer be satisifed. The <code>message</code> attribute of the MediaError
+ SHOULD contain a string that is useful for debugging.
+ The conditions under which this error might occur are platform- and application-specific.
+ For example, the user might physically manipulate a camera in a way that
+ makes it impossible to provide a resolution that satisifies the constraints.
+ The UA MAY take other actions as a result of the overconstrained situation.</p>
</dd>
@@ -2863,12 +2901,7 @@
<dd>This event handler, of type <code><a href=
"#event-constrainable-overconstrained">overconstrained</a></code>, MUST
be supported by all objects implementing the <code>
- <a>Constrainable</a></code> interface. The UA MUST raise the
- <code>overconstrained</code> event if changing circumstances at runtime
- result in the currently valid mandatory constraints no longer being satisfied.
- The conditions under which this might happen are platform- and application-specific.
- For example, the user might physically manipulate a camera in a way that
- made it impossible to provide a resolution that satisified the constraints.
+ <a>Constrainable</a></code> interface.
</dd>
@@ -2920,7 +2953,8 @@
as if it were <var>object</var> with all constraints removed.) </li>
<li>If the mandatory constraints in <var>desiredConstraints</var> is
cannot be satisifed by <var>copy</var>, call the <code>errorCallback</code>, passing
- it a list of the mandatory constraints that could not be
+ it a new <code>MediaError</code> with name <code>ConstraintNotSatisfied</code>
+ and <code>constraintName</code> set to the mandatory constraints that could not be
satisfied, and return. (Note that there may be more than one way of selecting
the set of constraints that were not satisfied.) <code>existingConstraints</code> remain
in effect on <var>object</var> in this case.
@@ -2950,24 +2984,13 @@
<h3>applyConstraints Failure Callback</h3>
<section>
- <section>
- <h4>ConstraintError</h4>
- <dl class="idl" title="[NoInterfaceObject] interface ConstraintError">
-
- <dt>readonly attribute Constraints constraintNames</dt>
- <dd>Contains the set of mandatory constraints that could not
- be satisified. The <code>optional</code> field in this
- object will be undefined.</dd>
-
- </dl>
- </section>
<section>
<h4>ConstraintErrorCallback</h4>
<dl class="idl" title="callback ConstraintErrorCallback = void">
- <dt>ConstraintError error</dt>
+ <dt>MediaError error</dt>
- <dd>An object holding the mandatory constraints that could not be satisfied.</dd>
+ <dd>An <code>MediaError</code> holding the mandatory constraint that could not be satisfied.</dd>
</dl>
</section>
@@ -3272,6 +3295,24 @@
</pre>
</div>
</section>
+
+ <section>
+ <h1>Error Names</h1>
+ <p>This specification defines the following new error names
+</p>
+ <ul>
+ <li>PermissionDeniedError: User denied permission for scripts from
+ this origin to access the media device.</li>
[70 lines skipped]
--- /sources/public/2011/webrtc/editor/sources/getusermedia.js 2013/11/05 18:10:45 1.1
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.js 2013/12/26 03:19:20 1.2
@@ -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/20131017/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20131105/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, 26 December 2013 03:19:23 UTC