- From: CVS User dburnett <cvsmail@w3.org>
- Date: Tue, 30 Apr 2013 04:46:46 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv30145
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20130429 archived version.
--- /sources/public/2011/webrtc/editor/getusermedia.html 2013/03/20 17:29:39 1.16
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2013/04/30 04:46:45 1.17
@@ -74,99 +74,182 @@
</section>
<section>
<h2>Terminology</h2>
- <p>
- The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
- EventHandler</a></code> interface represents a callback used for event
- handlers as defined in [[!HTML5]].
- </p>
- <p>
- The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
- queue a task</a></dfn> and
- <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>
+
+ <dl>
+ <dt><i>HTML Terms:</i></dt>
+ <dd>
+ <p>
+ The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
+ EventHandler</a></code> interface represents a callback used for event
+ handlers as defined in [[!HTML5]].
+ </p>
+ <p>
+ The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn> and
+ <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>
+ </dd>
+
+ <dt><dfn title="source" id="dfn-source">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
+ source can be a physical webcam, microphone, local video or
+ audio file from the user's hard drive, network resource, or
+ static image.</p>
+
+ <p>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.</p>
+
+ <p>Other than the identifier, other bits of source identity
+ 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.</p>
+
+ <p>Sources <strong>do not</strong> have constraints --
+ tracks have constraints. When a source is connected to a
+ track, it must conform to the constraints present on that
+ track (or set of tracks).</p>
+
+ <p>Sources will be released (un-attached) from a track when
+ the track is ended for any reason.</p>
+
+ <p>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.</p>
+
+ <p>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>
+ </dd>
+
+ <dt><dfn title=""
+ id="dfn-state">State (Source State)</dfn></dt>
+ <dd>
+ <p>State refers to the immediate, current value of the
+ source's (optionally constrained) capabilities. State is
+ always read-only.</p>
+ <p>A source's state can change dynamically over time due to
+ environmental conditions, sink configurations, or constraint
+ changes. A source's state must always conform to the current
+ set of mandatory constraints that all of the tracks it is
+ bound to have defined, and should do its best to conform to
+ the set of optional constraints specified.</p>
+ <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>
+ <p>Events are available that signal to the application that
+ source state has changed.</p>
+ <p>A conforming user-agent <em title="must"
+ class="rfc2119">must</em> support all the state names
+ defined in this spec.</p>
+ </dd>
+
+ <dt><dfn title="capabilities"
+ id="dfn-capabilities">Capabilities</dfn></dt>
+ <dd>
+ <p>Source capabilities are the intrinsic "features" of a
+ source object. For each source state, there is a
+ corresponding capability that describes whether it is
+ supported by the source and if so, what the range of
+ supported values are. Capabilities are expressed as either a
+ series of states (for enumerated-type capabilities) or as a
+ min/max range.</p>
+ <p>The values of the supported capabilities must be
+ normalized to the ranges and enumerated types defined in
+ this specification.</p>
+ <p>Capabilities return the same underlying per-source
+ capabilities, regardless of any user-supplied constraints
+ present on the source (capabilities are independent of
+ constraints).</p>
+ <p>Source capabilities are effectively
+ constant. Applications should be able to depend on a
+ specific source having the same capabilities for any
+ session.</p>
+ </dd>
+
+ <dt><dfn title="constraints"
+ id="dfn-constraints">Constraints</dfn></dt>
+
+ <dd>
+ <p>Constraints 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.</p>
+
+ <p>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).</p>
+
+ <p>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.</p>
+
+ <p>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.</p>
+
+ <p>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.</p>
+
+ <p>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.).</p>
+
+ <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
+ will allow future constraints to be defined in a backward
+ compatible manner.</p>
+
+ <p>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>
+ </dd>
+ </dl>
</section>
<section id="stream-api">
@@ -224,20 +307,21 @@
accessible media sources (that does not require any additional
permissions) using the <code><a href="#dom-mediastream">MediaStream()</a>
</code> constructor. The constructor argument can either be an existing
- <code><a>MediaStream</a></code> object, in which case the given stream is
- cloned, or an array of <code><a>MediaStreamTrack</a></code> objects. The
+ <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
streams.</p>
<p><img alt="A MediaStream" src="images/media-stream.png" width=
"40%"></p>
- <p>The ability to duplicate a <code><a>MediaStream</a></code>,
- 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>Both <code><a>MediaStream</a></code> and <code>
+ <a>MediaStreamTrack</a></code> objects can be cloned. This allows for
+ greater control since the separate instances can be manipulated and
+ <a title="consumer">consumed</a> individually. A cloned <code>
+ <a>MediaStream</a></code> contains clones of all member tracks from the
+ original stream.</p>
<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
@@ -253,7 +337,8 @@
<h2>MediaStream</h2>
<p>The <dfn id="dom-mediastream"> <code>MediaStream()</code></dfn>
- constructor takes zero or one argument. If the argument is supplied, it
+ constructor composes a new stream out of existing tracks. It takes zero
+ or one argument. If the argument is supplied, it
MUST either be 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>
@@ -297,13 +382,8 @@
</li>
<li>
- <p>Create a new <code><a>MediaStreamTrack</a></code> object
- and let it inherit <var>track’s</var> underlying source,
- <code><a href="#dom-mediastreamtrack-kind">kind</a></code> and
- <code><a href="#dom-mediastreamtrack-label">label</a></code>
- attributes. Add the new <code><a>MediaStreamTrack</a>
- </code> to <var>stream</var>’s <a href="#track-set">track
- set</a>.</p>
+ <p>Add <var>track</var> to <var>stream</var>'s <a href=
+ "#track-set">track set</a>.</p>
</li>
</ol>
@@ -386,14 +466,14 @@
interaction task source. Otherwise the task source for this <span title=
"concept-task">task</span> is the networking task source.</p>
- <!-- The "[]" in MediaStreamTrack[] breaks rendering if added directly to
- the constructor declaration -->
- <dl class="idl" title="typedef MediaStreamTrack[] MediaStreamTrackArray"></dl>
+ <!-- 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 (),
+ title="[Constructor,
Constructor (MediaStream stream),
- Constructor (MediaStreamTrackArray tracks)]
+ Constructor (MediaStreamTrackSequence tracks)]
interface MediaStream : EventTarget">
<dt>readonly attribute DOMString id</dt>
@@ -489,13 +569,8 @@
</li>
<li>
- <p>Create a new <code><a>MediaStreamTrack</a></code> object
- and let it inherit <var>track’s</var> underlying source,
- <code><a href="#dom-mediastreamtrack-kind">kind</a></code> and
- <code><a href="#dom-mediastreamtrack-label">label</a></code>
- attributes. Add the new <code><a>MediaStreamTrack</a>
- </code> to <var>stream</var>’s <a href="#track-set">track
- set</a>.</p>
+ <p>Add <var>track</var> to <var>stream</var>'s <a href=
+ "#track-set">track set</a>.</p>
</li>
</ol>
</dd>
@@ -523,17 +598,49 @@
</li>
<li>
- <p>If <var>track</var> is not in <var>stream</var>’s
- <a href="#track-set">track set</a>, abort these steps.</p>
- </li>
-
- <li>
- <p>Remove <var>track</var> from <var>stream’s</var>
- <a href="#track-set">track set</a>.</p>
+ <p>If <var>track</var> is in <var>stream</var>'s
+ <a href="#track-set">track set</a>, remove it.</p>
</li>
</ol>
</dd>
+ <dt>MediaStream clone()</dt>
+
+ <dd>
+ <p>Clones the given <code><a>MediaStream</a></code> and all its
+ tracks.</p>
+
+ <p>When the <dfn id=
+ "dom-mediastream-clone"><code>clone()</code></dfn> method
+ is invoked, the user agent MUST run the following steps:</p>
+
+ <ol>
+ <li>
+ <p>Let <var>streamClone</var> be a newly constructed <code>
[1399 lines skipped]
--- /sources/public/2011/webrtc/editor/getusermedia.js 2013/03/20 17:29:40 1.9
+++ /sources/public/2011/webrtc/editor/getusermedia.js 2013/04/30 04:46:46 1.10
@@ -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/20121212/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20130320/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 Tuesday, 30 April 2013 04:46:47 UTC