- From: CVS User dburnett <cvsmail@w3.org>
- Date: Wed, 20 Mar 2013 17:29:41 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv13986
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20130320 getusermedia archived version.
--- /sources/public/2011/webrtc/editor/getusermedia.html 2012/12/12 13:38:41 1.15
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2013/03/20 17:29:39 1.16
@@ -9,13 +9,8 @@
<title>Media Capture and Streams</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<!--
- After making changes to this document in the github repo, run:
- ./publish.sh getusermedia.html
- to publish a new editor's draft to the W3C CVS. This assumes your
- CVS checkout is located at ../2011/webrtc, you can specify the location
- as the second argument, for example:
- ./publish.sh getusermedia.html ~/path/to/w3/2011/webrtc
- -->
+ To publish this document, see instructions in README
+ -->
<script class="remove" src="http://www.w3.org/Tools/respec/respec-w3c-common"
type="text/javascript">
@@ -90,12 +85,88 @@
<dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
fires a simple event</a></dfn> are defined in [[!HTML5]].
</p>
+
<p>
The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
event handlers</a></dfn> and
<dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
event handler event types</a></dfn> are defined in [[!HTML5]].
</p>
+
+ <p class="note">The following paragraphs need to be spread out
+ to make them easier to read. Also, descriptions for "source
+ states" and "capabilities" need to be added.</p>
+
+ <p>A <dfn>source</dfn> is the "thing" providing the source of a
+ media stream track. The source is the broadcaster of the media
+ itself. A source can be a physical webcam, microphone, local
+ video or audio file from the user's hard drive, network
+ resource, or static image. Some sources have an identifier
+ which <em title="must" class="rfc2119">must</em> be unique to
+ the application (un-guessable by another application) and
+ persistent between application sessions (e.g., the identifier
+ for a given source device/application must stay the same, but
+ not be guessable by another application). Sources that must have
+ an identifier are camera and microphone sources; local file
+ sources are not required to have an identifier. Source
+ identifiers let the application save, identify the availability
+ of, and directly request specific sources. Other than the
+ identifier, other bits of source identify
+ are <strong>never</strong> directly available to the application
+ until the user agent connects a source to a track. Once a source
+ has been "released" to the application (either via a permissions
+ UI, pre-configured allow-list, or some other release mechanism)
+ the application will be able discover additional source-specific
+ capabilities. When a source is connected to a track, it must
+ conform to the constraints present on that track (or set of
+ tracks). Sources will be released (un-attached) from a track
+ when the track is ended for any reason. On
+ the <code><a>MediaStreamTrack</a></code> object, sources are
+ represented by a <code><a>sourceType</a></code> attribute. The
+ behavior of APIs associated with the source's capabilities and
+ state change depending on the source type. [[Sources
+ have <code><a>capabilities</a></code>
+ and <code><a>state</a></code>. The capabilities and state are
+ "owned" by the source and are common to any [multiple] tracks
+ that happen to be using the same source (e.g., if two different
+ tracks objects bound to the same source ask for the same
+ capability or state information, they will get back the same
+ answer).]]</p>
+ <p><dfn title="constraints"
+ id="dfn-constraints">Constraints</dfn> are an optional feature
+ for restricting the range of allowed variability on a
+ source. Without provided constraints, implementations are free
+ to select a source's state from the full range of its supported
+ capabilities, and to adjust that state at any time for any
+ reason. Constraints may be optional or mandatory. Optional
+ constraints are represented by an ordered list, mandatory
+ constraints are an unordered set. The order of the optional
+ constraints is from most important (at the head of the list) to
+ least important (at the tail of the list). Constraints are
+ stored on the track object, not the source. Each track can be
+ optionally initialized with constraints, or constraints can be
+ added afterward through the constraint APIs defined in this
+ spec. Applying track level constraints to a source is
+ conditional based on the type of source. For example, read-only
+ sources will ignore any specified constraints on the track. It
+ is possible for two tracks that share a unique source to apply
+ contradictory constraints. Under such contradictions, the
+ implementation will mute both tracks and notify them that they
+ are over-constrained. Events are available that allow the
+ application to know when constraints cannot be met by the user
+ agent. These typically occur when the application applies
+ constraints beyond the capability of a source, contradictory
+ constraints, or in some cases when a source cannot sustain
+ itself in over-constrained scenarios (overheating, etc.).
+ 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 will allow future
+ constraints to be defined in a backward compatible manner. A
+ correspondingly-named constraint exists for each corresponding
+ source state name and capability name. In general, user agents
+ will have more flexibility to optimize the media streaming
+ experience the fewer constraints are applied.</p>
</section>
<section id="stream-api">
@@ -130,7 +201,7 @@
<p>A <code><a>MediaStream</a></code> object has an input and an output.
The input depends on how the object was created: a
- <code><a>LocalMediaStream</a></code> object generated by a <code><a href=
+ <code><a>MediaStream</a></code> object generated by a <code><a href=
"#dom-navigator-getusermedia">getUserMedia()</a></code> call (which is
described later in this document), for instance, might take its input
from the user’s local camera. The output of the object controls how the
@@ -162,16 +233,13 @@
"40%"></p>
<p>The ability to duplicate a <code><a>MediaStream</a></code>,
- specifically create a new <code><a>MediaStream</a></code> object using an
- other stream as input, allows for greater control since separate
+ specifically creating a new <code><a>MediaStream</a></code>
+ object using another stream as input, allows for greater control
+ since separate
<code><a>MediaStream</a></code> instances can be manipulated and
<a title="consumer">consumed</a> individually.</p>
- <p>The <code><a>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).</p>
-
- <p>When a <code><a>LocalMediaStream</a></code> object is being generated
+ <p>When a <code><a>MediaStream</a></code> object is being generated
from a local file (as opposed to a live audio/video source), the user
agent SHOULD stream the data from the file in real time, not all at once.
The <code>MediaStream</code> object is also used in contexts outside
@@ -286,7 +354,7 @@
<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-mediastream-stop">stop()</a></code> method being
+ <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>
@@ -295,7 +363,7 @@
<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-mediastream-stop">stop()</a></code> method was probably called
+ "#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>
@@ -330,7 +398,7 @@
<dt>readonly attribute DOMString id</dt>
<dd>
- <p>When a <code><a>LocalMediaStream</a></code> object is created, the
+ <p>When a <code><a>MediaStream</a></code> object is created, the
user agent MUST generate a globally unique identifier string, and
MUST initialize the object’s <code><a href=
"#dom-mediastream-id">id</a></code> attribute to that string.
@@ -381,7 +449,7 @@
the order does not have to stable between calls.</p>
</dd>
- <dt>MediaStreamTrack getTrackById(DOMString trackId)</dt>
+ <dt>MediaStreamTrack? getTrackById(DOMString trackId)</dt>
<dd>
<p>The <dfn id=
@@ -509,74 +577,6 @@
</section>
<section>
- <h2>LocalMediaStream</h2>
-
- <p>Before the web application can access the user's media input devices
- it must let <code><a href=
- "#dom-navigator-getusermedia">getUserMedia()</a></code> create a
- <code><a>LocalMediaStream</a></code> . Once the application is done
- using, e.g., a webcam and a microphone, it may revoke its own access by
- calling <code><a href="#dom-mediastream-stop">stop()</a></code> on the
- <code><a>LocalMediaStream</a></code>.
- <!--If the web application no longer has access to any media input devices, any
- "on air" indicators in the browser UI MUST be turned off.--></p>
-
- <p>A web application may, once it has access to a
- <code><a>LocalMediaStream</a></code> , use the <code><a href=
- "#dom-mediastream">MediaStream()</a></code> constructor to construct
- additional <code><a>MediaStream</a></code> objects. Since a derived
- <code><a>MediaStream</a></code> object is created from the tracks of an
- existing stream, it cannot use any media input devices that have not been
- approved by the user.</p>
-
- <dl class="idl" title="interface LocalMediaStream : MediaStream">
- <dt>void stop()</dt>
-
- <dd>
- <p>When a <code><a>LocalMediaStream</a></code> object’s <dfn id=
- "dom-mediastream-stop"><code>stop()</code></dfn> method is invoked,
- the user agent MUST queue a task that runs the following steps on
- every track:</p>
-
- <ol>
- <li>
- <p>Let <var>track</var> be the current
- <code><a>MediaStreamTrack</a></code> object.</p>
- </li>
-
- <li>
- <p><a title="ended">End</a> <var>track</var>. The track starts
- outputting only silence and/or blackness, as appropriate.</p>
- </li>
-
- <li>
- <p>Dereference <var>track’s</var> underlying media source.</p>
- </li>
-
- <li>
- <p>If the reference count of <var>track’s</var> underlying media
- source is greater than zero, then abort these steps.</p>
- </li>
-
- <li>
- <p>Permanently stop the generation of data for <var>track’s</var>
- 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>
- </li>
- </ol>
-
- <p>The task source for the <span title="concept-task">tasks</span>
- queued for the <code><a href=
- "#dom-mediastream-stop">stop()</a></code> method is the DOM
- manipulation task source.</p>
- </dd>
- </dl>
- </section>
-
- <section>
<h2>MediaStreamTrack</h2>
<p>A <code><a>MediaStreamTrack</a></code> object represents a media
@@ -586,26 +586,9 @@
<code><a href="#dom-navigator-getusermedia">getUserMedia()</a></code>
.</p>
- <p>A <code><a>MediaStreamTrack</a></code> object can reference its media
- source in two ways, either with a strong or a weak reference, depending
- on how the track was created. For example, a track in a
- <code><a>MediaStream</a></code>, derived from a
- <code><a>LocalMediaStream</a></code> with the <code><a href=
- "#dom-mediastream">MediaStream()</a></code> constructor, has a weak
- reference to a local media source, while a track in a
- <code><a>LocalMediaStream</a></code> has a strong reference. This means
- that a track in a <code><a>MediaStream</a></code>, derived from a
- <code><a>LocalMediaStream</a></code>, will end if there is no
- non-<a>ended</a> track in a <code><a>LocalMediaStream</a></code> which
- references the same local media source.</p>
-
- <p class="note">The concept with strong and weak references to media
- sources allows the web application to derive new
- <code><a>MediaStream</a></code> objects from
- <code><a>LocalMediaStream</a></code> objects (created via <code><a href=
- "#dom-navigator-getusermedia">getUserMedia()</a></code>) and still be
- able to revoke all given permissions with <code><a href=
- "#dom-mediastream-stop">LocalMediaStream.stop()</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 <code><a>MediaStreamTrack</a></code> object is said to <em>end</em>
when the user agent learns that no more data will ever be forthcoming for
@@ -619,8 +602,8 @@
the reference count of the track’s underlying media source has reached
zero, it is said to be <dfn>ended</dfn>. When track instance
<var>track</var> ends for any reason other than the <code><a href=
- "#dom-mediastream-stop">stop()</a></code> method being invoked on the
- <code><a>LocalMediaStream</a></code> object that represents
+ "#dom-mediastreamtrack-stop">stop()</a></code> method being invoked on the
+ <code><a>MediaStreamTrack</a></code> object that represents
<var>track</var>, the user agent MUST queue a task that runs the
following steps:</p>
@@ -646,7 +629,35 @@
<p>If the end of the stream was reached due to a user request, the event
source for this event is the user interaction event source.</p>
+ <p>Constraints are independent of sources. **** Add note about
+ potential effects of readonly and remote flags ****</p>
+
+ <p>Whether <code><a>MediaTrackConstraints</a></code> were provided at
+ track initialization time or need to be established later at
+ runtime, the APIs defined below allow the retrieval and
+ manipulation of the constraints currently established on a
+ track.</p>
+
+ <p>Each track maintains an internal version of
+ the <code><a>MediaTrackConstraints</a></code> structure, namely a
+ mandatory set of constraints (no duplicates), and an optional
+ ordered list of individual constraint objects (may contain
+ duplicates). The internal stored constraint structure is only
+ exposed to the application using the existing
+ <code><a>MediaTrackConstraints</a></code>,
+ <code><a>MediaTrackConstraintSet</a></code>, <code><a>MediaTrackConstraint</a></code>,
+ and similarly-derived-type dictionary objects.</p>
+
+ <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>
+ changes, then the user agent should perform the same actions to
+ re-evaluate the constraints of each track affected by that
+ source change.</p>
+
<dl class="idl" title="interface MediaStreamTrack">
+
<dt>readonly attribute DOMString kind</dt>
<dd>
@@ -720,19 +731,40 @@
attribute represents the state of the track. It MUST return the value
to which the user agent last set it.
- <p>When a <code><a>MediaStreamTrack</a></code> object is created, its
+ <p>When a <code><a>MediaStreamTrack</a></code> object is created via <code><a href=
+ "#dom-navigator-getusermedia">getUserMedia()</a></code>, its
<code><a href=
"#dom-mediastreamtrack-readystate">readyState</a></code> is either
<code>live</code> or <code>muted</code>, depending on the state of
- the track’s underlying media source. For example, a track in a
- <code><a>LocalMediaStream</a></code>, created with <code><a href=
- "#dom-navigator-getusermedia">getUserMedia()</a></code>, MUST
+ the track's underlying media source. For example, a track in a
+ <code><a>MediaStream</a></code> created with <code><a href=
+ "#dom-navigator-getusermedia">getUserMedia()</a></code> MUST
initially have its <code><a href=
"#dom-mediastreamtrack-readystate">readyState</a></code> attribute
set to <code>live</code>.
</p>
</dd>
+ <dt>readonly attribute SourceTypeEnum sourceType</dt>
+
+ <dd>Returns the type information associated with the currently
+ attached source (if any).</dd>
+
+ <dt>readonly attribute DOMString sourceId</dt>
+
+ <dd>The application-unique identifier for this source. The
+ same identifier must be valid between sessions of this
+ application, but must also be different for other
+ applications. Some sort of GUID is recommended for the
+ identifier.</dd>
+
+ <dt>attribute EventHandler onstarted</dt>
+
+ <dd>This event handler, of type <code><a href=
+ "#event-mediastreamtrack-started">started</a></code>, MUST be supported by
+ all objects implementing the <code><a>MediaStreamTrack</a></code>
+ interface.</dd>
+
<dt>attribute EventHandler onmute</dt>
<dd>This event handler, of type <code><a href=
@@ -753,9 +785,257 @@
"#event-mediastreamtrack-ended">ended</a></code>, MUST be supported by
all objects implementing the <code><a>MediaStreamTrack</a></code>
interface.</dd>
+
+ <dt>any getConstraint ()</dt>
+
+ <dd>
+ <dl class="parameters">
+ <dt>DOMString constraintName</dt>
+ <dd>The name of the setting for which the current value of that setting should be returned</dd>
+ <dt>optional boolean mandatory = false</dt>
+ <dd><code>true</code> to indicate that
+ the constraint should be looked up in the mandatory set
+ of constraints, otherwise, the constraintName should be
+ retrieved from the optional list of constraints.</dd>
+ </dl>
+
+ <p>Retrieves a specific named constraint value from the
+ track. The named constraints are the same names used for
+ the <a class="internalDFN"
+ href="#dfn-capabilities">capabilities</a> API, and also are
+ the same names used for the source's <a class="internalDFN"
+ href="#dfn-state">state</a> attributes.</p>
+
+ <p>Returns one of the following types:</p>
+ <dl>
+ <dt><strong>null</strong></dt>
+ <dd>If no constraint matching the provided constraintName
+ exists in the respective optional or mandatory set on this
[820 lines skipped]
--- /sources/public/2011/webrtc/editor/getusermedia.js 2012/12/12 13:45:18 1.8
+++ /sources/public/2011/webrtc/editor/getusermedia.js 2013/03/20 17:29:40 1.9
@@ -12,14 +12,14 @@
// publishDate: "2009-08-06",
// new ability to override the copyright completely
- overrideCopyright: "<p class='copyright'>Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:<br /> © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.<\/p> <p class='copyright'>All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group and the Device APIs Working Group are under the following <a href='http://www.w3.org/Consortium/Legal/ipr-notice#Copyright'>Copyright<\/a>:<br />© 2011-2012 <a href='http://www.w3.org/'><acronym title='World Wide Web Consortium'>W3C<\/acronym><\/a><sup>®<\/sup> (<a href='http://www.csail.mit.edu/'><acronym title='Massachusetts Institute of Technology'>MIT<\/acronym><\/a>, <a href='http://www.ercim.eu/'><acronym title='European Research Consortium for Informatics and Mathematics'>ERCIM<\/acronym><\/a>, <a href='http://www.keio.ac.jp/'>Keio<\/a>), All Rights Reerved. <a href='http://www.w3.org/Consortium/Legal/copyright-documents'>Document use<\/a> rules apply.<\/p> <p class='copyright'>For the entire publication on the W3C site the <a href='http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer'>liability<\/a> and <a href='http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks'>trademark<\/a> rules apply.<\/p>",
+ overrideCopyright: "<p class='copyright'>Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:<br /> © Copyright 2004-2011 Apple Computer, Inc., Mozilla Foundation, and Opera Software ASA. You are granted a license to use, reproduce and create derivative works of this document.<\/p> <p class='copyright'>All subsequent changes since 26 July 2011 done by the W3C WebRTC Working Group and the Device APIs Working Group are under the following <a href='http://www.w3.org/Consortium/Legal/ipr-notice#Copyright'>Copyright<\/a>:<br />© 2011-2013 <a href='http://www.w3.org/'><acronym title='World Wide Web Consortium'>W3C<\/acronym><\/a><sup>®<\/sup> (<a href='http://www.csail.mit.edu/'><acronym title='Massachusetts Institute of Technology'>MIT<\/acronym><\/a>, <a href='http://www.ercim.eu/'><acronym title='European Research Consortium for Informatics and Mathematics'>ERCIM<\/acronym><\/a>, <a href='http://www.keio.ac.jp/'>Keio<\/a>, <a href='http:/ev.buaa.edu.cn/'>Beihang<\/a>), All Rights Reserved. <a href='http://www.w3.org/Consortium/Legal/copyright-documents'>Document use<\/a> rules apply.<\/p> <p class='copyright'>For the entire publication on the W3C site the <a href='http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer'>liability<\/a> and <a href='http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks'>trademark<\/a> rules apply.<\/p>",
// if the specification's copyright date is a range of years, specify
// the start date here:
// 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/20120813/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20121212/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 Wednesday, 20 March 2013 17:29:42 UTC