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

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?