W3C home > Mailing lists > Public > public-dap-commits@w3.org > March 2013

CVS 2011/webrtc/editor

From: CVS User dburnett <cvsmail@w3.org>
Date: Wed, 20 Mar 2013 17:29:41 +0000
Message-Id: <E1UIMpZ-0003de-1W@roscoe.w3.org>
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 /> &#169; 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 />&#169; 2011-2012 <a href='http://www.w3.org/'><acronym title='World Wide Web Consortium'>W3C<\/acronym><\/a><sup>&#174;<\/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 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>",
+   overrideCopyright:  "<p class='copyright'>Initial Author of this Specification was Ian Hickson, Google Inc., with the following copyright statement:<br /> &#169; 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 />&#169; 2011-2013 <a href='http://www.w3.org/'><acronym title='World Wide Web Consortium'>W3C<\/acronym><\/a><sup>&#174;<\/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 GMT

This archive was generated by hypermail 2.3.1 : Wednesday, 20 March 2013 17:29:43 GMT