--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/media-stream-capture/proposals/SettingsAPI_proposal_v4.html Tue Oct 02 18:05:58 2012 -0700
@@ -0,0 +1,1206 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+<head>
+ <title>Proposal: Settings API Version 4</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+
+
+ <style>/*****************************************************************
+ * ReSpec 3 CSS
+ * Robin Berjon - http://berjon.com/
+ *****************************************************************/
+
+/* --- INLINES --- */
+em.rfc2119 {
+ text-transform: lowercase;
+ font-variant: small-caps;
+ font-style: normal;
+ color: #900;
+}
+
+h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
+h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
+ border: none;
+}
+
+dfn {
+ font-weight: bold;
+}
+
+a.internalDFN {
+ color: inherit;
+ border-bottom: 1px solid #99c;
+ text-decoration: none;
+}
+
+a.externalDFN {
+ color: inherit;
+ border-bottom: 1px dotted #ccc;
+ text-decoration: none;
+}
+
+a.bibref {
+ text-decoration: none;
+}
+
+cite .bibref {
+ font-style: normal;
+}
+
+code {
+ color: #ff4500;
+}
+
+
+/* --- --- */
+ol.algorithm { counter-reset:numsection; list-style-type: none; }
+ol.algorithm li { margin: 0.5em 0; }
+ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
+
+/* --- TOC --- */
+.toc a, .tof a {
+ text-decoration: none;
+}
+
+a .secno, a .figno {
+ color: #000;
+}
+
+ul.tof, ol.tof {
+ list-style: none outside none;
+}
+
+.caption {
+ margin-top: 0.5em;
+ font-style: italic;
+}
+
+/* --- TABLE --- */
+table.simple {
+ border-spacing: 0;
+ border-collapse: collapse;
+ border-bottom: 3px solid #005a9c;
+}
+
+.simple th {
+ background: #005a9c;
+ color: #fff;
+ padding: 3px 5px;
+ text-align: left;
+}
+
+.simple th[scope="row"] {
+ background: inherit;
+ color: inherit;
+ border-top: 1px solid #ddd;
+}
+
+.simple td {
+ padding: 3px 10px;
+ border-top: 1px solid #ddd;
+}
+
+.simple tr:nth-child(even) {
+ background: #f0f6ff;
+}
+
+/* --- DL --- */
+.section dd > p:first-child {
+ margin-top: 0;
+}
+
+.section dd > p:last-child {
+ margin-bottom: 0;
+}
+
+.section dd {
+ margin-bottom: 1em;
+}
+
+.section dl.attrs dd, .section dl.eldef dd {
+ margin-bottom: 0;
+}
+</style><style>/* --- ISSUES/NOTES --- */
+div.issue-title, div.note-title {
+ padding-right: 1em;
+ min-width: 7.5em;
+ color: #b9ab2d;
+}
+div.issue-title { color: #e05252; }
+div.note-title { color: #52e052; }
+div.issue-title span, div.note-title span {
+ text-transform: uppercase;
+}
+div.note, div.issue {
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+.note > p:first-child, .issue > p:first-child { margin-top: 0 }
+.issue, .note {
+ padding: .5em;
+ border-left-width: .5em;
+ border-left-style: solid;
+}
+div.issue, div.note {
+ padding: 0.5em;
+ margin: 1em 0;
+ position: relative;
+ clear: both;
+}
+span.note, span.issue { padding: .1em .5em .15em; }
+
+.issue {
+ border-color: #e05252;
+ background: #fbe9e9;
+}
+.note {
+ border-color: #52e052;
+ background: #e9fbe9;
+}
+
+
+</style><style>/* --- WEB IDL --- */
+pre.idl {
+ border-top: 1px solid #90b8de;
+ border-bottom: 1px solid #90b8de;
+ padding: 1em;
+ line-height: 120%;
+}
+
+pre.idl::before {
+ content: "WebIDL";
+ display: block;
+ width: 150px;
+ background: #90b8de;
+ color: #fff;
+ font-family: initial;
+ padding: 3px;
+ font-weight: bold;
+ margin: -1em 0 1em -1em;
+}
+
+.idlType {
+ color: #ff4500;
+ font-weight: bold;
+ text-decoration: none;
+}
+
+/*.idlModule*/
+/*.idlModuleID*/
+/*.idlInterface*/
+.idlInterfaceID, .idlDictionaryID, .idlCallbackID, .idlEnumID {
+ font-weight: bold;
+ color: #005a9c;
+}
+
+.idlSuperclass {
+ font-style: italic;
+ color: #005a9c;
+}
+
+/*.idlAttribute*/
+.idlAttrType, .idlFieldType, .idlMemberType {
+ color: #005a9c;
+}
+.idlAttrName, .idlFieldName, .idlMemberName {
+ color: #ff4500;
+}
+.idlAttrName a, .idlFieldName a, .idlMemberName a {
+ color: #ff4500;
+ border-bottom: 1px dotted #ff4500;
+ text-decoration: none;
+}
+
+/*.idlMethod*/
+.idlMethType, .idlCallbackType {
+ color: #005a9c;
+}
+.idlMethName {
+ color: #ff4500;
+}
+.idlMethName a {
+ color: #ff4500;
+ border-bottom: 1px dotted #ff4500;
+ text-decoration: none;
+}
+
+/*.idlParam*/
+.idlParamType {
+ color: #005a9c;
+}
+.idlParamName {
+ font-style: italic;
+}
+
+.extAttr {
+ color: #666;
+}
+
+/*.idlConst*/
+.idlConstType {
+ color: #005a9c;
+}
+.idlConstName {
+ color: #ff4500;
+}
+.idlConstName a {
+ color: #ff4500;
+ border-bottom: 1px dotted #ff4500;
+ text-decoration: none;
+}
+
+/*.idlException*/
+.idlExceptionID {
+ font-weight: bold;
+ color: #c00;
+}
+
+.idlTypedefID, .idlTypedefType {
+ color: #005a9c;
+}
+
+.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
+ color: #c00;
+ font-weight: normal;
+}
+
+.excName a {
+ font-family: monospace;
+}
+
+.idlRaises a.idlType, .excName a.idlType {
+ border-bottom: 1px dotted #c00;
+}
+
+.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
+ width: 45px;
+ text-align: center;
+}
+.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
+.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
+
+.idlImplements a {
+ font-weight: bold;
+}
+
+dl.attributes, dl.methods, dl.constants, dl.fields, dl.dictionary-members {
+ margin-left: 2em;
+}
+
+.attributes dt, .methods dt, .constants dt, .fields dt, .dictionary-members dt {
+ font-weight: normal;
+}
+
+.attributes dt code, .methods dt code, .constants dt code, .fields dt code, .dictionary-members dt code {
+ font-weight: bold;
+ color: #000;
+ font-family: monospace;
+}
+
+.attributes dt code, .fields dt code, .dictionary-members dt code {
+ background: #ffffd2;
+}
+
+.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
+ color: #005a9c;
+ background: transparent;
+ font-family: inherit;
+ font-weight: normal;
+ font-style: italic;
+}
+
+.methods dt code {
+ background: #d9e6f8;
+}
+
+.constants dt code {
+ background: #ddffd2;
+}
+
+.attributes dd, .methods dd, .constants dd, .fields dd, .dictionary-members dd {
+ margin-bottom: 1em;
+}
+
+table.parameters, table.exceptions {
+ border-spacing: 0;
+ border-collapse: collapse;
+ margin: 0.5em 0;
+ width: 100%;
+}
+table.parameters { border-bottom: 1px solid #90b8de; }
+table.exceptions { border-bottom: 1px solid #deb890; }
+
+.parameters th, .exceptions th {
+ color: #fff;
+ padding: 3px 5px;
+ text-align: left;
+ font-family: initial;
+ font-weight: normal;
+ text-shadow: #666 1px 1px 0;
+}
+.parameters th { background: #90b8de; }
+.exceptions th { background: #deb890; }
+
+.parameters td, .exceptions td {
+ padding: 3px 10px;
+ border-top: 1px solid #ddd;
+ vertical-align: top;
+}
+
+.parameters tr:first-child td, .exceptions tr:first-child td {
+ border-top: none;
+}
+
+.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
+ width: 100px;
+}
+
+.parameters td.prmType {
+ width: 120px;
+}
+
+table.exceptions table {
+ border-spacing: 0;
+ border-collapse: collapse;
+ width: 100%;
+}
+</style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet"><!--[if lt IE 9]><script src='undefined://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
+ <body><div class="head">
+ <p>
+
+ <a href="http://www.w3.org/"><img width="72" height="48" alt="W3C" src="http://www.w3.org/Icons/w3c_home"></a>
+
+ </p>
+ <h1 class="title" id="title">Proposal: Settings API Version 4</h1>
+
+ <dl>
+ <dt>Author:</dt>
+ <dd><span>Travis Leithead</span>, <a href="http://www.microsoft.com/">Microsoft</a></dd>
+ </dl>
+
+ <p class="copyright">
+ <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
+ 2012
+
+ <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
+ (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
+ <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
+ <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
+ <abbr title="World Wide Web Consortium">W3C</abbr> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
+ <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and
+ <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.
+ </p>
+
+
+ <hr>
+</div>
+ <section class="introductory" id="abstract"><h2>Abstract</h2><p>
+ This proposal describes additions and suggested changes to the
+ <a href="http://dev.w3.org/2011/webrtc/editor/getusermedia.html">Media Capture and Streams</a>
+ specification in order to support the goal of device settings retrieval and modification. This proposal incorporates
+ <a href="http://lists.w3.org/Archives/Public/public-media-capture/2012Oct/0001.html">feedback</a> from three prior proposals with the same goal
+ [<a href="http://lists.w3.org/Archives/Public/public-media-capture/2012Aug/0143.html">v3</a>]
+ [<a href="http://lists.w3.org/Archives/Public/public-media-capture/2012Aug/0066.html">v2</a>]
+ [<a href="http://lists.w3.org/Archives/Public/public-media-capture/2012Jul/0069.html">v1</a>].
+ </p></section>
+
+
+<section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#remove-localmediastream-interface"><span class="secno">1. </span>Remove <code>LocalMediaStream</code> interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#rationale"><span class="secno">1.1 </span>Rationale</a></li></ul></li><li class="tocline"><a class="tocxref" href="#new-mediastreamtrack-derived-types"><span class="secno">2. </span>New <code>MediaStreamTrack</code> (derived) types</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#local-and-remote-video-tracks"><span class="secno">2.1 </span>Local and remote video tracks</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#videostreamtrack-interface"><span class="secno">2.1.1 </span><code>VideoStreamTrack</code> interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#local-and-remote-audio-tracks"><span class="secno">2.2 </span>Local and remote audio tracks</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#audiostreamtrack-interface"><span class="secno">2.2.1 </span><code>AudioStreamTrack</code> interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#camera-device-tracks"><span class="secno">2.3 </span>Camera device tracks</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#videodevicetrack-interface"><span class="secno">2.3.1 </span><code>VideoDeviceTrack</code> interface</a></li><li class="tocline"><a class="tocxref" href="#videofacingenum-enumeration"><span class="secno">2.3.2 </span><code>VideoFacingEnum</code> enumeration</a></li></ul></li><li class="tocline"><a class="tocxref" href="#cameras-with-high-resolution-picture-modes"><span class="secno">2.4 </span>Cameras with "high-resolution picture" modes</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#picturedevicetrack-interface"><span class="secno">2.4.1 </span><code>PictureDeviceTrack</code> interface</a></li><li class="tocline"><a class="tocxref" href="#pictureevent-interface"><span class="secno">2.4.2 </span><code>PictureEvent</code> interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#microphone-device-tracks"><span class="secno">2.5 </span>Microphone device tracks</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#audiodevicetrack-interface"><span class="secno">2.5.1 </span><code>AudioDeviceTrack</code> interface</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#settings-retrieval-application"><span class="secno">3. </span>Settings Retrieval/Application</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#grouping-setting-features"><span class="secno">3.1 </span>Grouping setting features</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#mediasettingsrange-interface"><span class="secno">3.1.1 </span><code>MediaSettingsRange</code> interface</a></li><li class="tocline"><a class="tocxref" href="#mediasettingslist-interface"><span class="secno">3.1.2 </span><code>MediaSettingsList</code> interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#basic-settings-for-pictures-and-video-devices"><span class="secno">3.2 </span>Basic settings for pictures and video devices</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#pictureandvideosettings-mix-in-interface"><span class="secno">3.2.1 </span><code>PictureAndVideoSettings</code> mix-in interface</a></li><li class="tocline"><a class="tocxref" href="#videodimensiondict-dictionary"><span class="secno">3.2.2 </span><code>VideoDimensionDict</code> dictionary</a></li><li class="tocline"><a class="tocxref" href="#videofocusmodeenum-enumeration"><span class="secno">3.2.3 </span><code>VideoFocusModeEnum</code> enumeration</a></li><li class="tocline"><a class="tocxref" href="#videofilllightmodeenum-enumeration"><span class="secno">3.2.4 </span><code>VideoFillLightModeEnum</code> enumeration</a></li></ul></li><li class="tocline"><a class="tocxref" href="#expanded-settings-for-video-devices"><span class="secno">3.3 </span>Expanded settings for video devices</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#videodevicetrack-partial-interface"><span class="secno">3.3.1 </span><code>VideoDeviceTrack</code> partial interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#settings-for-audio-devices"><span class="secno">3.4 </span>Settings for audio devices</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#audiodevicetrack-partial-interface"><span class="secno">3.4.1 </span><code>AudioDeviceTrack</code> partial interface</a></li></ul></li><li class="tocline"><a class="tocxref" href="#tracking-the-result-of-constraint-application"><span class="secno">3.5 </span>Tracking the result of constraint application</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#mediaconstraintresulteventhandlers-mix-in-interface"><span class="secno">3.5.1 </span><code>MediaConstraintResultEventHandlers</code> mix-in interface</a></li><li class="tocline"><a class="tocxref" href="#constrainterrorevent-interface"><span class="secno">3.5.2 </span><code>ConstraintErrorEvent</code> interface</a></li><li class="tocline"><a class="tocxref" href="#constrainterroreventinit-dictionary"><span class="secno">3.5.3 </span><code>ConstraintErrorEventInit</code> dictionary</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#device-lists"><span class="secno">4. </span>Device Lists</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#mediadevicelist-interface"><span class="secno">4.1 </span><code>MediaDeviceList</code> interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes"><span class="secno">4.1.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods"><span class="secno">4.1.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#deviceevent-interface"><span class="secno">4.2 </span><code>DeviceEvent</code> interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-1"><span class="secno">4.2.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#deviceeventinit-dictionary"><span class="secno">4.3 </span><code>DeviceEventInit</code> dictionary</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#dictionary-deviceeventinit-members"><span class="secno">4.3.1 </span>Dictionary <span class="formerLink"><code>DeviceEventInit</code></span> Members</a></li></ul></li><li class="tocline"><a class="tocxref" href="#devicelistaccess-mix-in-interface"><span class="secno">4.4 </span><code>DeviceListAccess</code> mix-in interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-2"><span class="secno">4.4.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#constraints-for-navigator.getusermedia-mediadevicelist.select"><span class="secno">5. </span>Constraints for navigator.getUserMedia/MediaDeviceList.select</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#video-constraints"><span class="secno">5.1 </span>Video Constraints</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#videoconstraints-dictionary"><span class="secno">5.1.1 </span><code>VideoConstraints</code> dictionary</a></li></ul></li><li class="tocline"><a class="tocxref" href="#audio-constraints"><span class="secno">5.2 </span>Audio Constraints</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#audioconstraints-dictionary"><span class="secno">5.2.1 </span><code>AudioConstraints</code> dictionary</a></li></ul></li><li class="tocline"><a class="tocxref" href="#common-sub-constraint-structures"><span class="secno">5.3 </span>Common sub-constraint structures</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#minmaxulongsubconstraint-dictionary"><span class="secno">5.3.1 </span><code>MinMaxULongSubConstraint</code> dictionary</a></li><li class="tocline"><a class="tocxref" href="#minmaxfloatsubconstraint-dictionary"><span class="secno">5.3.2 </span><code>MinMaxFloatSubConstraint</code> dictionary</a></li><li class="tocline"><a class="tocxref" href="#videoorientationenum-enumeration"><span class="secno">5.3.3 </span><code>VideoOrientationEnum</code> enumeration</a></li></ul></li></ul></li></ul></section>
+
+ <section id="remove-localmediastream-interface">
+ <!--OddPage--><h2><span class="secno">1. </span>Remove <code>LocalMediaStream</code> interface</h2>
+ <p>In this proposal, the derived LocalMediaStream interface is removed. Rather than returning a LocalMediaStream
+ instance in the NavigatorUserMediaSuccessCallback, a vanilla MediaStream object is returned. The primary difference
+ is in the tracks contained in that MediaStream object.
+ </p>
+
+ <section id="rationale">
+ <h3><span class="secno">1.1 </span>Rationale</h3>
+
+ The LocalMediaStream object currently extends MediaStream by adding a single method "stop()". In my prior proposals, this
+ object was radically altered in order to facilite several goals:
+ <dl>
+ <dt>Provide a predicatable home for developers to find and modify device settings</dt>
+ <dd>A previous proposal went out of its way to strongly associate LocalMediaStream objects with devices. This
+ seemed like a good design because local device configuration is always on the local media stream. This made
+ for a stable, dependable API surface for all local media stream instances (no guesswork).
+ </dd>
+ <dt>Prevent track-list mutations</dt>
+ <dd>A previous proposal also removed the track lists on local media streams (resulting in some dramatic inheritence
+ changes). Mutable tracks lists on LocalMediaStream objects seemed like the wrong design considering the current
+ thinking that a getUserMedia request would only ever produce a LocalMediaStream with at most one audio or video
+ track.
+ </dd>
+ </dl>
+
+ <p>Some feedback even suggested re-considering the "at most one video/audio track per request to getUserMedia".</p>
+
+ <p>While thinking about these goals and the feedback, I began to consider a few things:</p>
+
+ <dl>
+ <dt>Device-centric tracks</dt>
+ <dd>With tracks supplemented with device-characteristics (duck-typing), the LocalMediaStream's stop() API was a
+ convenience feature for stopping all tracks backed by a device on the LocalMediaStream object. With device-
+ centric tracks a stop() API should be present on the tracks themselves.
+ </dd>
+ <dt>Mutable track lists</dt>
+ <dd>Mutable track lists were not a desireable feature while I was locked into considering the LocalMediaStream
+ as strongly associated with device-control. What is actually necessary, is that there is a something immutable
+ associated with devices--that "something" doesn't necessarily need to be a LocalMediaStream or any MediaStream-like
+ object at all! Once I unlocked that line of thinking, I began to experiement with the notion of a device list
+ which then ultimately brought back a use-case for having mutable track lists for MediaStream objects. (It did not
+ bring back a need for LocalMediaStream objects themselves though.)
+ </dd>
+ <dt>Workflow for access to additional device streams</dt>
+ <dd>It is now understood that to request additional streams for different devices (e.g., the second camera on a
+ dual-camera mobile phone), one must invoke getUserMedia a second time. In my prior proposal, this would result
+ in a separate LocalMediaStream instance. At this point there are two LocalMediaStream objects each with their
+ own devices. While this was nice for consistency of process, it was a challenge in terms of use of the objects
+ with a MediaStream consumer like the Video tag.
+
+ <p>To illustrate this challenge, consider how my prior proposal required a re-hookup of the MediaStream
+ to a video tag consumer:</p>
+
+ <ol>
+ <li>First request to getUserMedia</li>
+ <li>LocalMediaStream (1) obtained from success callback</li>
+ <li>createObjectURL and preview in a video tag</li>
+ <li>Second call to getUserMedia</li>
+ <li>LocalMediaStream (2) obtained from success callback</li>
+ <li>createObjectURL and preview in same video tag</li>
+ </ol>
+
+ <p>Note that this process has to bind a completely new LocalMediaStream to the video tag a second time (if
+ re-using the same video tag) only because the second LocalMediaStream object was different than the
+ first.</p>
+
+ <p>It is much more efficient for developer code to simply add/remove tracks to a MediaStream that are
+ relevant, without needing to change the consumer of the MediaStream.</p>
+ </dd>
+ <dt>Usage of getUserMedia for permission rather than for additional device access</dt>
+ <dd>The getUserMedia method is the gateway for permission to media. This proposal does not suggest
+ changing that concept. It <em>does</em> suggest, however, that more information can be made available for
+ discovery of additional devices within the approved "category" or "type" of media, and provide a way to
+ obtain those additional devices without needing to go through the "permissions" route (i.e., getUserMedia).
+ </dd>
+ <dt>Importance of restricting control to LocalMediaStream</dt>
+ <dd>Upon reflection of the feedback around the prior proposal, the relative importance of restricting control
+ of the devices associated with tracks on the LocalMediaStream to <em>only</em> the LocalMediaStream did not
+ seem as vital, insofar as the device-level access via the track is not directly available through a
+ PeerConnection to a remote browser.
+ </dd>
+ </dl>
+ </section>
+ </section>
+
+ <section id="new-mediastreamtrack-derived-types">
+ <!--OddPage--><h2><span class="secno">2. </span>New <code>MediaStreamTrack</code> (derived) types</h2>
+
+ <p>This proposal consolidates settings directly into the tracks that are provided by devices. However, in order to
+ do this efficiently and in a future-extendible manner, the highly-generic MediaStreamTrack is now extended for
+ specific characteristics of the devices it embodies, resulting in a hierarchy:
+ </p>
+
+ <ul>
+ <li>MediaStreamTrack
+ <ul>
+ <li>VideoStreamTrack
+ <ul>
+ <li>VideoDeviceTrack</li>
+ <li>PictureDeviceTrack</li>
+ </ul>
+ </li>
+ <li>AudioStreamTrack
+ <ul>
+ <li>AudioDeviceTrack</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+ <section id="local-and-remote-video-tracks">
+ <h3><span class="secno">2.1 </span>Local and remote video tracks</h3>
+
+ <p>MediaStreamTrack objects that are of <code>kind</code> "video" and that are located in a MediaStream's
+ <code>videoTracks</code> list will be instances of a <code>VideoStreamTrack</code>. The VideoStreamTrack
+ provides basic (read-only) properties pertinent to all sources of video.
+ </p>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>There is no takePicture API on a VideoStreamTrack because a simple frame-grab can be accomplished using a
+ combination of a <video> and <canvas> APIs (takePicture is intended for use with a camera's high-resolution
+ picture mode, not for arbitrary video frame capture).
+ </p></div>
+
+ <p>I'm intentionally keeping this interface as sparce as possible. Features about the video that can be calculated like
+ aspect ratio are not provided.
+ </p>
+
+ <section id="videostreamtrack-interface">
+ <h4><span class="secno">2.1.1 </span><code>VideoStreamTrack</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-VideoStreamTrack">interface <span class="idlInterfaceID">VideoStreamTrack</span> : <span class="idlSuperclass"><a>MediaStreamTrack</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-VideoStreamTrack-width">width</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-VideoStreamTrack-height">height</a></span>;</span>
+};</span></pre><section><h5 id="attributes-3">Attributes</h5><dl class="attributes"><dt id="widl-VideoStreamTrack-width"><code>width</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The "natural" width (in pixels) of the video flowing through the track. In the case of a VideoDeviceTrack, this
+ value represents the current setting of the camera's sensor (still in terms of number of pixels). This value is
+ indpendent of the camera's rotation (if the camera's rotation setting is changed, it does not impact this value).
+ For example, consider a camera setting with width of 1024 pixels and height of 768 pixels. If the camera's rotation
+ setting is changed by 90 degrees, the width is still reported as 1024 pixels. However, a <video> element used
+ to preview this track would report a width of 768 pixels (the effective width with rotation factored in).
+ </dd><dt id="widl-VideoStreamTrack-height"><code>height</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The "natural" height (in pixels) of the video in this track. See the "width" attribute for additional info.</dd></dl></section>
+ </section>
+ </section>
+
+ <section id="local-and-remote-audio-tracks">
+ <h3><span class="secno">2.2 </span>Local and remote audio tracks</h3>
+
+ <p>MediaStreamTrack objects that are of <code>kind</code> "audio" and that are located in a MediaStream's
+ <code>audioTracks</code> list will be instances of an <code>AudioStreamTrack</code>. The AudioStreamTrack
+ provides basic (read-only) properties pertinent to all sources of audio.
+ </p>
+
+ <section id="audiostreamtrack-interface">
+ <h4><span class="secno">2.2.1 </span><code>AudioStreamTrack</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-AudioStreamTrack">interface <span class="idlInterfaceID">AudioStreamTrack</span> : <span class="idlSuperclass"><a>MediaStreamTrack</a></span> {
+};</span></pre>
+ </section>
+ </section>
+
+ <section id="camera-device-tracks">
+ <h3><span class="secno">2.3 </span>Camera device tracks</h3>
+
+ <p>VideoDeviceTracks are created by the user agent to represent a camera device that provides local video.</p>
+
+ <section id="videodevicetrack-interface">
+ <h4><span class="secno">2.3.1 </span><code>VideoDeviceTrack</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-VideoDeviceTrack">interface <span class="idlInterfaceID">VideoDeviceTrack</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-VideoStreamTrack"><code>VideoStreamTrack</code></a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-PictureDeviceTrack"><code>PictureDeviceTrack</code></a>?</span> <span class="idlAttrName"><a href="#widl-VideoDeviceTrack-pictureTrack">pictureTrack</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFacingEnum"><code>VideoFacingEnum</code></a></span> <span class="idlAttrName"><a href="#widl-VideoDeviceTrack-facing">facing</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-VideoDeviceTrack-stop-void">stop</a></span> ();</span>
+};</span></pre><section><h5 id="attributes-4">Attributes</h5><dl class="attributes"><dt id="widl-VideoDeviceTrack-pictureTrack"><code>pictureTrack</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-PictureDeviceTrack"><code>PictureDeviceTrack</code></a></span>, readonly, nullable</dt><dd>If the device providing this VideoDeviceTrack supports a "high-resolution picture mode", this
+ attribute will be reference to a PictureDeviceTrack object. Otherwise, this attribute will be null.
+ </dd><dt id="widl-VideoDeviceTrack-facing"><code>facing</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFacingEnum"><code>VideoFacingEnum</code></a></span>, readonly</dt><dd>From the user's perspective, this attribute describes whether this camera is pointed toward the
+ user ("user") or away from the user ("environment"). If this information cannot be reliably obtained,
+ for example from a USB external camera, the value "unknown" is returned.
+ </dd></dl></section><section><h5 id="methods-1">Methods</h5><dl class="methods"><dt id="widl-VideoDeviceTrack-stop-void"><code>stop</code></dt><dd>Causes this track to enter the <code>ENDED</code> state. Same behavior of the old LocalMediaStream's
+ stop API, but only affects this device track.<div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+
+ <section id="videofacingenum-enumeration">
+ <h4><span class="secno">2.3.2 </span><code>VideoFacingEnum</code> enumeration</h4>
+ <pre class="idl"><span class="idlEnum" id="idl-def-VideoFacingEnum">enum <span class="idlEnumID">VideoFacingEnum</span> {
+ "<span class="idlEnumItem">unknown</span>",
+ "<span class="idlEnumItem">user</span>",
+ "<span class="idlEnumItem">environment</span>"
+};</span></pre><table class="simple"><tr><th colspan="2">Enumeration description</th></tr><tr><td><code>unknown</code></td><td>The relative directionality of the camera cannot be determined by the user agent based on the hardware.</td></tr><tr><td><code>user</code></td><td>The camera is facing toward the user (a self-view camera).</td></tr><tr><td><code>environment</code></td><td>The camera is facing away from the user (viewing the environment).</td></tr></table>
+ </section>
+ </section>
+
+ <section id="cameras-with-high-resolution-picture-modes">
+ <h3><span class="secno">2.4 </span>Cameras with "high-resolution picture" modes</h3>
+
+ <p>The PictureDeviceTrack interface is created by the user agent if the camera device providing the VideoDeviceTrack
+ supports an optional "high-resolution picture mode" with picture settings different (better) from those of
+ its basic video constraints.</p>
+
+ <p>This track is initially available from a VideoDeviceTrack via the <code>pictureTrack</code> property. This track type
+ is not present in the video device list (<code>MediaDeviceList</code>). Likewise, it cannot be stopped directly, and
+ its VideoStreamTrack inherited attributes reflect the values of its "owning" VideoDeviceTrack.
+ </p>
+
+ <p>The PictureDeviceTrack is essentially a specialized VideoStreamTrack (this track type is of kind <code>"video"</code>).
+ It may be explicitly added to a videoTracks list (MediaStreamTrackList) in order to output its track video to a <video>
+ tag, but its preview video stream reflects the owning VideoDeviceTrack's settings, rather than the settings directly
+ available on this object. Rather the settings of this object are only applied at the time when the takePicture API is
+ invoked.
+ </p>
+
+ <section id="picturedevicetrack-interface">
+ <h4><span class="secno">2.4.1 </span><code>PictureDeviceTrack</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-PictureDeviceTrack">interface <span class="idlInterfaceID">PictureDeviceTrack</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-VideoStreamTrack"><code>VideoStreamTrack</code></a></span> {
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-PictureDeviceTrack-takePicture-void">takePicture</a></span> ();</span>
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-PictureDeviceTrack-onpicture">onpicture</a></span>;</span>
+};</span></pre><section><h5 id="attributes-5">Attributes</h5><dl class="attributes"><dt id="widl-PictureDeviceTrack-onpicture"><code>onpicture</code> of type <span class="idlAttrType"><a>EventHandler</a></span></dt><dd>Register/unregister for "picture" events. The handler should expect to get a PictureEvent object as its first
+ parameter.
+ <div class="issue"><div class="issue-title"><span>Issue 2</span></div><p>Is an "error" event necessary here too?</p></div>
+ </dd></dl></section><section><h5 id="methods-2">Methods</h5><dl class="methods"><dt id="widl-PictureDeviceTrack-takePicture-void"><code>takePicture</code></dt><dd>Temporarily mutes the owning VideoDeviceTrack's stream, then asynchronously switches the camera into "high
+ resolution picture mode", applies the PictureDeviceTrack settings (a snapshot from the time the takePicture
+ API was called, and records/encodes an image using a user-agent determined format into a Blob object.
+ Finally, queues a task to fire a "picture" event with the resulting Blob instance.
+ <div class="issue"><div class="issue-title"><span>Issue 1</span></div><p>Could consider providing a hint or setting for the desired picture format.</p></div>
+ <div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>In the previous proposal, the PictureEvent returned a Canvas ImageData object, however it makes
+ sense to return a compressed format (PNG/JPEG), especially given that picture snapshots will be very high
+ resolution, and ImageData objects are essentially raw images.
+ </p></div>
+
+ <section id="pictureevent-interface">
+ <h4><span class="secno">2.4.2 </span><code>PictureEvent</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-PictureEvent">[<span class="extAttr">Constructor(DOMString type, optional PictureEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">PictureEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>Blob</a></span> <span class="idlAttrName"><a href="#widl-PictureEvent-data">data</a></span>;</span>
+};</span></pre><section><h5 id="attributes-6">Attributes</h5><dl class="attributes"><dt id="widl-PictureEvent-data"><code>data</code> of type <span class="idlAttrType"><a>Blob</a></span>, readonly</dt><dd>Returns a Blob object whose type attribute indicates the encoding of the picture data. An implementation must
+ return a Blob in a format that is capable of being viewed in an HTML <img> tag.
+ </dd></dl></section>
+ </section>
+ </section>
+
+ <section id="microphone-device-tracks">
+ <h3><span class="secno">2.5 </span>Microphone device tracks</h3>
+
+ <p>AudioDeviceTracks are created by the user agent to represent a microphone device that provides local audio.</p>
+
+ <section id="audiodevicetrack-interface">
+ <h4><span class="secno">2.5.1 </span><code>AudioDeviceTrack</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-AudioDeviceTrack">interface <span class="idlInterfaceID">AudioDeviceTrack</span> : <span class="idlSuperclass"><a class="idlType" href="#idl-def-AudioStreamTrack"><code>AudioStreamTrack</code></a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-AudioDeviceTrack-level">level</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-AudioDeviceTrack-stop-void">stop</a></span> ();</span>
+};</span></pre><section><h5 id="attributes-7">Attributes</h5><dl class="attributes"><dt id="widl-AudioDeviceTrack-level"><code>level</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The sensitivity of the microphone. This value must be a whole number between 0 and 100 inclusive.
+ When a MediaStreamTrack is muted, the level attribute must return 0. A value of 100 means the microphone
+ is configured for maximum gain.
+ </dd></dl></section><section><h5 id="methods-3">Methods</h5><dl class="methods"><dt id="widl-AudioDeviceTrack-stop-void"><code>stop</code></dt><dd>Causes this track to enter the <code>ENDED</code> state. Same behavior of the old LocalMediaStream's stop
+ API, but only for this device track.<div><em>No parameters.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+ </section>
+
+ </section>
+
+ <section id="settings-retrieval-application">
+ <!--OddPage--><h2><span class="secno">3. </span>Settings Retrieval/Application</h2>
+
+ <p>As noted in prior proposals, camera/microphone settings must be applied asynchronously to ensure that web
+ applications can remain responsive for all device types that may not respond quickly to setting changes.
+ </p>
+
+ <p>My prior proposals used a monolithic dictionary of settings for inspection and application. This proposal takes a
+ different approach, considering the feedback for more-direct access to settings, expected patterns for settings
+ adjustment (which is generally one setting at at time as initiated by a web application UI), difficulties in
+ understanding what values were read-only vs. writable, and the current already-defined constraint application
+ engine.</p>
+
+ <section id="grouping-setting-features">
+ <h3><span class="secno">3.1 </span>Grouping setting features</h3>
+
+ <p>Settings are organized into two groups: value ranges (a continuum of values) and enumerated values. Value ranges
+ include a min and max value, while enumerated values are provided in an array with an associated length.
+ Both groups of settings include an "initial" value, which is the value that is expected to be the device's
+ default value when it is acquired.
+ </p>
+
+ <p>The key to changing settings in either setting group is the request() API. This is the mechanism for asynchronously
+ requesting that the device change the value of the setting that the setting group is applicable to. The
+ mechanics for applying setting change requests follows exactly the model used when applying constraints at
+ getUserMedia invocation. Each team a request() is made, the user agent begins building up an [internally-represented]
+ constraint structure which is associated with the device making the request (and only that device). For example,
+ if a "width" setting change request is made, the user agent creates a constraint structure equivalent to the
+ following getUserMedia constraint (except that this constraint only applies to the specific device--not all
+ video devices):
+ </p>
+
+ <p><pre><code>{ video: { optional: [ { width: <em>value</em> } ] } }</code></pre><p></p>
+
+ <p>If this is the only request during this script-execution task, then when control returns to the user agent,
+ this constraint will be committed (i.e., like an indexedDB transaction) and the constraint application logic
+ will evaluate the request making changes to the current device if applicable.
+ </p>
+
+ <p>If there is another request during the same script-execution task, it is appended to the optional list. Since
+ order is important in the optional constraints list, the first requested setting has priority over the next.
+ </p>
+
+ <p>The request() API also has a flag used to signal to the UA that the requested setting change should be
+ manditory. In this case, the constraint is added to the manditory set, and replaces an existing setting in
+ that set if the names collide (last setting wins). My expectation is that if a manditory constraint cannot
+ be satisfied, then the UA must end that stream as a result of the failure.
+ </p>
+
+ <p>Unlike constraints built using dictionaries for getUserMedia, the constraint structures produced by calls to
+ the request() API will always be individual proposed values, rather than min/max ranges. This is because
+ min/max information is already available within the relevant settings, and can be included in calculations
+ <em>before</em> making the call to request(). Therefore, I didn't feel it was necessary to clutter the API
+ surface with that feature.
+ </p>
+
+ <p>MediaSettingsRange objects should be used when the setting can generally actually assume a value along a continuum of
+ values. This specification should indicate what the range of values must be for each setting. Given that implementations
+ of various hardware may not exactly map to the same range, an implementation should make a reasonable attempt to
+ translate and scale the hardware's setting onto the mapping provided by this specification. If this is not possible due
+ to a hardware setting supporting (for example) fewer levels of granularity, then the implementation should make the device
+ settings min value reflect the min value reported in this specification, and the same for the max value. Then for values
+ in between the min and max, the implementation may round to the nearest supported value and report that value in the
+ setting.
+ </p>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>For example, if the setting is fluxCapacitance, and has a specified range from -10 (min) to 10 (max) in
+ this specification, but the implementation's fluxCapacitance hardware setting only supports values of "off" "medium" and
+ "full", then -10 should be mapped to "off", 10 should map to "full", and 0 should map to "medium". A request to change the
+ value to 3 should be rounded down to the closest supported setting (0).
+ </p></div>
+
+ <section id="mediasettingsrange-interface">
+ <h4><span class="secno">3.1.1 </span><code>MediaSettingsRange</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-MediaSettingsRange">interface <span class="idlInterfaceID">MediaSettingsRange</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-MediaSettingsRange-max">max</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-MediaSettingsRange-min">min</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-MediaSettingsRange-initial">initial</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-MediaSettingsRange-request-void-any-value-boolean-manditory">request</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">manditory</span></span>);</span>
+};</span></pre><section><h5 id="attributes-8">Attributes</h5><dl class="attributes"><dt id="widl-MediaSettingsRange-max"><code>max</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>The maximum value of this setting. The type of value is specific to the setting.</dd><dt id="widl-MediaSettingsRange-min"><code>min</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>The minimum value of this setting. The type of value is specific to the setting.</dd><dt id="widl-MediaSettingsRange-initial"><code>initial</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>The initial value of this setting. When the object associated with this setting is first made available
+ to the application, the current value of the setting should be set to the initial value.
+ For example, in a browsing scenario, if one web site changes this setting and a subsequent web site
+ gets access to this same setting, the setting should have been reset back to its initial value.
+ </dd></dl></section><section><h5 id="methods-4">Methods</h5><dl class="methods"><dt id="widl-MediaSettingsRange-request-void-any-value-boolean-manditory"><code>request</code></dt><dd>Creates an internal constraint based on the setting name with the provided value, adds that constraint
+ into the pending constraint structure (to the MediaTrackConstraint array by default or replaces an entry
+ in the MediaTrackConstraintSet if the manditory flag is set) and queues a task (if not already queued) to
+ process the pending constraint structure at the conclusion of this task.
+ <p>The manditory parameter defaults to false.</p>
+ <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">manditory</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+
+ <section id="mediasettingslist-interface">
+ <h4><span class="secno">3.1.2 </span><code>MediaSettingsList</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-MediaSettingsList">interface <span class="idlInterfaceID">MediaSettingsList</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-MediaSettingsList-length">length</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>getter any</a></span> <span class="idlMethName"><a href="#widl-MediaSettingsList-item-getter-any-unsigned-long-index">item</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">index</span></span>);</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-MediaSettingsList-initial">initial</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-MediaSettingsList-request-void-any-value-boolean-manditory">request</a></span> (<span class="idlParam"><span class="idlParamType"><a>any</a></span> <span class="idlParamName">value</span></span>, <span class="idlParam">optional <span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">manditory</span></span>);</span>
+};</span></pre><section><h5 id="attributes-9">Attributes</h5><dl class="attributes"><dt id="widl-MediaSettingsList-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The length of the enuerated values that this setting may assume.</dd><dt id="widl-MediaSettingsList-initial"><code>initial</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>The initial value of this setting. When the object associated with this setting is first made available
+ to the application, the current value of the setting should be set to the initial value.
+ For example, in a browsing scenario, if one web site changes this setting and a subsequent web site
+ gets access to this same setting, the setting should have been reset back to its initial value.
+ </dd></dl></section><section><h5 id="methods-5">Methods</h5><dl class="methods"><dt id="widl-MediaSettingsList-item-getter-any-unsigned-long-index"><code>item</code></dt><dd>Retrieves the value of the <code>index</code>ed enumerated item of this setting.<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">index</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>getter any</a></code></div></dd><dt id="widl-MediaSettingsList-request-void-any-value-boolean-manditory"><code>request</code></dt><dd>Creates an internal constraint based on the setting name with the provided value, adds that constraint
+ into the pending constraint structure (to the MediaTrackConstraint array by default or replaces an entry
+ in the MediaTrackConstraintSet if the manditory flag is set) and queues a task (if not already queued) to
+ process the pending constraint structure at the conclusion of this task.
+ <p>The manditory parameter defaults to false.</p>
+ <table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">value</td><td class="prmType"><code><a>any</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">manditory</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+ </section>
+
+ <section id="basic-settings-for-pictures-and-video-devices">
+ <h3><span class="secno">3.2 </span>Basic settings for pictures and video devices</h3>
+
+ <p>Settings (read/writable) are defined as separate properties from their read-only counterparts. This allows for
+ a variety of benefits:
+ </p>
+
+ <ul>
+ <li>Some read-only settings can be surfaced on super-interfaces (like VideoStreamTrack) to benefit non-device
+ centric tracks.</li>
+ <li>Some read-only settings have no corresponding read/write version (for example "facing" cannot be changed).</li>
+ <li>Some read/write settings have no (or do not really require) a similar read-only value (for example, dimensions
+ is already reported separately as width/height).</li>
+ <li>Simple to access read-only settings are more convenient (versus accessing an object to then get the propery).</li>
+ </ul>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>These are pluralized for compatness and easy identification as a "setting". The more verbose
+ "widthSettings", "horizontalAspectRatioSettings", "orientationSettings", etc., were considered (and may still be
+ considered).
+ </p></div>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><div>The following settings have been proposed, but are not included in this version to keep the
+ initial set of settings scoped to those that:
+
+ <ol>
+ <li>cannot be easily computed in post-processing</li>
+ <li>are not redundant with other settings</li>
+ <li>are settings found in nearly all devices (common)</li>
+ <li>can be easily tested for conformance</li>
+ </ol>
+ Each setting also includes a brief explanitory rationale for why it's not included:
+ <ol>
+ <li><code>width</code> - I've used "dimension" for the setting instead, since resolutions of the camera are nearly
+ always in step-wise pairs of width/height combinations. These are thus an enumerated type rather than
+ a range continuum of possible width/height (independent) pairs.
+ </li>
+ <li><code>height</code> - see width explanation</li>
+ <li><code>horizontalAspectRatio</code> - easily calculated based on width/height in the dimension values</li>
+ <li><code>verticalAspectRatio</code> - see horizontalAspectRatio explanation</li>
+ <li><code>orientation</code> - can be easily calculated based on the width/height values and the current rotation</li>
+ <li><code>aperatureSize</code> - while more common on digital cameras, not particularly common on webcams (major use-case
+ for this feature)</li>
+ <li><code>shutterSpeed</code> - see aperatureSize explanation</li>
+ <li><code>denoise</code> - may require specification of the algorithm processing or related image processing filter required
+ to implement.
+ </li>
+ <li><code>effects</code> - sounds like a v2 or indpendent feature (depending on the effect).</li>
+ <li><code>faceDetection</code> - sounds like a v2 feature. Can also be done using post-processing techniques (though
+ perhaps not as fast...)
+ </li>
+ <li><code>antiShake</code> - sounds like a v2 feature.</li>
+ <li><code>geoTagging</code> - this can be independently associated with a recorded picture/video/audio clip using the
+ Geolocation API. Automatically hooking up Geolocation to Media Capture sounds like an exercise for v2
+ given the possible complications.
+ </li>
+ <li><code>highDynamicRange</code> - not sure how this can be specified, or if this is just a v2 feature.</li>
+ <li><code>skintoneEnhancement</code> - not a particularly common setting.</li>
+ <li><code>shutterSound</code> - Can be accomplished by syncing custom audio playback via the <audio> tag if desired.
+ By default, there will be no sound issued.
+ </li>
+ <li><code>redEyeReduction</code> - photo-specific setting. (Could be considered if photo-specific settings
+ are introduced.)
+ </li>
+ <li><code>meteringMode</code> - photo-specific setting. (Could be considered if photo-specific settings
+ are introduced.)</li>
+ <li><code>iso</code> - photo-specific setting. while more common on digital cameras, not particularly common on webcams (major use-case
+ for this feature)</li>
+ <li><code>sceneMode</code> - while more common on digital cameras, not particularly common on webcams (major use-case
+ for this feature)</li>
+ <li><code>antiFlicker</code> - not a particularly common setting.</li>
+ <li><code>zeroShutterLag</code> - this seems more like a <em>hope</em> than a setting. I'd rather just have implementations
+ make the shutter snap as quickly as possible after takePicture, rather than requiring an opt-in/opt-out
+ for this setting.
+ </li>
+ </ol>
+ The following settings are up for debate in my opinion:
+ <ol>
+ <li>exposure</li>
+ <li>exposureCompensation (is this the same as exposure?)</li>
+ <li>autoExposureMode</li>
+ <li>brightness</li>
+ <li>contrast</li>
+ <li>saturation</li>
+ <li>sharpness</li>
+ <li>evShift</li>
+ <li>whiteBalance</li>
+ </ol>
+ <p>Some of the above settings <em>are</em> available as constraints, and so are included in the proposed set of constraints in the
+ last section.
+ </p>
+ </div></div>
+
+ <section id="pictureandvideosettings-mix-in-interface">
+ <h4><span class="secno">3.2.1 </span><code>PictureAndVideoSettings</code> mix-in interface</h4>
+ <pre><code>VideoDeviceTrack</code> implements <code>PictureAndVideoSettings</code>;</pre>
+ <pre><code>PictureDeviceTrack</code> implements <code>PictureAndVideoSettings</code>;</pre>
+ <pre class="idl"><span class="idlInterface" id="idl-def-PictureAndVideoSettings">[<span class="extAttr">NoInterfaceObject</span>]
+interface <span class="idlInterfaceID">PictureAndVideoSettings</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a></span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-dimensions">dimensions</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-rotation">rotation</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a>?</span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-rotations">rotations</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>float</a></span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-zoom">zoom</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a>?</span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-zooms">zooms</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFocusModeEnum"><code>VideoFocusModeEnum</code></a></span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-focusMode">focusMode</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a>?</span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-focusModes">focusModes</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFillLightModeEnum"><code>VideoFillLightModeEnum</code></a></span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-fillLightMode">fillLightMode</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a>?</span> <span class="idlAttrName"><a href="#widl-PictureAndVideoSettings-fillLightModes">fillLightModes</a></span>;</span>
+};</span></pre><section><h5 id="attributes-10">Attributes</h5><dl class="attributes"><dt id="widl-PictureAndVideoSettings-dimensions"><code>dimensions</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a></span>, readonly</dt><dd>The MediaSettingsList reports values of type VideoDimensionDict. The width/height reported are of the
+ camera's sensor, not reflecting a particular orientation.</dd><dt id="widl-PictureAndVideoSettings-rotation"><code>rotation</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The current rotation value in use by the camera. If not supported, the property returns the
+ value 0.</dd><dt id="widl-PictureAndVideoSettings-rotations"><code>rotations</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a></span>, readonly, nullable</dt><dd>The MediaSettingsList reports values of type unsigned long. (0-90-180-270) degrees).
+ <div class="issue"><div class="issue-title"><span>Issue 3</span></div><p>Rotation makes me think I could set this to 45 degrees or some such. Maybe there's a
+ better setting name for this. I only want to support right-angles.
+ </p></div>
+ </dd><dt id="widl-PictureAndVideoSettings-zoom"><code>zoom</code> of type <span class="idlAttrType"><a>float</a></span>, readonly</dt><dd>The current zoom scale value in use by the camera. If the zooms property is not available (not
+ supported), then this property will always return 1.0.
+ <div class="issue"><div class="issue-title"><span>Issue 4</span></div><p>In the case that a camera device supports both optical and digital zoom, does it make sense
+ to have just one property? I expect this to be the "digitalZoom" version, which is more common on devices.
+ </p></div>
+ </dd><dt id="widl-PictureAndVideoSettings-zooms"><code>zooms</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a></span>, readonly, nullable</dt><dd>The MediaSettingsRange reports values of type float. (initial value is 1. The float value is a scale
+ factor, for example 0.5 is zoomed out by double, while 2.0 is zoomed in by double. Requests should be
+ rounded to the nearest supporting zoom factor by the implementation (when zoom is supported).
+ </dd><dt id="widl-PictureAndVideoSettings-focusMode"><code>focusMode</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFocusModeEnum"><code>VideoFocusModeEnum</code></a></span>, readonly</dt><dd>The camera's current focusMode state.</dd><dt id="widl-PictureAndVideoSettings-focusModes"><code>focusModes</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a></span>, readonly, nullable</dt><dd>The MediaSettingsList reports values of type VideoFocusModeEnum (less the "notavailable" value). The
+ initial value is "auto".</dd><dt id="widl-PictureAndVideoSettings-fillLightMode"><code>fillLightMode</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-VideoFillLightModeEnum"><code>VideoFillLightModeEnum</code></a></span>, readonly</dt><dd>The camera's current fill light mode.
+ <div class="note"><div class="note-title"><span>Note</span></div><p>fillLight seemed more appropriate a term to use for both cameras and photo settings.</p></div>
+ </dd><dt id="widl-PictureAndVideoSettings-fillLightModes"><code>fillLightModes</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsList"><code>MediaSettingsList</code></a></span>, readonly, nullable</dt><dd>The MediaSettingsList reports values of type VideoFillLightModeEnum (less the "notavailable" value).
+ The initial value is "auto".</dd></dl></section>
+ </section>
+
+ <section id="videodimensiondict-dictionary">
+ <h4><span class="secno">3.2.2 </span><code>VideoDimensionDict</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-VideoDimensionDict">dictionary <span class="idlDictionaryID">VideoDimensionDict</span> {
+<span class="idlMember"> <span class="idlMemberType"><a>unsigned long</a></span> <span class="idlMemberName"><a href="#widl-VideoDimensionDict-width">width</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>unsigned long</a></span> <span class="idlMemberName"><a href="#widl-VideoDimensionDict-height">height</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-videodimensiondict-members">Dictionary <a class="idlType" href="#idl-def-VideoDimensionDict"><code>VideoDimensionDict</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-VideoDimensionDict-width"><code>width</code> of type <span class="idlMemberType"><a>unsigned long</a></span></dt><dd>A supported camera width (long axis).</dd><dt id="widl-VideoDimensionDict-height"><code>height</code> of type <span class="idlMemberType"><a>unsigned long</a></span></dt><dd>A supported camera height (short axis).</dd></dl></section>
+ </section>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>The following enums had many more values in the prior proposal, but in the interest of testing,
+ I've scoped the initial list to those that seem most easily testable.
+ </p></div>
+
+ <section id="videofocusmodeenum-enumeration">
+ <h4><span class="secno">3.2.3 </span><code>VideoFocusModeEnum</code> enumeration</h4>
+ <pre class="idl"><span class="idlEnum" id="idl-def-VideoFocusModeEnum">enum <span class="idlEnumID">VideoFocusModeEnum</span> {
+ "<span class="idlEnumItem">notavailable</span>",
+ "<span class="idlEnumItem">auto</span>",
+ "<span class="idlEnumItem">manual</span>"
+};</span></pre><table class="simple"><tr><th colspan="2">Enumeration description</th></tr><tr><td><code>notavailable</code></td><td>This camera does not have an option to change focus modes.</td></tr><tr><td><code>auto</code></td><td>The camera auto-focuses.</td></tr><tr><td><code>manual</code></td><td>The camera must be manually focused.</td></tr></table>
+ </section>
+
+ <section id="videofilllightmodeenum-enumeration">
+ <h4><span class="secno">3.2.4 </span><code>VideoFillLightModeEnum</code> enumeration</h4>
+ <pre class="idl"><span class="idlEnum" id="idl-def-VideoFillLightModeEnum">enum <span class="idlEnumID">VideoFillLightModeEnum</span> {
+ "<span class="idlEnumItem">notavailable</span>",
+ "<span class="idlEnumItem">auto</span>",
+ "<span class="idlEnumItem">off</span>",
+ "<span class="idlEnumItem">on</span>"
+};</span></pre><table class="simple"><tr><th colspan="2">Enumeration description</th></tr><tr><td><code>notavailable</code></td><td>This camera does not have an option to change fill light modes (e.g., the camera does not have a flash).</td></tr><tr><td><code>auto</code></td><td>The camera's fill light will be enabled when required (typically low light conditions). Otherwise it will be
+ off.
+ </td></tr><tr><td><code>off</code></td><td>The camera's fill light will not be used.</td></tr><tr><td><code>on</code></td><td>The camera's fill light will be turned on until this setting is changed again, or the underlying track object
+ has ended.
+ </td></tr></table>
+ </section>
+ </section>
+
+ <section id="expanded-settings-for-video-devices">
+ <h3><span class="secno">3.3 </span>Expanded settings for video devices</h3>
+
+ <section id="videodevicetrack-partial-interface">
+ <h4><span class="secno">3.3.1 </span><code>VideoDeviceTrack</code> partial interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-VideoDeviceTrack-1">partial interface <span class="idlInterfaceID">VideoDeviceTrack</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>float</a></span> <span class="idlAttrName"><a href="#widl-VideoDeviceTrack-framesPerSecond">framesPerSecond</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a>?</span> <span class="idlAttrName"><a href="#widl-VideoDeviceTrack-framesPerSeconds">framesPerSeconds</a></span>;</span>
+};</span></pre><section><h5 id="attributes-11">Attributes</h5><dl class="attributes"><dt id="widl-VideoDeviceTrack-framesPerSecond"><code>framesPerSecond</code> of type <span class="idlAttrType"><a>float</a></span>, readonly</dt><dd>The camera's currently configured (estimated) framesPerSecond.</dd><dt id="widl-VideoDeviceTrack-framesPerSeconds"><code>framesPerSeconds</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a></span>, readonly, nullable</dt><dd>The MediaSettingRange reports values of type float.
+ <div class="issue"><div class="issue-title"><span>Issue 5</span></div><p>I wonder if this should just be a MediaSettingsList with the common values of 15, 30, and 60. Are
+ there really any other values coming from hardware?
+ </p></div>
+ </dd></dl></section>
+ </section>
+ </section>
+
+ <section id="settings-for-audio-devices">
+ <h3><span class="secno">3.4 </span>Settings for audio devices</h3>
+
+ <div class="note"><div class="note-title"><span>Note</span></div><p>My previous proposal included a "bassTone" and "trebleTone" setting value, but on reflection, those settings
+ are more relevant to playback than to microphone device settings. Those settings have been removed.
+ </p></div>
+ <section id="audiodevicetrack-partial-interface">
+ <h4><span class="secno">3.4.1 </span><code>AudioDeviceTrack</code> partial interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-AudioDeviceTrack-1">partial interface <span class="idlInterfaceID">AudioDeviceTrack</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a>?</span> <span class="idlAttrName"><a href="#widl-AudioDeviceTrack-levels">levels</a></span>;</span>
+};</span></pre><section><h5 id="attributes-12">Attributes</h5><dl class="attributes"><dt id="widl-AudioDeviceTrack-levels"><code>levels</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaSettingsRange"><code>MediaSettingsRange</code></a></span>, readonly, nullable</dt><dd>The MediaSettingRange reports values of type unsigned long.</dd></dl></section>
+ </section>
+ </section>
+
+ <section id="tracking-the-result-of-constraint-application">
+ <h3><span class="secno">3.5 </span>Tracking the result of constraint application</h3>
+
+ <section id="mediaconstraintresulteventhandlers-mix-in-interface">
+ <h4><span class="secno">3.5.1 </span><code>MediaConstraintResultEventHandlers</code> mix-in interface</h4>
+ <pre><code>AudioDeviceTrack</code> implements <code>MediaConstraintResultEventHandlers</code>;</pre>
+ <pre><code>VideoDeviceTrack</code> implements <code>MediaConstraintResultEventHandlers</code>;</pre>
+ <pre><code>PictureDeviceTrack</code> implements <code>MediaConstraintResultEventHandlers</code>;</pre>
+ <pre><code>MediaDeviceList</code> implements <code>MediaConstraintResultEventHandlers</code>;</pre>
+ <pre class="idl"><span class="idlInterface" id="idl-def-MediaConstraintResultEventHandlers">[<span class="extAttr">NoInterfaceObject</span>]
+interface <span class="idlInterfaceID">MediaConstraintResultEventHandlers</span> {
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-MediaConstraintResultEventHandlers-onconstrainterror">onconstrainterror</a></span>;</span>
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-MediaConstraintResultEventHandlers-onconstraintsuccess">onconstraintsuccess</a></span>;</span>
+};</span></pre><section><h5 id="attributes-13">Attributes</h5><dl class="attributes"><dt id="widl-MediaConstraintResultEventHandlers-onconstrainterror"><code>onconstrainterror</code> of type <span class="idlAttrType"><a>EventHandler</a></span></dt><dd>Register/unregister for "constrainterror" events. The handler should expect to get a ConstraintErrorEvent object as its first
+ parameter. The event is fired asynchronously after [potentially many] settings change requests are made but resulted in
+ one or more failures to meet those constraints. The ConstraintErrorEvent reports the name of the settings that could not be
+ applied.</dd><dt id="widl-MediaConstraintResultEventHandlers-onconstraintsuccess"><code>onconstraintsuccess</code> of type <span class="idlAttrType"><a>EventHandler</a></span></dt><dd>Register/unregister for "constraintsuccess" events. The handler should expect to get a DeviceEvent object as its first
+ parameter. The event is fired asynchronously after the [potentially many] settings change requests are made and applied
+ successfully. Note, if any one setting change fails, then the "constrainterror" event fires instead. The DeviceEvent
+ will fire on the track making the settings request (with the device attribute referring to the same object), with the
+ exception of the MediaDeviceList (see the MediaDeviceList's select() API).
+ </dd></dl></section>
+ </section>
+
+ <section id="constrainterrorevent-interface">
+ <h4><span class="secno">3.5.2 </span><code>ConstraintErrorEvent</code> interface</h4>
+ <pre class="idl"><span class="idlInterface" id="idl-def-ConstraintErrorEvent">[<span class="extAttr">Constructor(DOMString type, optional ConstraintErrorEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">ConstraintErrorEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a>[]</span> <span class="idlAttrName"><a href="#widl-ConstraintErrorEvent-optionalConstraints">optionalConstraints</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>DOMString</a>[]</span> <span class="idlAttrName"><a href="#widl-ConstraintErrorEvent-manditoryConstraints">manditoryConstraints</a></span>;</span>
+};</span></pre><section><h5 id="attributes-14">Attributes</h5><dl class="attributes"><dt id="widl-ConstraintErrorEvent-optionalConstraints"><code>optionalConstraints</code> of type array of <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd>A list of optional contraints that failed or succeeded (depending on the event type).</dd><dt id="widl-ConstraintErrorEvent-manditoryConstraints"><code>manditoryConstraints</code> of type array of <span class="idlAttrType"><a>DOMString</a></span>, readonly</dt><dd></dd></dl></section>
+ </section>
+
+ <section id="constrainterroreventinit-dictionary">
+ <h4><span class="secno">3.5.3 </span><code>ConstraintErrorEventInit</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-ConstraintErrorEventInit">dictionary <span class="idlDictionaryID">ConstraintErrorEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType">sequence<<a>'DOMString</a>></span> <span class="idlMemberName"><a href="#widl-ConstraintErrorEventInit-optionalConstraints">optionalConstraints</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">sequence<<a>'DOMString</a>></span> <span class="idlMemberName"><a href="#widl-ConstraintErrorEventInit-manditoryConstraints">manditoryConstraints</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-constrainterroreventinit-members">Dictionary <a class="idlType" href="#idl-def-ConstraintErrorEventInit"><code>ConstraintErrorEventInit</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-ConstraintErrorEventInit-optionalConstraints"><code>optionalConstraints</code> of type <span class="idlMemberType">sequence<<a>'DOMString</a>></span></dt><dd>List of optional constraints to populate into the ConstraintErrorEvent object's optionalConstraints readonly attribute.</dd><dt id="widl-ConstraintErrorEventInit-manditoryConstraints"><code>manditoryConstraints</code> of type <span class="idlMemberType">sequence<<a>'DOMString</a>></span></dt><dd>List of manditory constraints to populate into the ConstraintErrorEvent object's manditoryConstraints readonly attribute.</dd></dl></section>
+ </section>
+ </section>
+ </section>
+
+ <section id="device-lists">
+ <!--OddPage--><h2><span class="secno">4. </span>Device Lists</h2>
+
+ <p>One common problem with all my previous proposals, and with the existing model for using getUserMedia to request access to
+ additional devices, is the problem of discovery of multiple devices. As I understand it,
+ <a href="http://dev.w3.org/2011/webrtc/editor/getusermedia.html#implementation-suggestions">the existing recommendation</a>
+ relies on "guessing" by making a second (or third, etc.) request to getUserMedia for access to additional devices. This
+ model has two primary advantages:</p>
+
+ <p>First, it ensures privacy by making sure that each device request could be approved by the user. I say "could" because there
+ is no current requirement that the user agent be involved, especially when re-requesting a device type that was already approved,
+ for example, a second "video" device. I surmise that a request for a different class of device ("audio", when exclusive "video" was
+ previously approved), would be cause for an implementation to ask the user for approval.
+ </p>
+
+ <p>Second, it ensure privacy by not leaking any information about additional devices until the code has sucessfully requested a device.</p>
+
+ <p>Unfortunately, this model does not provide a means for discovery of additional devices. Such a discovery mechanism could be
+ trivially added to this proposal in the form of a device-specific "totalDevices" property, but there's an opportunity for
+ considering a solution that both streamlines the usability of multiple devices while maintaining the privacy benefits of the current
+ model.
+ </p>
+
+ <p>The device list is such a proposal. The device list offers the following benefits:</p>
+
+ <ul>
+ <li>Privacy of multiple devices is maintained (multiple device discovery is not available until the user has approved at least
+ one device, and then discovery is only permitted for devices matching its device type).
+ </li>
+ <li>Multiple device discovery is as easy as a hypothetical "totalDevices" property.</li>
+ <li>Multiple devices (of a common type) can be used/switched-to directly without needing to re-request a second MediaStream from
+ getUserMedia.</li>
+ <li>Provides a mechanism for discovery of "new" devices at run-time (for example, when a USB camera is plugged-in while the
+ application is running).</li>
+ <li>Just like getUserMedia, it allows for the application of constraints against a set of devices with visibility into the results.</li>
+ </ul>
+
+ <p>A device list is merely a list of all AudioDeviceTrack or VideoDeviceTrack objects that are available to the application. Device lists are
+ device-type specific, so there is one device list for all AudioDeviceTrack objects and one device list for all VideoDeviceTrack objects.
+ There is only one instance of each of these lists at any time, and the lists are <em>LIVE</em> (meaning the user agent keeps them up-to-date
+ at all times). Device track objects are added to the list as soon as they are available to the application (e.g., as soon as they are
+ plugged-in) A device track object in the device list will have a readyState set to either <code>LIVE</code> or <code>MUTED</code>). Device
+ tracks are removed from the list when they are unplugged, or otherwise disassociated with their device source such that their readyState
+ changes to <code>ENDED</code>.
+ </p>
+
+ <p>Every non-ended device track object will belong to a device list. Of course, the same device track object may also belong to zero or more
+ <code>MediaStreamTrackList</code> objects. The device list provides the one-stop list for all devices of that type regardless of which
+ MediaStream's (if any) the device track objects also belong to.
+ </p>
+
+ <section id="mediadevicelist-interface">
+ <h3><span class="secno">4.1 </span><code>MediaDeviceList</code> interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-MediaDeviceList">interface <span class="idlInterfaceID">MediaDeviceList</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-MediaDeviceList-length">length</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>getter any</a></span> <span class="idlMethName"><a href="#widl-MediaDeviceList-item-getter-any-unsigned-long-index">item</a></span> (<span class="idlParam"><span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">index</span></span>);</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a></span> <span class="idlAttrName"><a href="#widl-MediaDeviceList-totalEnabled">totalEnabled</a></span>;</span>
+<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-MediaDeviceList-select-void-MediaTrackConstraints-constraints">select</a></span> (<span class="idlParam"><span class="idlParamType"><a>MediaTrackConstraints</a></span> <span class="idlParamName">constraints</span></span>);</span>
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-MediaDeviceList-ondeviceadded">ondeviceadded</a></span>;</span>
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-MediaDeviceList-ondeviceremoved">ondeviceremoved</a></span>;</span>
+};</span></pre><section id="attributes"><h4><span class="secno">4.1.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-MediaDeviceList-length"><code>length</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The number of devices in this list (including those that are <code>MUTED</code> and <code>LIVE</code>.</dd><dt id="widl-MediaDeviceList-totalEnabled"><code>totalEnabled</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly</dt><dd>The number of devices in this list that whose <code>readyState</code> is in the <code>LIVE</code> state.</dd><dt id="widl-MediaDeviceList-ondeviceadded"><code>ondeviceadded</code> of type <span class="idlAttrType"><a>EventHandler</a></span></dt><dd>Register/unregister for "deviceadded" events. The handler should expect to get a DeviceEvent object as its first
+ parameter. The event is fired whenever a new video device (or audio device, depending on the device list) becomes available for use.
+ This can happen when a new device is plugged in, for example. Prevoiusly ended device tracks are not re-used, and if the user agent
+ is able to re-purpose a physical device for use in the application, it fires the "deviceadded" event providing a new device track
+ object (in its default initial state).</dd><dt id="widl-MediaDeviceList-ondeviceremoved"><code>ondeviceremoved</code> of type <span class="idlAttrType"><a>EventHandler</a></span></dt><dd>Register/unregister for "deviceremoved" events. The handler should expect to get a DeviceEvent object as its first
+ parameter. The event is fired whenever an existing video device (or audio device, depending on the device list) moves into the
+ <code>ENDED</code> state. Note that before dispatching this event, the device in question is removed from the device list.
+ </dd></dl></section><section id="methods"><h4><span class="secno">4.1.2 </span>Methods</h4><dl class="methods"><dt id="widl-MediaDeviceList-item-getter-any-unsigned-long-index"><code>item</code></dt><dd>Retrieves a device object (an AudioDeviceTrack if this is the audio devices list or a VideoDeviceTrack if this is the video devices list).<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">index</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>getter any</a></code></div></dd><dt id="widl-MediaDeviceList-select-void-MediaTrackConstraints-constraints"><code>select</code></dt><dd>Apply a set of optional and/or manditory constraints to the set of devices in the device list, with the goal of
+ selecting a single device. This will queue a task to fire either a "constrainterror" or "constraintsuccess" event
+ depending on the result. The "constraintsuccess" event includes the selected device on the DeviceEvent object's device
+ attribute.
+ <table class="parameters"><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>MediaTrackConstraints</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ </section>
+
+ <section id="deviceevent-interface">
+ <h3><span class="secno">4.2 </span><code>DeviceEvent</code> interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-DeviceEvent">[<span class="extAttr">Constructor(DOMString type, optional DeviceEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">DeviceEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>any</a></span> <span class="idlAttrName"><a href="#widl-DeviceEvent-device">device</a></span>;</span>
+};</span></pre><section id="attributes-1"><h4><span class="secno">4.2.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-DeviceEvent-device"><code>device</code> of type <span class="idlAttrType"><a>any</a></span>, readonly</dt><dd>Contains a reference to the relevant device.</dd></dl></section>
+ </section>
+
+ <section id="deviceeventinit-dictionary">
+ <h3><span class="secno">4.3 </span><code>DeviceEventInit</code> dictionary</h3>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-DeviceEventInit">dictionary <span class="idlDictionaryID">DeviceEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType"><a>any</a></span> <span class="idlMemberName"><a href="#widl-DeviceEventInit-device">device</a></span>;</span>
+};</span></pre><section id="dictionary-deviceeventinit-members"><h4><span class="secno">4.3.1 </span>Dictionary <a class="idlType" href="#idl-def-DeviceEventInit"><code>DeviceEventInit</code></a> Members</h4><dl class="dictionary-members"><dt id="widl-DeviceEventInit-device"><code>device</code> of type <span class="idlMemberType"><a>any</a></span></dt><dd>Video or Audio device track used to initialize the "device" property on the DeviceEvent.</dd></dl></section>
+ </section>
+
+ <p>Device lists are only accessible from an existing device track object. In other words, the device list itself can only be accessed from
+ one of the devices contained within it (this is an inside-to-outside reference). To help orient the traversal of the list, each device
+ track object includes a (dynaimcally updated) device index property. If a given device track transitions to the <coded>ENDED</coded>
+ state, then it will not belong to the device list any longer and its device index property becomes invalid (null); however, the device
+ list itself will still be accessible from that object.
+ </p>
+
+ <section id="devicelistaccess-mix-in-interface">
+ <h3><span class="secno">4.4 </span><code>DeviceListAccess</code> mix-in interface</h3>
+ <pre><code>AudioDeviceTrack</code> implements <code>DeviceListAccess</code>;</pre>
+ <pre><code>VideoDeviceTrack</code> implements <code>DeviceListAccess</code>;</pre>
+ <pre class="idl"><span class="idlInterface" id="idl-def-DeviceListAccess">[<span class="extAttr">NoInterfaceObject</span>]
+interface <span class="idlInterfaceID">DeviceListAccess</span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaDeviceList"><code>MediaDeviceList</code></a></span> <span class="idlAttrName"><a href="#widl-DeviceListAccess-devices">devices</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a>?</span> <span class="idlAttrName"><a href="#widl-DeviceListAccess-deviceIndex">deviceIndex</a></span>;</span>
+};</span></pre><section id="attributes-2"><h4><span class="secno">4.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-DeviceListAccess-devices"><code>devices</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-MediaDeviceList"><code>MediaDeviceList</code></a></span>, readonly</dt><dd>A reference to the device list for the associated video (or audio) device.</dd><dt id="widl-DeviceListAccess-deviceIndex"><code>deviceIndex</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly, nullable</dt><dd>The current index of this device in the device list. This value can be dynamically changed when other devices are added to (or
+ removed from) the device list. If this device is removed from the device list (because it enters the <code>ENDED</code> state),
+ then the deviceIndex property returns null to signal that this device is not in the device list any longer.
+ </dd></dl></section>
+ </section>
+ </section>
+
+ <section id="constraints-for-navigator.getusermedia-mediadevicelist.select">
+ <!--OddPage--><h2><span class="secno">5. </span>Constraints for navigator.getUserMedia/MediaDeviceList.select</h2>
+
+ <p>This proposal defines several constraints for use with video and audio devices.</p>
+
+ <p>These constraints are applied against the device's <em>range</em> or set of
+ <em>enumerated</em> possible settings, but do not result in a setting change
+ on the device. To change actual settings, use the request() API on each setting.
+ </p>
+
+ <section id="video-constraints">
+ <h3><span class="secno">5.1 </span>Video Constraints</h3>
+
+ <p>The following constraints are applicable to video devices</p>
+
+ <section id="videoconstraints-dictionary">
+ <h4><span class="secno">5.1.1 </span><code>VideoConstraints</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-VideoConstraints">dictionary <span class="idlDictionaryID">VideoConstraints</span> : <span class="idlSuperclass"><a>MediaTrackConstraintSet</a></span> {
+<span class="idlMember"> <span class="idlMemberType">(<a>unsigned long</a> or <a class="idlType" href="#idl-def-MinMaxULongSubConstraint"><code>MinMaxULongSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-width">width</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">(<a>unsigned long</a> or <a class="idlType" href="#idl-def-MinMaxULongSubConstraint"><code>MinMaxULongSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-height">height</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">(<a>float</a> or <a class="idlType" href="#idl-def-MinMaxFloatSubConstraint"><code>MinMaxFloatSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-horizontalAspectRatio">horizontalAspectRatio</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">(<a>float</a> or <a class="idlType" href="#idl-def-MinMaxFloatSubConstraint"><code>MinMaxFloatSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-verticalAspectRatio">verticalAspectRatio</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>unsigned long</a></span> <span class="idlMemberName"><a href="#widl-VideoConstraints-rotation">rotation</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">(<a>float</a> or <a class="idlType" href="#idl-def-MinMaxFloatSubConstraint"><code>MinMaxFloatSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-zoom">zoom</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a class="idlType" href="#idl-def-VideoFocusModeEnum"><code>VideoFocusModeEnum</code></a></span> <span class="idlMemberName"><a href="#widl-VideoConstraints-focusMode">focusMode</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a class="idlType" href="#idl-def-VideoFillLightModeEnum"><code>VideoFillLightModeEnum</code></a></span> <span class="idlMemberName"><a href="#widl-VideoConstraints-fillLightMode">fillLightMode</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType">(<a>float</a> or <a class="idlType" href="#idl-def-MinMaxFloatSubConstraint"><code>MinMaxFloatSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-VideoConstraints-framesPerSecond">framesPerSecond</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-videoconstraints-members">Dictionary <a class="idlType" href="#idl-def-VideoConstraints"><code>VideoConstraints</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-VideoConstraints-width"><code>width</code> of type <span class="idlMemberType"><a>unsigned longMinMaxULongSubConstraint</a></span></dt><dd>A device that supports the desired width or width range.</dd><dt id="widl-VideoConstraints-height"><code>height</code> of type <span class="idlMemberType"><a>unsigned longMinMaxULongSubConstraint</a></span></dt><dd>A device that supports the desired height or height range.</dd><dt id="widl-VideoConstraints-horizontalAspectRatio"><code>horizontalAspectRatio</code> of type <span class="idlMemberType"><a>floatMinMaxFloatSubConstraint</a></span></dt><dd>A device that supports the desired horizontal aspect ratio (width/height)</dd><dt id="widl-VideoConstraints-verticalAspectRatio"><code>verticalAspectRatio</code> of type <span class="idlMemberType"><a>floatMinMaxFloatSubConstraint</a></span></dt><dd>A device that supports the desired vertical aspect ratio (height/width)</dd><dt id="widl-VideoConstraints-rotation"><code>rotation</code> of type <span class="idlMemberType"><a>unsigned long</a></span></dt><dd>A device that supports the desired rotation.</dd><dt id="widl-VideoConstraints-zoom"><code>zoom</code> of type <span class="idlMemberType"><a>floatMinMaxFloatSubConstraint</a></span></dt><dd>A device that supports the desired zoom setting.</dd><dt id="widl-VideoConstraints-focusMode"><code>focusMode</code> of type <span class="idlMemberType"><a class="idlType" href="#idl-def-VideoFocusModeEnum"><code>VideoFocusModeEnum</code></a></span></dt><dd>A device that supports the desired focus mode.</dd><dt id="widl-VideoConstraints-fillLightMode"><code>fillLightMode</code> of type <span class="idlMemberType"><a class="idlType" href="#idl-def-VideoFillLightModeEnum"><code>VideoFillLightModeEnum</code></a></span></dt><dd>A device that supports the desired fill light (flash) mode.</dd><dt id="widl-VideoConstraints-framesPerSecond"><code>framesPerSecond</code> of type <span class="idlMemberType"><a>floatMinMaxFloatSubConstraint</a></span></dt><dd>A device that supports the desired frames per second.</dd></dl></section>
+ </section>
+ </section>
+
+ <section id="audio-constraints">
+ <h3><span class="secno">5.2 </span>Audio Constraints</h3>
+
+ <p>The following constraints are applicable to audio devices</p>
+
+ <section id="audioconstraints-dictionary">
+ <h4><span class="secno">5.2.1 </span><code>AudioConstraints</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-AudioConstraints">dictionary <span class="idlDictionaryID">AudioConstraints</span> : <span class="idlSuperclass"><a>MediaTrackConstraintSet</a></span> {
+<span class="idlMember"> <span class="idlMemberType">(<a>unsigned long</a> or <a class="idlType" href="#idl-def-MinMaxULongSubConstraint"><code>MinMaxULongSubConstraint</code></a>)</span> <span class="idlMemberName"><a href="#widl-AudioConstraints-level">level</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-audioconstraints-members">Dictionary <a class="idlType" href="#idl-def-AudioConstraints"><code>AudioConstraints</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-AudioConstraints-level"><code>level</code> of type <span class="idlMemberType"><a>unsigned longMinMaxULongSubConstraint</a></span></dt><dd>A device that supports the desired level or level range.</dd></dl></section>
+ </section>
+
+ </section>
+
+ <section id="common-sub-constraint-structures">
+ <h3><span class="secno">5.3 </span>Common sub-constraint structures</h3>
+
+ <section id="minmaxulongsubconstraint-dictionary">
+ <h4><span class="secno">5.3.1 </span><code>MinMaxULongSubConstraint</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-MinMaxULongSubConstraint">dictionary <span class="idlDictionaryID">MinMaxULongSubConstraint</span> {
+<span class="idlMember"> <span class="idlMemberType"><a>unsigned long</a></span> <span class="idlMemberName"><a href="#widl-MinMaxULongSubConstraint-max">max</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>unsigned long</a></span> <span class="idlMemberName"><a href="#widl-MinMaxULongSubConstraint-min">min</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-minmaxulongsubconstraint-members">Dictionary <a class="idlType" href="#idl-def-MinMaxULongSubConstraint"><code>MinMaxULongSubConstraint</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-MinMaxULongSubConstraint-max"><code>max</code> of type <span class="idlMemberType"><a>unsigned long</a></span></dt><dd>unsigned long min</dd><dt id="widl-MinMaxULongSubConstraint-min"><code>min</code> of type <span class="idlMemberType"><a>unsigned long</a></span></dt><dd></dd></dl></section>
+ </section>
+
+ <section id="minmaxfloatsubconstraint-dictionary">
+ <h4><span class="secno">5.3.2 </span><code>MinMaxFloatSubConstraint</code> dictionary</h4>
+ <pre class="idl"><span class="idlDictionary" id="idl-def-MinMaxFloatSubConstraint">dictionary <span class="idlDictionaryID">MinMaxFloatSubConstraint</span> {
+<span class="idlMember"> <span class="idlMemberType"><a>float</a></span> <span class="idlMemberName"><a href="#widl-MinMaxFloatSubConstraint-max">max</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>float</a></span> <span class="idlMemberName"><a href="#widl-MinMaxFloatSubConstraint-min">min</a></span>;</span>
+};</span></pre><section><h5 id="dictionary-minmaxfloatsubconstraint-members">Dictionary <a class="idlType" href="#idl-def-MinMaxFloatSubConstraint"><code>MinMaxFloatSubConstraint</code></a> Members</h5><dl class="dictionary-members"><dt id="widl-MinMaxFloatSubConstraint-max"><code>max</code> of type <span class="idlMemberType"><a>float</a></span></dt><dd>float min</dd><dt id="widl-MinMaxFloatSubConstraint-min"><code>min</code> of type <span class="idlMemberType"><a>float</a></span></dt><dd></dd></dl></section>
+ </section>
+
+ <section id="videoorientationenum-enumeration">
+ <h4><span class="secno">5.3.3 </span><code>VideoOrientationEnum</code> enumeration</h4>
+ <pre class="idl"><span class="idlEnum" id="idl-def-VideoOrientationDict">enum <span class="idlEnumID">VideoOrientationDict</span> {
+ "<span class="idlEnumItem">landscape</span>",
+ "<span class="idlEnumItem">portrait</span>"
+};</span></pre><table class="simple"><tr><th colspan="2">Enumeration description</th></tr><tr><td><code>landscape</code></td><td>The long axis of the "effective" video (width/height + rotation) is landscape.</td></tr><tr><td><code>portrait</code></td><td>The long axis of the "effective" video (width/height + rotation) is portrait.</td></tr></table>
+ </section>
+ </section>
+ </section>
+
+
+
+
+</body></html>