From Jan-Ivar, pointing out several issues with the Constrainable pattern as applied to MediaTrack:


The spec still leaves several types to be inferred by the implementer around constraints:

1. In [1]:
> partial interface MediaDevices {
>     static Dictionary getSupportedConstraints (DOMString kind);

"Dictionary" is not defined. To implement this, we'd need something like:


  dictionary SupportedMediaTrackConstraintSet {
      boolean width;
      boolean height;
      boolean aspectRatio;
      boolean frameRate;
      boolean facingMode;
      boolean volume;
      boolean sampleRate;
      boolean sampleSize;
      boolean echoCancelation;
      boolean sourceId;
      boolean groupId;
      // basically a boolean rehash of MediaTrackConstraintSet
  };

  static SupportedMediaTrackConstraintSet getSupportedConstraints (DOMString kind);

or simply:

  static MediaTrackConstraintSet getSupportedConstraints (DOMString kind);

since UAs can return non-zero values in MediaTrackConstraintSet just fine!


2. In [2]:
> interface MediaStreamTrack : EventTarget {
>     ...
>     Capabilities          getCapabilities ();
>     MediaTrackConstraints getConstraints ();
>     Settings              getSettings ();

Capabilities and Settings are not defined in this use of the Constrainable pattern. To implement this, we'd need something like:


  dictionary MediaTrackSettingSet {
      long            width;
      long            height;
      double          aspectRatio;
      double          frameRate;
      VideoFacingMode facingMode;
      double          volume;
      long            sampleRate;
      long            sampleSize;
      boolean         echoCancelation;
      DOMString       sourceId;
      DOMString       groupId;
      // basically a bare-value rehash of MediaTrackConstraintSet
  };

  interface MediaStreamTrack : EventTarget {
      ...
      MediaTrackConstraintSet getCapabilities ();
      MediaTrackConstraints   getConstraints ();
      MediaTrackSettingSet    getSettings ();

or simply:

  interface MediaStreamTrack : EventTarget {
      ...
      MediaTrackConstraintSet getCapabilities ();
      MediaTrackConstraints   getConstraints ();
      MediaTrackConstraintSet getSettings ();

since UAs can return bare values in MediaTrackConstraintSet just fine!

3. In the Constrainable Pattern in [3]:
> Capabilities are dictionary containing one or more key-value pairs, where each key must be a constrainable property defined in the registry, and each value must be a subset of the set of values defined for that property in the registry. The exact syntax of the value expression depends on the type of the property but is of type ConstraintValues . The Capabilities dictionary specifies the subset of the constrainable properties and values from the registry that the UA supports.

Typo: "Capabilities are dictionary" -> "Capabilities is a dictionary". Importantly, all capabilities are in one dictionary.

The type "ConstraintValues" is not defined anywhere. Do we mean "members of ConstraintSet" here? If so, that makes Capabilities of type ConstraintSet, yet we're leaving that deduction to the reader. IMHO prose and examples are no substitute for definitions.


4. In the Constrainable Pattern in [4]:
> A Setting is a dictionary containing one or more key-value pairs. It must contain each key returned in getCapabilities(). There must be a single value for each key and the value must a member of the set defined for that property by capabilities(). The Settings dictionary contains the actual values that the UA has chosen for the object's Capabilities. The exact syntax of the value depends on the type of the property.

Typo: "A Setting is a dictionary" -> "Settings is a dictionary". Importantly, all settings are in one dictionary.
Typo: "the value must a member" -> "the value must be a member"

We're leaving the reader to deduce that Settings is a bare-values-only subset of ConstraintSet. IMHO prose and examples are no substitute for definitions.

5. In the Constrainable Pattern in [5]:
> typedef Dictionary ConstraintSet;

"Dictionary" is not defined, and even if it were, it wouldn't have the right members, so a typedef infers the wrong thing. We could say:

  dictionary ConstraintSet { /* members */ };


6. In [6]:
> dictionary MediaTrackConstraintSet {
>     ConstrainLong            width;
>     ConstrainLong            height;
>     ConstrainDouble          aspectRatio;
>     ConstrainDouble          frameRate;
>     ConstrainVideoFacingMode facingMode;
>     ConstrainDouble          volume;
>     ConstrainLong            sampleRate;
>     ConstrainLong            sampleSize;
>     boolean                  echoCancelation;
>     ConstrainDOMString       sourceId;
>     DOMString                groupId;
> };

groupId seems to have the wrong type. Why not ConstrainDOMString groupId ?

.: Jan-Ivar :.

[1] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#mediadevices-interface-extensions
[2] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#media-stream-track-interface-definition
[3] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#capabilities
[4] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#settings
[5] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#constraints
[6] http://dev.w3.org/2011/webrtc/editor/archives/20140817/getusermedia.html#dictionary-mediatrackconstraints-members