- From: CVS User dburnett <cvsmail@w3.org>
- Date: Wed, 29 May 2013 21:04:55 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv471
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20130529 archived version.
--- /sources/public/2011/webrtc/editor/getusermedia.html 2013/05/15 09:32:39 1.19
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2013/05/29 21:04:54 1.20
@@ -263,9 +263,9 @@
video content, e.g. from a local camera. The data from a
<code><a>MediaStream</a></code> object does not necessarily have a
canonical binary form; for example, it could just be "the video currently
- coming from the user’s video camera". This allows user agents to
+ coming from the user's video camera". This allows user agents to
manipulate media streams in whatever fashion is most suitable on the
- user’s platform.</p>
+ user's platform.</p>
<p>Each <code><a>MediaStream</a></code> object can contain zero or more
tracks, in particular audio and video tracks. All tracks in a MediaStream
@@ -287,13 +287,13 @@
<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
+ from the user's local camera. The output of the object controls how the
object is used, e.g., what is saved if the object is written to a file or
what is displayed if the object is used in a <code>video</code>
element.</p>
<p>Each track in a <code><a>MediaStream</a></code> object can be
- disabled, meaning that it is muted in the object’s output. All tracks are
+ disabled, meaning that it is muted in the object's output. All tracks are
initially enabled.</p>
<p>A <code><a>MediaStream</a></code> can be <a>finished</a>, indicating
@@ -314,7 +314,7 @@
streams.</p>
<p><img alt="A MediaStream" src="images/media-stream.png" width=
- "40%"></p>
+ "418"></p>
<p>Both <code><a>MediaStream</a></code> and <code>
<a>MediaStreamTrack</a></code> objects can be cloned. This allows for
@@ -329,7 +329,7 @@
The <code>MediaStream</code> object is also used in contexts outside
<code>getUserMedia</code>, such as [[!WEBRTC10]]. In both cases, ensuring
a realtime stream reduces the ease with which pages can distinguish live
- video from pre-recorded video, which can help protect the user’s
+ video from pre-recorded video, which can help protect the user's
privacy.</p>
</section>
@@ -350,13 +350,13 @@
</li>
<li>
- <p>Initialize <var>stream’s</var> <code><a href=
+ <p>Initialize <var>stream's</var> <code><a href=
"#dom-mediastream-id">id</a></code> attribute to a newly generated
value.</p>
</li>
<li>
- <p>If the constructor’s argument is present, run the sub steps that
+ <p>If the constructor's argument is present, run the sub steps that
corresponds to the argument type.</p>
<ul>
@@ -393,7 +393,7 @@
<p><code><a>MediaStream</a></code>:</p>
<p>Run the sub steps labeled <em>Add track</em> (above) for every
- <code><a>MediaStreamTrack</a></code> in the argument stream’s
+ <code><a>MediaStreamTrack</a></code> in the argument stream's
<a href="#track-set">track set</a>.
</p>
</li>
@@ -440,7 +440,7 @@
<ol>
<li>
- <p>If the object’s <code><a href=
+ <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-mediastreamtrack-stop">stop()</a></code> method was probably called
@@ -450,7 +450,7 @@
</li>
<li>
- <p>Set the object’s <code><a href=
+ <p>Set the object's <code><a href=
"#dom-mediastream-ended">ended</a></code> attribute to true.</p>
</li>
@@ -480,7 +480,7 @@
<dd>
<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=
+ MUST initialize the object's <code><a href=
"#dom-mediastream-id">id</a></code> attribute to that string.
Such strings MUST only use characters in the ranges U+0021, U+0023 to
U+0027, U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041
@@ -504,7 +504,7 @@
<p>The <dfn id=
"dom-mediastream-getaudiotracks"><code>getAudioTracks()</code></dfn>
method MUST return a sequence that represents a snapshot of all the
- <code><a>MediaStreamTrack</a></code> objects in this stream’s
+ <code><a>MediaStreamTrack</a></code> objects in this stream's
<a href="#track-set">track set</a> whose <code>
<a href="#dom-mediastreamtrack-kind">kind</a></code> is equal to
"<code>audio</code>". The conversion from the <a href=
@@ -521,7 +521,7 @@
<p>The <dfn id=
"dom-mediastream-getvideotracks"><code>getVideoTracks()</code></dfn>
method MUST return a sequence that represents a snapshot of all the
- <code><a>MediaStreamTrack</a></code> objects in this stream’s
+ <code><a>MediaStreamTrack</a></code> objects in this stream's
<a href="#track-set">track set</a> whose <code>
<a href="#dom-mediastreamtrack-kind">kind</a></code> is equal to
"<code>video</code>". The conversion from the <a href=
@@ -535,7 +535,7 @@
<p>The <dfn id=
"dom-mediastream-gettrackbyid"><code>getTrackById()</code></dfn>
method MUST return the first <code><a>MediaStreamTrack</a></code>
- object in this stream’s <a href="#track-set">track set</a> whose
+ object in this stream's <a href="#track-set">track set</a> whose
<code><a href="#dom-mediastreamtrack-id">id</a></code> is equal to
<var>trackId</var>. The method MUST return null if no track matches
the <var>trackId</var> argument.</p>
@@ -564,7 +564,7 @@
</li>
<li>
- <p>If <var>track</var> is already in <var>stream’s</var>
+ <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>
@@ -740,10 +740,10 @@
<p>When a <code><a>MediaStreamTrack</a></code> object ends for any reason
(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
+ 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
+ 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-mediastreamtrack-stop">stop()</a></code> method being invoked on the
@@ -753,13 +753,13 @@
<ol>
<li>
- <p>If the track’s <code><a href=
+ <p>If the track's <code><a href=
"#dom-mediastreamtrack-readystate">readyState</a></code> attribute
has the value <code>ended</code> already, then abort these steps.</p>
</li>
<li>
- <p>Set <var>track’s</var> <code><a href=
+ <p>Set <var>track's</var> <code><a href=
"#dom-mediastreamtrack-readystate">readyState</a></code> attribute to
<code>ended</code>.</p>
</li>
@@ -830,7 +830,7 @@
<p>Unless a <code><a>MediaStreamTrack</a></code> object is created as
a part a of special purpose algorithm that specifies how the track id
must be initialized, the user agent MUST generate a globally unique
- identifier string and initialize the object’s <code><a href=
+ identifier string and initialize the object's <code><a href=
"#dom-mediastreamtrack-id">id</a></code> attribute to that string.</p>
<p>An example of an algorithm that specifies how the track id must be
@@ -849,7 +849,7 @@
<p>User agents MAY label audio and video sources (e.g., "Internal
microphone" or "External USB Webcam"). The <dfn id=
"dom-mediastreamtrack-label"><code>MediaStreamTrack.label</code></dfn>
- attribute MUST return the label of the object’s corresponding track,
+ attribute MUST return the label of the object's corresponding track,
if any. If the corresponding track has or had no label, the attribute
MUST instead return the empty string.</p>
@@ -875,7 +875,7 @@
<p class="note">Thus, after a <code><a>MediaStreamTrack</a></code> is
disassociated from its track, its <code><a href=
"#dom-mediastreamtrack-enabled">enabled</a></code> attribute still
- changes value when set; it just doesn’t do anything with that new
+ changes value when set; it just doesn't do anything with that new
value.</p>
</dd>
@@ -947,6 +947,12 @@
all objects implementing the <code><a>MediaStreamTrack</a></code>
interface.</dd>
+ <dt>static sequence<SourceInfo> getSourceInfos()</dt>
+
+ <dd>
+ Returns authorized information for all available sources.
+ </dd>
+
<dt>MediaTrackConstraints? constraints()</dt>
<dd>
@@ -966,7 +972,7 @@
associated with the allowed constraints.
</dd>
- <dt>(AllVideoCapabilites or AllAudioCapabilities) capabilities ()</dt>
+ <dt>(AllVideoCapabilities or AllAudioCapabilities) capabilities ()</dt>
<dd>
<p>Returns a dictionary with all of the capabilities for the
@@ -1083,7 +1089,7 @@
<dd>
<p>When a <code><a>MediaStreamTrack</a></code>
- object’s <dfn id=
+ object's <dfn id=
"dom-mediastreamtrack-stop"><code>stop()</code></dfn> method
is invoked, if no source is attached
(e.g., <code><a>sourceType</a></code> is "none"), then this
@@ -1128,7 +1134,7 @@
<dt>live</dt>
<dd>
- <p>The track is active (the track’s underlying media source is making
+ <p>The track is active (the track's underlying media source is making
a best-effort attempt to provide data in real time).</p>
<p>The output of a track in the <code>live</code> state can be
@@ -1165,15 +1171,53 @@
</dl>
</section>
+ <section>
+ <h2>Source Info</h2>
+
+ <dl class="idl" title="dictionary SourceInfo">
+ <dt>DOMString sourceId</dt>
+ <dd>The unique id for this source as described in the <code><a>MediaSourceStates</a></code> dictionary.</dd>
+
+ <dt>DOMString kind</dt>
+ <dd>MUST be either "audio" or "video".</dd>
+
+ <dt>DOMString label</dt>
+ <dd>If the application is authorized to get info from this
+ source, the <code>label</code> attribute will be filled in
+ with exactly the same value as would have been returned from
+ a call to <code><a>getUserMedia()</a></code> with a
+ constraint specifying this
+ source's <code><a>sourceId</a></code>.</dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2>Video Facing Mode Enum</h2>
+
+ <dl class="idl" title="enum VideoFacingModeEnum">
+ <dt>user</dt>
+ <dd>The source is facing toward the user (a self-view camera).</dd>
+
+ <dt>environment</dt>
+ <dd>The source is facing away from the user (viewing the
+ environment).</dd>
+
+ <dt>left</dt>
+ <dd>The source is facing to the left of the user.</dd>
+
+ <dt>right</dt>
+ <dd>The source is fating to the right of the user.</dd>
+ </dl>
+ </section>
</section>
<section>
<h3>MediaStreamTrackEvent</h3>
<p>The <code><a href=
- "#event-mediastreamtracklist-addtrack">addtrack</a></code> and
+ "#event-mediastream-addtrack">addtrack</a></code> and
<code title="event-MediaStreamTracklist-removetrack"><a href=
- "#event-mediastreamtracklist-removetrack">removetrack</a></code> events
+ "#event-mediastream-removetrack">removetrack</a></code> events
use the <code><a>MediaStreamTrackEvent</a></code> interface.</p>
<p><dfn title="Fire a track event">Firing a track event named
@@ -1200,7 +1244,7 @@
</dl>
<dl class="idl" title="dictionary MediaStreamTrackEventInit : EventInit">
- <dt>readonly MediaStreamTrack? track</dt>
+ <dt>MediaStreamTrack? track</dt>
<dd>
<p> </p>
@@ -1236,11 +1280,11 @@
<div class="note">
<p><strong>Example: </strong> <code><a>VideoStreamTrack</a></code>
objects are instantiated in JavaScript using the new
- operator: <br/>
- <tt><b>new</b> <code>VideoStreamTrack</code>();</tt><br/>
- or<br/>
- <tt><b>new</b> <code>VideoStreamTrack</code>( { optional: [ { <code>sourceId</code>: "20983-20o198-109283-098-09812" }, { <code>width</code>: { min: 800, max: 1200 }}, { <code>height</code>: { min: 600 }}] });</tt>
- </p></div>
+ operator:</p>
+ <pre><b>new</b> <code>VideoStreamTrack</code>();</pre>
+ or
+ <pre><b>new</b> <code>VideoStreamTrack</code>( { optional: [ { <code>sourceId</code>: "20983-20o198-109283-098-09812" }, { <code>width</code>: { min: 800, max: 1200 }}, { <code>height</code>: { min: 600 }}] });</pre>
+ </div>
<dl class="idl" title="[Constructor(optional MediaTrackConstraints videoConstraints)]
interface VideoStreamTrack : MediaStreamTrack">
@@ -1277,11 +1321,11 @@
<h2>AudioStreamTrack</h2>
<div class="note">
- <p><strong>Example: </strong><code><a>AudioStreamTrack</a></code> objects are instantiated in JavaScript using the new operator: <br/>
- <tt><b>new</b> <code>AudioStreamTrack</code>();</tt><br/>
- or<br/>
- <tt><b>new</b> <code>AudioStreamTrack</code>( { optional: [ { <code>sourceId</code>: "64815-wi3c89-1839dk-x82-392aa" }, { <code>gain</code>: 0.5 }] });</tt>
- </p></div>
+ <p><strong>Example: </strong><code><a>AudioStreamTrack</a></code> objects are instantiated in JavaScript using the new operator:</p>
+ <pre><b>new</b> <code>AudioStreamTrack</code>();</pre>
+ or
+ <pre><b>new</b> <code>AudioStreamTrack</code>( { optional: [ { <code>sourceId</code>: "64815-wi3c89-1839dk-x82-392aa" }, { <code>gain</code>: 0.5 }] });</pre>
+ </div>
<dl class="idl" title="[Constructor(optional MediaTrackConstraints audioConstraints)]
interface AudioStreamTrack : MediaStreamTrack">
@@ -1301,11 +1345,226 @@
</section>
<section>
+ <h2>The model: sources, sinks, constraints, and states</h2>
+
+ <p>Browsers provide a media pipeline from sources to sinks. In
+ a browser, sinks are the <img>, <video> and
+ <audio> tags. Traditional sources include camera,
+ microphones, streamed content, files and web resources. The
+ media produced by these sources typically does not change over
+ time - these sources can be considered to be static.</p>
+
+ <p>The sinks that display these sources to the user (the actual
+ tags themselves) have a variety of controls for manipulating the
+ source content. For example, an <img> tag scales down a
+ huge source image of 1600x1200 pixels to fit in a rectangle
+ defined with <code>width="400"</code>
+ and <code>height="300"</code>.</p>
+
+ <p>The getUserMedia API adds dynamic sources such as microphones
+ and cameras - the characteristics of these sources can change in
+ response to application needs. These sources can be considered
+ to be dynamic in nature. A <video> element that displays
+ media from a dynamic source can either perform scaling or it can
+ feed back information along the media pipeline and have the
+ source produce content more suitable for display.</p>
+
+ <div class="note">
+ <p><strong>Note: </strong> This sort of feedback loop is
+ obviously just enabling an "optimization", but it's a
+ non-trivial gain. This optimization can save battery, allow
+ for less network congestion, etc...</p>
+ </div>
+
+ <p>Note that <code>MediaStream</code> sinks
+ (such as <code><video></code>, <code><audio></code>,
+ and even <code>RTCPeerConnection</code>) will continue to have
+ mechanisms to further transform the source stream beyond that
+ which the <a>state</a>s, <a>capabilities</a>,
+ and <a>constraints</a> described in this specification
+ offer. (The sink transformation options, including
+ those of <code>RTCPeerConnection</code>, are outside the scope of
+ this specification.)</p>
+
+ <p>The act of changing or applying a track constraint may affect
+ the <a>state</a> of all
+ tracks sharing that source and consequently all down-level sinks
+ that are using that source. Many sinks may be able to take these
+ changes in stride, such as the <code><video></code>
+ element or <code>RTCPeerConnection</code>. Others like the
+ Recorder API may fail as a result of a source state change.</p>
+
+ <p>The <code>RTCPeerConnection</code> is an interesting object
+ because it acts simultaneously as both a
+ sink <strong>and</strong> a source for over-the-network
+ streams. As a sink, it has source transformational capabilities
+ (e.g., lowering bit-rates, scaling-up or down resolutions,
+ adjusting frame-rates), and as a source it could have its own
+ states changed by a track source (though in this specification
+ sources with the <code><a>remote</a></code> attribute set to
+ true do not consider the current constraints applied to a
+ track). </p>
+
+ <p>To illustrate how changes to a given source impact various
+ sinks, consider the following example. This example only uses
+ width and height, but the same principles apply to any of
+ the <a class="internalDFN" href="#dfn-state">state</a>s exposed
+ in this proposal. In the first figure a home client has obtained
[405 lines skipped]
--- /sources/public/2011/webrtc/editor/getusermedia.js 2013/05/15 01:58:19 1.11
+++ /sources/public/2011/webrtc/editor/getusermedia.js 2013/05/29 21:04:54 1.12
@@ -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/20130429/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20130515/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, 29 May 2013 21:05:00 UTC