W3C home > Mailing lists > Public > public-media-capture@w3.org > June 2014

Re: A proposal for getUserMedia constraints based on the consensus reached in the DC interim

From: cowwoc <cowwoc@bbs.darktech.org>
Date: Mon, 09 Jun 2014 17:32:01 -0400
Message-ID: <539627D1.6060308@bbs.darktech.org>
To: public-media-capture@w3.org
I don't understand the meaning of:

     “facingMode”: {"exact": “environment”},

In theory, this means I didn't read some documentation which explains 
this. In practice, this means the convention is not intuitive.

And I also suggest renaming "advanced" to something more intuitive. The 
current name does not hint what the section actually does.

Gili

On 09/06/2014 5:08 PM, Peter Thatcher wrote:
> At the interim meeting in DC, we reached a consensus for a form of 
> getUserMedia constraints that has the following form:
>
> var supports = DeviceManager.getSupportedConstraints("video");
> if(!supports["aspectRatio"] || !supports["facingMode"]) {
>   // Treat like an error.
> }
> getUserMedia({“video”: {
>   “width”: {"min": 320, “ideal”: 1280, “max”: 1920},
>   “height”: {"min": 240, “ideal”: 720, “max”: 1080},
>   // Shorthand for ideal.
>   “framerate”: 30,
>   // "facingMode": "environment" would be optional.
>   “facingMode”: {"exact": “environment”},
>   "advanced": [...]
> }}, ...);
>
> And the following rules:
>
> 1.  "min", "max", and "exact" are required, except when in the 
> "advanced" list.
> 2.  "ideal" and a bare value or list of values are optional.
> 3.  The browser indicates what it supports via 
> DeviceManager.getSupportedConstraints, which the JS can use to make 
> sure the browser supports a certain constraint before trying to use it.
>
> Here is an example of "I want 720p, I can go up to 1080p, and I can go 
> down to VGA":
>
> getUserMedia({“video”: {
>   “width”: {"min": 640, “ideal”: 1280, “max”: 1920},
>   “height”: {"min": 480, “ideal”: 720, “max”: 1080},
> }}, ...);
>
>
> Here is an example of "I want camera X, ideally with VGA":
>
> var cameraSourceId = ...;
> getUserMedia({“video”: {
>   "sourceId": {"exact": cameraSourceId},
>   "width": 640,
>   "height": 480
> }}, ...);
>
> Here is an example of "I want a front-facing camera and it must be VGA":
>
> var supports = DeviceManager.getSupportedConstraints("video");
> if(supports["facingMode"]) {
>   getUserMedia({“video”: {
>     "facingMode": {"exact": "user"},
>     "width": {"exact": 640},
>     "height": {"exact": 480}
>   }}, ...);
> }
>
> Here is an advanced example of "I want 4k, then 1080, then 720p, and 
> nothing else".
>
> getUserMedia({“video”: {
>   "advanced": [
>     {"width": 4096, "height": 2160},
>     {"width": 1920, "height": 1080},
>     {"width": 1280, "height": 720}
>   ]
> }}, ...);
>
>
> I have looked through the existing WebIDL, and I believe this is would 
> be the best way to structure the new WebIDL.  Note the assumption that 
> there is a "DeviceManager" to be added before this:
>
> partial interface DeviceManager {
>   // Keys are constraint keys, and truthy values = supported and
>   // untruthy values = unsupported.
>   static Dictionary getSupportedConstraints(DOMString kind);
> }
>
> dictionary MediaTrackConstraints : MediaTrackConstraintSet {
>     sequence<MediaTrackConstraintSet> advanced;
> };
>
> dictionary MediaTrackConstraintSet {
>     ConstrainLong            width;
>     ConstrainLong            height;
>     ConstrainDouble          aspectRatio;
>     ConstrainDouble          frameRate;
>     ConstrainVideoFacingMode facingMode;
>     ConstrainDouble          volume;
>     ConstrainLong            sampleRate;
>     ConstrainLong            sampleSize;
>     boolean                  echoCancelation;
>     ConstrainDOMString       sourceId;
> };
>
> typedef (Long or ConstrainLongRange) ConstrainLong;
> typedef (Double or ConstrainDoubleRange) ConstrainDouble;
> typedef (DOMString or sequence<DOMString> or ConstrainDOMStringParameters)
>   ConstrainDOMString;
> typedef (VideoFacingModeEnum or sequence<VideoFacingModeEnum> or
>   ConstrainVideoFacingModeParameters) ConstrainVideoFacingMode;
>
> dictionary ConstrainLongRange {
>     long max;
>     long min;
>     long exact;  // new
>     long ideal;  // new
> }
>
> dictionary ConstrainDoubleRange {
>     double min;
>     double max;
>     double exact;  // new
>     double ideal;  // new
> };
>
> // new
> dictionary ConstrainDOMStringParameters {
>   (DOMString or sequence<DOMString>) exact;
>   (DOMString or sequence<DOMString>) ideal;
> }
>
> // new
> dictionary ConstrainVideoFacingModeParameters {
>   (VideoFacingModeEnum or sequence<VideoFacingModeEnum>) exact;
>   (VideoFacingModeEnum or sequence<VideoFacingModeEnum>) ideal;
> }
>
> Note that it's possible, according to the type system, to have "exact" 
> and "ideal" in "advanced", which doesn't make sense according to the 
> algorithm.  But making that not possible complicates the types a lot, 
> which probably isn't worth it.  It would be much more simple to put a 
> check in the runtime rather than the type system to disallow that.
>
>
> Now, two questions:
>
> 1.  Does everyone like these details?
> 2.  What are the next steps to add text and get in the spec?
Received on Monday, 9 June 2014 21:32:56 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:24:48 UTC