- From: CVS User cjenning <cvsmail@w3.org>
- Date: Sat, 01 Feb 2014 00:52:59 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor
In directory roscoe:/tmp/cvs-serv10837
Modified Files:
getusermedia.html
Log Message:
Added 20140130 archived version
--- /sources/public/2011/webrtc/editor/getusermedia.html 2013/12/26 03:19:20 1.26
+++ /sources/public/2011/webrtc/editor/getusermedia.html 2014/02/01 00:52:59 1.27
@@ -1,7 +1,6 @@
<!DOCTYPE html>
<html lang="en-us" typeof="bibo:Document " about="" property="dcterms:language" content="en">
<head>
- <meta name="generator" content="HTML Tidy for HTML5 (experimental) for Linux https://github.com/w3c/tidy-html5/tree/68a9e74">
<style>/* --- EXAMPLES --- */
div.example-title {
min-width: 7.5em;
@@ -341,10 +340,6 @@
<title>Media Capture and Streams</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
- <!--
- To publish this document, see instructions in README
- -->
-
<style>/*****************************************************************
@@ -456,21 +451,27 @@
.section dl.attrs dd, .section dl.eldef dd {
margin-bottom: 0;
}
-</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 id="respecDocument" role="document" class="h-entry"><div id="respecHeader" role="contentinfo" class="head">
+@media print {
+ .removeOnSave {
+ 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>
+
+<body class="h-entry" style="" role="document" id="respecDocument"><div class="head" role="contentinfo" id="respecHeader">
<p>
- <a href="http://www.w3.org/"><img src="https://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a>
+ <a href="http://www.w3.org/"><img width="72" height="48" src="https://www.w3.org/Icons/w3c_home" alt="W3C"></a>
</p>
<h1 class="title p-name" id="title" property="dcterms:title">Media Capture and Streams</h1>
- <h2 id="w3c-editor-s-draft-25-december-2013" property="dcterms:issued" datatype="xsd:dateTime" content="2013-12-26T01:13:15.000Z"><acronym title="World Wide Web Consortium">W3C</acronym> Editor's Draft <time class="dt-published" datetime="2013-12-25">25 December 2013</time></h2>
+ <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>
<dl>
<dt>This version:</dt>
- <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>
+ <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>
<dt>Latest published version:</dt>
<dd><a href="http://www.w3.org/TR/mediacapture-streams/">http://www.w3.org/TR/mediacapture-streams/</a></dd>
@@ -483,7 +484,7 @@
<dt>Previous editor's draft:</dt>
- <dd><a href="http://dev.w3.org/2011/webrtc/editor/archives/20131105/getusermedia.html">http://dev.w3.org/2011/webrtc/editor/archives/20131105/getusermedia.html</a></dd>
+ <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>
@@ -511,10 +512,13 @@
<hr>
</div>
- <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>
+ <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>
@@ -527,7 +531,8 @@
<p>This document is not complete. It is subject to major changes and, while
early experimentations are encouraged, it is therefore not intended for
- implementation. The API is based on preliminary work done in the WHATWG.</p>
+ implementation. The API is based on preliminary work done in the
+ WHATWG.</p>
<p>
This document was published by the <a href="http://www.w3.org/2011/04/webrtc/">Web Real-Time Communication Working Group</a> and <a href="http://www.w3.org/2009/dap">Device APIs Working Group</a> as an Editor's Draft.
@@ -578,3403 +583,523 @@
-
-</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"href="#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"><pan 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="#navigatorusermediauccesscallback"><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>Constrinable 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><li class="tocline"><a class="tocxref" href="#capabilities-constraints-and-settings"><span class="secno">11.1.4 </span>Capabilities, Constraints, and Settings</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#registry"><span class="secno">11.1.4.1 </span>The Property Registry</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#propertyvaluerange"><span class="secno">11.1.4.1.1 </span>PropertyValueRange</a><ul class"toc"><li class="tocline"><a class="tocxref" href="#dictionary-propertyvaluerange-members"><span class="secno">11.1.4.1.1.1 </span>Dictionary <span class="formerLink"><code>PropertyValueRange</code></span> Members</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#capabilities"><span class="secno">11.1.4.2 </span>Capabilities</a></li><li class="tocline"><a class="tocxref" href="#settings"><span class="secno">11.1.4.3 </span>Settings</a></li><li class="tocline"><a class="tocxref" href="#constraints"><span class="secno">11.1.4.4 </span>Constraints</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-constraints-members"><span class="secno">11.1.4.4.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.1.4.4.2 </span>ConstraintSet</a></li><li class="tocline"><a class="tocxref" href="#constraint"><span class="secno">11.1.4.4.3 </span>Constraint<a></li></ul></li></ul></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="#acknowledgements"><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></l></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>
- <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>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>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>
-
-<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="terminology">
- <!--OddPage--><h2 id="h2_terminology" role="heading" aria-level="1"><span class="secno">3. </span>Terminology</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>
+
+
+ <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>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>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>
- <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 [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>].
- </p>
- <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>
- 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>
+ <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>
- <dt><dfn 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 class="idlType" href="#idl-def-MediaStreamTrack"><code>MediaStreamTrack</code></a></code> object,
- sources are represented by a <code>sourceType</code>
- attribute. The behavior of APIs associated with the source's
- capabilities and settings change depending on the source
- type.</p>
-
- <p>Sources have <code><a class="internalDFN" href="#dfn-capabilities">capabilities</a></code>
- and <code>settings</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>
-
- <dt><dfn id="dfn-state" title="state">Setting (Source Setting)</dfn></dt>
- <dd>
- <p>A setting refers to the immediate, current value of the
- source's (optionally constrained) capabilities. Settings are
- always read-only.</p>
- <p>A source's settings can change dynamically over time due to
- environmental conditions, sink configurations, or constraint
- changes. A source's settings 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 settings are 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
- a source's settings have changed.</p>
- <p>A conforming user-agent <em title="must" class="rfc2119">must</em> support all the setting 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 setting, 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 settings (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
- settings from the full ranges of its supported capabilities, and
- to adjust those settings 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>
+ <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
[3529 lines skipped]
Received on Saturday, 1 February 2014 00:53:05 UTC