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

I also like the idea of changing the name of "advanced", but my purpose
here is to flesh out the consensus that was reached in DC, and that was not
part of the consensus, and I don't want to vary to much from what we agreed
on, lest we end up not agreeing on anything again.


On Mon, Jun 9, 2014 at 2:32 PM, cowwoc <cowwoc@bbs.darktech.org> wrote:

> 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?
>>
>
>
>