- From: CVS User dburnett <cvsmail@w3.org>
- Date: Wed, 19 Feb 2014 02:04:13 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv27480
Modified Files:
getusermedia.html
Log Message:
Added 20140218 archived version.
--- /sources/public/2011/webrtc/editor/getusermedia.html 2014/02/01 00:52:59 1.27
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2014/02/19 02:04:13 1.28
@@ -457,21 +457,21 @@
display: none;
}
}
-</style><link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/W3C-ED"><!--[if lt IE 9]><script src='https://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
+</style><link href="https://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet"><!--[if lt IE 9]><script src='https://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
-<body class="h-entry" style="" role="document" id="respecDocument"><div class="head" role="contentinfo" id="respecHeader">
+<body id="respecDocument" role="document" class="h-entry"><div id="respecHeader" role="contentinfo" class="head">
<p>
- <a href="http://www.w3.org/"><img width="72" height="48" src="https://www.w3.org/Icons/w3c_home" alt="W3C"></a>
+ <a href="http://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a>
</p>
<h1 class="title p-name" id="title" property="dcterms:title">Media Capture and Streams</h1>
- <h2 property="dcterms:issued" datatype="xsd:dateTime" content="2014-01-31T05:34:25.000Z" id="w3c-editor-s-draft-30-january-2014"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft <time class="dt-published" datetime="2014-01-30">30 January 2014</time></h2>
+ <h2 id="w3c-editor-s-draft-18-february-2014" property="dcterms:issued" datatype="xsd:dateTime" content="2014-02-19T01:04:05.000Z"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft <time class="dt-published" datetime="2014-02-18">18 February 2014</time></h2>
<dl>
<dt>This version:</dt>
- <dd><a class="u-url" href="http://dev.w3.org/2011/webrtc/editor/archives/20140130/getusermedia.html">http://dev.w3.org/2011/webrtc/editor/archives/20140130/getusermedia.html</a></dd>
+ <dd><a class="u-url" href="http://dev.w3.org/2011/webrtc/editor/archives/20131225/getusermedia.html">http://dev.w3.org/2011/webrtc/editor/archives/20131225/getusermedia.html</a></dd>
<dt>Latest published version:</dt>
<dd><a href="http://www.w3.org/TR/mediacapture-streams/">http://www.w3.org/TR/mediacapture-streams/</a></dd>
@@ -482,6 +482,7 @@
+
<dt>Previous editor's draft:</dt>
<dd><a href="http://dev.w3.org/2011/webrtc/editor/archives/20131225/getusermedia.html">http://dev.w3.org/2011/webrtc/editor/archives/20131225/getusermedia.html</a></dd>
@@ -512,13 +513,10 @@
<hr>
</div>
- <section id="abstract" class="introductory" property="dcterms:abstract" datatype="" typeof="bibo:Chapter" resource="#ref" rel="bibo:Chapter"><h2 aria-level="1" role="heading" id="h2_abstract">Abstract</h2>
- <p>This document is a temporary version that has deleted all sections
-except one. This allows the editors to get that section out to the working group
-and get comments on it before making the associated changes to the rest of the
-specification. Readers that need more context are advised to have a look at the
-previos version. </p>
- </section><section id="sotd" class="introductory" typeof="bibo:Chapter" resource="#ref" rel="bibo:Chapter"><h2 aria-level="1" role="heading" id="h2_sotd">Status of This Document</h2>
+ <section rel="bibo:Chapter" resource="#ref" typeof="bibo:Chapter" datatype="" property="dcterms:abstract" class="introductory" id="abstract"><h2 id="h2_abstract" role="heading" aria-level="1">Abstract</h2>
+ <p>This document defines a set of JavaScript APIs that allow local media,
+ including audio and video, to be requested from a platform.</p>
+ </section><section rel="bibo:Chapter" resource="#ref" typeof="bibo:Chapter" id="sotd" class="introductory"><h2 id="h2_sotd" role="heading" aria-level="1">Status of This Document</h2>
@@ -559,6 +557,7 @@
</p>
+
<p>
This document was produced by a group operating under the
@@ -583,523 +582,4032 @@
+
+</section><section id="toc"><h2 id="h2_toc" role="heading" aria-level="1" class="introductory">Table of Contents</h2><ul id="respecContents" role="directory" class="toc"><li class="tocline"><a class="tocxref" href="#intro"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#conformance"><span class="secno">2. </span>Conformance</a></li><li class="tocline"><a class="tocxref" href="#terminology"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a class="tocxref" href="#stream-api"><span class="secno">4. </span>MediaStream API</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#introduction"><span class="secno">4.1 </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#mediastream"><span class="secno">4.2 </span>MediaStream</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#constructors"><span class="secno">4.2.1 </span>Constructors</a></li><li class="tocline"><a class="tocxref" href="#attributes"><pan class="secno">4.2.2 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods"><span class="secno">4.2.3 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#mediastreamtrack"><span class="secno">4.3 </span>MediaStreamTrack</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#life-cycle-and-media-flow"><span class="secno">4.3.1 </span>Life-cycle and Media Flow</a></li><li class="tocline"><a class="tocxref" href="#tracks-and-constraints"><span class="secno">4.3.2 </span>Tracks and Constraints</a></li><li class="tocline"><a class="tocxref" href="#interface-definition"><span class="secno">4.3.3 </span>Interface Definition</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-1"><span class="secno">4.3.3.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-1"><span class="secno">4.3.3.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#track-source-types"><span class="scno">4.3.4 </span>Track Source Types</a></li><li class="tocline"><a class="tocxref" href="#isolated-media-streams"><span class="secno">4.3.5 </span>Isolated Media Streams</a></li></ul></li><li class="tocline"><a class="tocxref" href="#mediastreamtrackevent"><span class="secno">4.4 </span>MediaStreamTrackEvent</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#constructors-1"><span class="secno">4.4.1 </span>Constructors</a></li><li class="tocline"><a class="tocxref" href="#attributes-2"><span class="secno">4.4.2 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#dictionary-mediastreamtrackeventinit-members"><span class="secno">4.4.3 </span>Dictionary <span class="formerLink"><code>MediaStreamTrackEventInit</code></span> Members</a></li></ul></li><li class="tocline"><a class="tocxref" href="#video-and-audio-tracks"><span class="secno">4.5 </span>Video and Audio Tracks</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#videostreamtrack-interface"><span class="scno">4.5.1 </span>VideoStreamTrack interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#constructors-2"><span class="secno">4.5.1.1 </span>Constructors</a></li></ul></li><li class="tocline"><a class="tocxref" href="#audiostreamtrack"><span class="secno">4.5.2 </span>AudioStreamTrack</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#constructors-3"><span class="secno">4.5.2.1 </span>Constructors</a></li></ul></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#the-model-sources-sinks-constraints-and-states"><span class="secno">5. </span>The model: sources, sinks, constraints, and states</a></li><li class="tocline"><a class="tocxref" href="#mediastreams-as-media-elements"><span class="secno">6. </span>MediaStreams as Media Elements</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#direct-assignment-to-media-elements"><span class="secno">6.1 </span>Direct Assignment to Media Elements</a><ul class="toc"><li class="tocline"><a class="tocxref" ref="#attributes-3"><span class="secno">6.1.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#loading-and-playing-a-mediastream-in-a-media-element"><span class="secno">6.2 </span>Loading and Playing a MediaStream in a Media Element</a></li><li class="tocline"><a class="tocxref" href="#media-element-attributes-when-playing-a-mediastream"><span class="secno">6.3 </span>Media Element Attributes when Playing a MediaStream</a></li></ul></li><li class="tocline"><a class="tocxref" href="#error-handling"><span class="secno">7. </span>Error Handling</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-4"><span class="secno">7.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#constructors-4"><span class="secno">7.2 </span>Constructors</a></li><li class="tocline"><a class="tocxref" href="#attributes-5"><span class="secno">7.3 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#dictionary-mediaerroreventinit-members"><san class="secno">7.4 </span>Dictionary <span class="formerLink"><code>MediaErrorEventInit</code></span> Members</a></li></ul></li><li class="tocline"><a class="tocxref" href="#event-summary"><span class="secno">8. </span>Event summary</a></li><li class="tocline"><a class="tocxref" href="#enumerating-devices"><span class="secno">9. </span>Enumerating Local Media Devices</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#navigatorusermedia"><span class="secno">9.1 </span>NavigatorUserMedia</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods-2"><span class="secno">9.1.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#device-info"><span class="secno">9.2 </span>Device Info</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#callback-mediadeviceinfocallback-parameters"><span class="secno">9.2.1 </span>Callback <span class="formerLink"><code>MediaDeviceInfoCallback</code></span> Parameters</a></li><li class="tocline"><a class="tocxref"href="#dictionary-mediadeviceinfo-members"><span class="secno">9.2.2 </span>Dictionary <span class="formerLink"><code>MediaDeviceInfo</code></span> Members</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#local-content"><span class="secno">10. </span>Obtaining local multimedia content</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#navigatorusermedia-1"><span class="secno">10.1 </span>NavigatorUserMedia</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#methods-3"><span class="secno">10.1.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#mediastreamconstraints"><span class="secno">10.2 </span>MediaStreamConstraints</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-mediastreamconstraints-members"><span class="secno">10.2.1 </span>Dictionary <span class="formerLink"><code>MediaStreamConstraints</code></span> Members</a></li></ul></li><li class="tocline"><a class="tocxref" href="#navigatorusermediasccesscallback"><span class="secno">10.3 </span>NavigatorUserMediaSuccessCallback</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#callback-navigatorusermediasuccesscallback-parameters"><span class="secno">10.3.1 </span>Callback <span class="formerLink"><code>NavigatorUserMediaSuccessCallback</code></span> Parameters</a></li></ul></li><li class="tocline"><a class="tocxref" href="#navigatorusermediaerrorcallback"><span class="secno">10.4 </span>NavigatorUserMediaErrorCallback</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#callback-navigatorusermediaerrorcallback-parameters"><span class="secno">10.4.1 </span>Callback <span class="formerLink"><code>NavigatorUserMediaErrorCallback</code></span> Parameters</a></li></ul></li><li class="tocline"><a class="tocxref" href="#implementation-suggestions"><span class="secno">10.5 </span>Implementation Suggestions</a></li></ul></li><li class="tocline"><a class="tocxref" href="#constrainable-interface"><span class="secno">11. </span>Constranable Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#interface-definition-1"><span class="secno">11.1 </span>Interface Definition</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-6"><span class="secno">11.1.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods-4"><span class="secno">11.1.2 </span>Methods</a></li><li class="tocline"><a class="tocxref" href="#applyconstraints-failure-callback"><span class="secno">11.1.3 </span>applyConstraints Failure Callback</a><ul class="toc"></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#registry"><span class="secno">11.2 </span>The Property Registry</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#PropertyValueSet"><span class="secno">11.2.1 </span><span>PropertyValueSet</span>
+ </a></li><li class="tocline"><a class="tocxref" href="#PropertyValueDoubleRange"><span class="secno">11.2.2 </span>PropertyValueDoubleRange</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-propertyvaluedoublerange-members"><span class="secno">11.2.2.1 </span>Dictionary <span class="formerLink"><code>PropertyValueDoubleRange</code></span> Members</a></li></ul></li><li class="tocline"><a class="tocxref" href="#PropertyValueLongRange"><span class="secno">11.2.3 </span>PropertyValueLongRange</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-propertyvaluelongrange-members"><span class="secno">11.2.3.1 </span>Dictionary <span class="formerLink"><code>PropertyValueLongRange</code></span> Members</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#capabilities"><span class="secno">11.3 </span>Capabilities</a></li><li class="tocline"><a class="tocxref" href="#settings"><span class="secno">11.4 </span><span>Settings</span>
+ </a></li><li class="tocline"><a class="tocxref" href="#constraints"><span class="secno">11.5 </span><span>Constraints</span>
+ </a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-constraints-members"><span class="secno">11.5.1 </span>Dictionary <span class="formerLink"><code>Constraints</code></span> Members</a></li><li class="tocline"><a class="tocxref" href="#constraintset"><span class="secno">11.5.2 </span>ConstraintSet</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#examples"><span class="secno">12. </span>Examples</a></li><li class="tocline"><a class="tocxref" href="#error-names"><span class="secno">13. </span>Error Names</a></li><li class="tocline"><a class="tocxref" href="#iana-registrations"><span class="secno">14. </span>IANA Registrations</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#track-property-registrations"><span class="secno">14.1 </span>Track Property Registrations</a></li></ul></li><li class="tocline"><a class="tocxref" href="#change-log"><span class="secno">15. </span>Change Log</a></li><li class="tocline"><a class="tocxref" href="#acknwledgements"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a class="tocxref" href="#informative-references"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></section>
+
- <section rel="bibo:Chapter" resource="#ref" typeof="bibo:Chapter" id="constrainable-interface">
- <!--OddPage--><h2 id="h2_constrainable-interface" role="heading" aria-level="1"><span class="secno">11. </span>Constrainable Interface</h2>
- <p>The Constrainable interface allows its consumers to inspect and adjust
- the properties of the object that implements it. It is broken out as a
- separate interface so that it can be used in other specifications. The core
- concept is that of a Capability, which consists of a property or feature of
- an object and the set of its possible values, which may be specified either
- as a range or as an enumeration. For example, a camera might be capable of
- framerates (a property) between 20 and 50 frames per second (a range) and
- may be able to be positioned (a property) facing towards the user, away
- from the user, or to the left or right of the user (an enumerated set.) The
- application can examine a Constrainable object's set of Capabilities via
- the <code>getCapabilities()</code> accessor.</p>
+ <section rel="bibo:Chapter" resource="#ref" typeof="bibo:Chapter" class="informative" id="intro">
+ <!--OddPage--><h2 id="h2_intro" role="heading" aria-level="1"><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
- <p>The application can select the (range of) values it wants for an
- object's Capabilities by means of one or more ConstraintSets and the
- <code>applyConstraints()</code> method. A ConstraintSet consists of the
- names of one or more properties of the object plus the desired value (or a
- range of desired values) for each of them. Each of those property/value
- pairs can be considered to be an individual constraint. For example, the
- application may set a ConstraintSet containing two constraints, the first
- stating that the framerate of a camera be between 30 and 40 frames per
- second (a range) and the second that the camera should be facing the user
- (a specific value). ConstraintSets can be mandatory or optional. In the
- case of optional ConstraintSets, the UA will consider the ConstraintSets in
- the order in which they are specified, and will try to satisfy each one,
- but will ignore a ConstraintSet if it cannot satisfy it. In the case of a
- mandatory ConstraintSet, the UA will try to satisfy it, and will call the
- <code>errorCallback</code> if it cannot do so. For example, suppose that an
- application applies three individual constraints, one stating that the
- video aspect ratio should be 3 to 2 (height to width), the next that the
- height should be 600 and the last that the width should be 500. Since these
- constraints interact with each other (the aspect ratio affects the possible
- values for height and width, and vice-versa) it is impossible to satisfy
- all three of them, so if they are all contained in a mandatory
- ConstraintSet, the UA will call the <code>errorCallback</code>. However if
- any one of the constraints is placed in an optional ConstraintSet, the
- other two can be satisfied, so the UA will satisfy the two mandatory ones,
- silently ignore the optional one, and call the
- <code>successCallback.</code></p>
+ <p>Access to multimedia streams (video, audio, or both) from local devices
+ (video cameras, microphones, Web cams) can have a number of uses, such as
+ real-time communication, recording, and surveillance.</p>
- <p>The ordering of optional ConstraintSets is significant. In the example
- in the previous paragraph, suppose that aspect ratio constraint is part of
- a mandatory ConstraintSet and that the height and width constraints are
- part of separate optional ConstraintSets. If the height ConstraintSet is
- specified first (and the other constraints in the ConstraintSet can also be
- satisfied), then it will be satisfied and the width ConstraintSet will be
- ignored. Thus the height will be set to 600 and the the width will be set
- to 400. On the other hand, if width is specified before height, the width
- ConstraintSet will be satisfied and the height ConstraintSet will be
- ignored, resulting in width of 500 and height of 750. (Note that the
- mandatory aspect ratio constraint is enforced in both cases.) The UA will
- attempt to satisfy as many optional ConstraintSets as it can, even if some
- of them cannot be satisfied and must therefore be ignored. Application
- authors can therefore implement a backoff strategy by specifying multiple
- optional ConstraintSets for the same property. For example, an application
- might specify three optional ConstraintSets, the first asking for a
- framerate greater than 500, the second asking for a framerate greater than
- 400, and the third asking for one greater than 300. If the UA is capable of
- setting a framerate greater than 500, it will (and the subsequent two
- ConstraintSets will be trivially satisfied.) However, if the UA cannot set
- the framerate above 500, it will ignore that ConstraintSet and attempt to
- set the framerate above 400. If that fails, it will then try to set it
- above 300. If the UA cannot satisfy any of the three ConstraintSets, it
- will set the framerate to any value it can get. If the developer wanted to
- insist on 300 as a lower bound, he put that in a mandatory ConstraintSet.
- In that case, the UA would fail altogether if it couldn't get a value over
- 300, but would choose a value over 500 if possible, then try for a value
- over 400. An application may inspect the set of ConstraintSets currently in
- effect via the <code>getConstraints()</code> accessor.</p>
+ <p>This document defines the APIs used to get access to local devices that
+ can generate multimedia stream data. This document also defines the
+ MediaStream API by which JavaScript is able to manipulate the stream data
+ or otherwise process it.</p>
+ </section>
- <p>The specific value that the UA chooses for a Capability is referred to
- as a Setting. For example, if the application applies a ConstraintSet
- specifying that the framerate must be at least 30 frames per second, and no
- greater than 40, the Setting can be any intermediate value, e.g., 32, 35,
- or 37 frames per second. The application can query the current settings of
- the object's Capabilities via the <code><a class="internalDFN" href="#dfn-getsettings">getSettings()</a></code>
- accessor.</p>
+ <section rel="bibo:Chapter" resource="#ref" typeof="bibo:Chapter" id="conformance"><!--OddPage--><h2 id="h2_conformance" role="heading" aria-level="1"><span class="secno">2. </span>Conformance</h2>
+<p>
+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
+ and notes in this specification are non-normative. Everything else in this specification is
+ normative.
+</p>
+<p>
+ The key words <em title="MUST" class="rfc2119">MUST</em>, <em title="MUST NOT" class="rfc2119">MUST NOT</em>, <em title="REQUIRED" class="rfc2119">REQUIRED</em>, <em title="SHOULD" class="rfc2119">SHOULD</em>, <em title="SHOULD NOT" class="rfc2119">SHOULD NOT</em>, <em title="RECOMMENDED" class="rfc2119">RECOMMENDED</em>, <em title="MAY" class="rfc2119">MAY</em>,
+ and <em title="OPTIONAL" class="rfc2119">OPTIONAL</em> in this specification are to be interpreted as described in [<cite><a href="#bib-RFC2119" class="bibref">RFC2119</a></cite>].
+</p>
+
+ <p>This specification defines conformance criteria that apply to a single
+ product: the <dfn id="dfn-user-agent">user agent</dfn> that implements the interfaces that it
+ contains.</p>
+
+
+ <p>Implementations that use ECMAScript to implement the APIs defined in
+ this specification must implement them in a manner consistent with the
+ ECMAScript Bindings defined in the Web IDL specification [<cite><a href="#bib-WEBIDL" class="bibref">WEBIDL</a></cite>], as
+ this specification uses that specification and terminology.</p>
+ </section>
- <section id="interface-definition-1">
- <h3 id="h3_interface-definition-1" role="heading" aria-level="2"><span class="secno">11.1 </span>Interface Definition</h3>
+ <section id="terminology">
+ <!--OddPage--><h2 id="h2_terminology" role="heading" aria-level="1"><span class="secno">3. </span>Terminology</h2>
- <pre class="idl"><span class="idlInterface" id="idl-def-Constrainable">[<span class="extAttr">NoInterfaceObject</span>]
-interface <span class="idlInterfaceID">Constrainable</span> {
-<span class="idlMethod"> <span class="idlMethType"><a class="internalDFN" href="#dfn-capabilities">Capabilities</a></span> <span class="idlMethName"><a href="#widl-Constrainable-getCapabilities-Capabilities">getCapabilities</a></span> ();</span>
-<span class="idlMethod"> <span class="idlMethType"><a class="idlType" href="#idl-def-Constraints"><code>Constraints</code></a></span> <span class="idlMethName"><a href="#widl-Constrainable-getConstraints-Constraints">getConstraints</a></span> ();</span>
-<span class="idlMethod"> <span class="idlMethType"><a class="internalDFN" href="#dfn-settings">Settings</a></span> <span class="idlMethName"><a href="#widl-Constrainable-getSettings-Settings">getSettings</a></span> ();</span>
-<span class="idlMethod"> <span class="idlMethType">void</span> <span class="idlMethName"><a href="#widl-Constrainable-applyConstraints-void-Constraints-constraints-VoidFunction-successCallback-ConstraintErrorCallback-errorCallback">applyConstraints</a></span> (<span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-Constraints"><code>Constraints</code></a></span> <span class="idlParamName">constraints</span></span>, <span class="idlParam"><span class="idlParamType">VoidFunction</span> <span class="idlParamName">successCallback</span></span>, <span class="idlParam"><span class="idlParamType"><a class="idlType" href="#idl-def-ConstraintErrorCallback"><code>ConstraintErrorCallback</code></a></span> <span class="idlParamName">errorCallback</span></span>);</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType">EventHandler</span> <span class="idlAttrName"><a href="#widl-Constrainable-onoverconstrained">onoverconstrained</a></span>;</span>
-};</span></pre><section id="attributes-6"><h4 id="h4_attributes-6" role="heading" aria-level="3"><span class="secno">11.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Constrainable-onoverconstrained"><code>onoverconstrained</code> of type <span class="idlAttrType">EventHandler</span>, </dt><dd>This event handler, of type <code><a href="#event-constrainable-overconstrained">overconstrained</a></code>,
- <em title="must" class="rfc2119">must</em> be supported by all objects
- implementing the <code><a class="idlType" href="#idl-def-Constrainable"><code>Constrainable</code></a></code> interface.
-
- <p>The UA <em title="must" class="rfc2119">must</em> raise a
- <code>MediaErrorEvent</code> named "overconstrained" if changing
- circumstances at runtime result in the currently valid mandatory
- ConstraintSet no longer being satisfied. This MediaErrorEvent
- <em title="must" class="rfc2119">must</em> 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 satisfied. The <code>message</code>
- attribute of the MediaError <em title="SHOULD" class="rfc2119">SHOULD</em> 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 satisfies the constraints. The UA <em title="MAY" class="rfc2119">MAY</em> take
- other actions as a result of the overconstrained situation.</p></dd></dl></section><section id="methods-4"><h4 id="h4_methods-4" role="heading" aria-level="3"><span class="secno">11.1.2 </span>Methods</h4><dl class="methods"><dt id="widl-Constrainable-applyConstraints-void-Constraints-constraints-VoidFunction-successCallback-ConstraintErrorCallback-errorCallback"><code>applyConstraints</code></dt><dd>
-
+ <dl>
+ <dt><i>HTML Terms:</i>
+ </dt>
- <p>The <dfn id="dfn-applyconstraints">applyConstraints()</dfn> algorithm for applying
- constraints is stated below. Here are some preliminary definitions
- that are used in the statement of the algorithm:</p>
+ <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
+ [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>].</p>
- <ul>
- <li>We refer to each property/value pair in a ConstraintSet as a
- 'constraint' (since it is intended to constrain the corresponding
- Capability of the Constrainable object to a value that is within
- the range or list of values it specifies.)</li>
-
-
- <li>A set of values for the properties of an object O satisfy
- ConstraintSet C if each value a) is in the set of supported values
- specified by the corresponding Capability of O, and b) is in the
- range or list of values specified by the constraint in C that
- applies to that property, if there is one, and c) there is no
- constraint in C that does not correspond to a Capability in O.
- (Note that although this definition ignores the difference between
- mandatory and optional ConstraintSets, the algorithm below
- distinguishes between them.)</li>
-
-
- <li>A ConstraintSet C can be satisfied by an object O if it is
- possible to choose a sequence of values for the properties of O
- that satisfy C.</li>
-
-
- <li>To apply a set of ConstraintSet C to object O is to choose such
- a sequence of values that satisfy C and assign them as the settings
- for the properties of O.</li>
- </ul>
+ <p>The concepts <dfn id="dfn-queue-a-task"><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">queue a
+ task</a></dfn> and <dfn id="dfn-fires-a-simple-event"><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">fires
+ a simple event</a></dfn> are defined in [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>].</p>
- <p>When <code>applyConstraints</code> is called, the UA <em title="must" class="rfc2119">must</em> queue a task to run the following
- steps:</p>
+ <p>The terms <dfn id="dfn-event-handlers"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">event
+ handlers</a></dfn> and <dfn id="dfn-event-handler-event-types"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>].</p>
+ </dd>
- <ol>
- <li>let <var>desiredContraints</var> be the argument to this
- function. Each constraint <em title="must" class="rfc2119">must</em> specify one or more values (or a range of
- values) for its property. A property <em title="may" class="rfc2119">may</em> appear more than once in the list of optional
- ConstraintSets.</li>
+ <dt><dfn id="dfn-source">source</dfn>
+ </dt>
- <li>Let <var>newConstraints</var> be an initially
- empty Constraints dictionary. Let <var>existingConstraints</var>
- be the Constraints currently in effect (i.e. what is returned by
- <code>getConstraints</code>.)</li>
+ <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>
- <li>Let <var>object</var> be the Constrainable object on which this
- method was called. Let <var>copy</var> be an unconstrained copy of
- <var>object</var> (i.e., <var>copy</var> should behave as if it
- were <var>object</var> with all ConstraintSets removed.)</li>
+ <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>
- <li>If the mandatory ConstraintSet in <var>desiredConstraints</var> is
- non-null and
- cannot be satisfied by <var>copy</var>, call the
- <code>errorCallback</code>, passing it a new
- <code>MediaError</code> with name
- <code>ConstraintNotSatisfied</code> and <code>constraintName</code>
- set to any of the mandatory constraints that could not be
- satisfied, and return. <var>existingConstraints</var> remain in
- effect in this case.</li>
+ <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>
- <li>Otherwise if the mandatory ConstraintSet is non-null, set
- it as the value of the 'mandatory' element in
- <var>newConstraints</var></li>
+ <p>Sources <strong>do not</strong> have constraints -- tracks
+ have constraints. When a source is connected to a track, it
+ must, possibly in combination with UA processing (e.g.,
+ downsampling), conform to the constraints present on that
+ track (or set of tracks).</p>
- <li>Iterate over the optional ConstraintSets in
- <var>desiredConstraints</var> in the order in which they were
- specified. For each ConstraintSet,if it and
- <var>newConstraints</var> together can be satisfied by
- <var>copy</var>, append it to the value of the 'optional' element in <var>newConstraints</var>. Otherwise,
- ignore it.</li>
+ <p>Sources will be released (un-attached) from a track when the track
+ is ended for any reason.</p>
- <li>In a single operation, remove <var>existingConstraints</var> from
- <var>object</var>, apply <var>newConstraints</var>, and fire the
- <code>successCallback</code>. From this point on until applyConstraints() is
- called successfully again, getConstraints() <em title="must" class="rfc2119">must</em> return <var>newConstraints</var>. Note: the UA
- <em title="MAY" class="rfc2119">MAY</em> modify the values of one or more properties of
- <var>object</var> at any time, as long as the resulting set of
- values satisfy the current set of constraints.</li>
- </ol>
- <table class="parameters"><tbody><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">constraints</td><td class="prmType"><code><a class="idlType" href="#idl-def-Constraints"><code>Constraints</code></a></code></td><td class="prmNullFalse"><span role="img" aria-label="False">✘</span></td><td class="prmOptFalse"><span role="img" aria-label="False">✘</span></td><td class="prmDesc">A new constraint structure to apply to this object.</td></tr><tr><td class="prmName">successCallback</td><td class="prmType"><code>VoidFunction</code></td><td class="prmNullFalse"><span role="img" aria-label="False">✘</span></td><td class="prmOptFalse"><span role="img" aria-label="False">✘</span></td><td class="prmDesc">Called if the mandatory ConstraintSet can be satisfied.</td></tr><tr><td class="prmName">errorCallback</td><td class="prmType"><code><a class="idlType" href="#idl-def-ConstraintErrorCallback"><code>ConstraintErrorCallback</code></a></coe></td><td class="prmNullFalse"><span role="img" aria-label="False">✘</span></td><td class="prmOptFalse"><span role="img" aria-label="False">✘</span></td><td class="prmDesc">Called if the mandatory ConstraintSet cannot be satisfied.</td></tr></tbody></table><div><em>Return type: </em><code>void</code></div></dd><dt id="widl-Constrainable-getCapabilities-Capabilities"><code>getCapabilities</code></dt><dd>
- <p>The <dfn id="dfn-getcapabilities">getCapabilities()</dfn> method returns the dictionary of
- the capabilities that the object supports.</p>
+ <p>On the <code><a class="idlType" href="#idl-def-MediaStreamTrack"><code>MediaStreamTrack</code></a></code> object, sources are
+ represented by a <code><a class="internalDFN" href="#dfn-sourcetype">sourceType</a></code> attribute. The behavior
+ of APIs associated with the source's capabilities and settings change
+ depending on the source type.</p>
- <div class="note"><div id="h_note_11" role="heading" aria-level="4" class="note-title"><span>Note</span></div><div class="">
- <p>It is possible that the underlying hardware may not exactly map
- to the range defined in the registry entry. Where this is possible,
- the entry <em title="should" class="rfc2119">should</em> define how
- to translate and scale the hardware's setting onto the values
- defined in the entry. For example, suppose that a registry entry
- defines a hypothetical fluxCapacitance capability that is defined
- to be the range from -10 (min) to 10 (max), but there are common
- hardware devices that support only values of "off" "medium" and
- "full". The registry entry might specify that for such hardware,
- the user agent should map the range value of -10 to "off", 10 to
- "full", and 0 to "medium". It might also indicate that given a
- ConstraintSet imposing a strict value of 3, the user agent should
- attempt to set the value of "medium" on the hardware, and and that
- <code><a class="internalDFN" href="#dfn-getsettings">getSettings()</a></code> should return a fluxCapacitance
- of 0, since that is the value defined as corresponding to
- "medium".</p>
- </div></div>
- <div><em>No parameters.</em></div><div><em>Return type: </em><code><a class="internalDFN" href="#dfn-capabilities">Capabilities</a></code></div></dd><dt id="widl-Constrainable-getConstraints-Constraints"><code>getConstraints</code></dt><dd>
- <p>The <dfn id="dfn-getconstraints">getConstraints()</dfn> method returns all the
- <code>ConstraintSets</code> that were applied to the object in the
- last successful call of <code>applyConstraints()</code>. The value
- <em title="must" class="rfc2119">must</em> contain only the
- ConstraintSets that were successfully applied, and it <em title="must" class="rfc2119">must</em> maintain the order that they were
- specified in.</p>
+ <p>Sources have <code><a class="internalDFN" href="#dfn-capabilities">capabilities</a></code> and
+ <code><a class="internalDFN" href="#dfn-settings">settings</a></code>. The capabilities and settings 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 track objects bound to
+ the same source ask for the same capability or setting information,
+ they will get back the same answer).</p>
+ </dd>
[4102 lines skipped]
Received on Wednesday, 19 February 2014 02:04:15 UTC