Re: WebIDL-compatible syntax compromise

What will the MediaTrackConstraintSet WebIDL look like?


On Apr 1, 2014, at 7:17 PM, Dan Burnett <dburnett@voxeo.com> wrote:

> At the teleconference last week we were tasked with finding a way to adjust the current constraint syntax in the specification, without loss of expressivity, into a syntax that was WebIDL-compatible.  We may have done one better.
> 
> We have found a workable compromise.  It can be expressed with dictionaries in WebIDL, retains the full expressive power of the current proposal, and offers simpler default operation to users.  Here's a rich example of the syntax to study (full WebIDL below): 
> 
>   var constraints = 
>   { 
>     require: ["width", "height"], 
>     width: {min: 640}, 
>     height: {min: 480}, 
>     frameRate: 40, 
>     facingMode: "user", 
>     advanced: [{width: 1920, height: 1280}, 
>                {aspectRatio: 1.3333333333}] 
>   }; 
> 
> In this dictionary, there are three types of constraints: required, non-required and advanced (you wouldn't use all three typically):
> 	• Required.
> 
> Members of the top-level dictionary whose names are in the 'require' list (the first 'width' and 'height' members in the example.) Collectively, these correspond to the mandatory ConstraintSet in the existing spec.  The UA must fail if any top-level members named in the require list are missing or unsupported by the UA.  Given how dictionaries work, this means that required constraints unknown to the UA fail.
> 
> 	• Non-required.
> 
> Remaining members of the top-level dictionary whose names are NOT in the 'require' list  (the top-level 'frameRate' and 'facingMode' entries in the example.) These do not correspond to anything in the existing spec. 
> 
> 	• Advanced.
> 
> Dictionaries sequenced in 'advanced'. These correspond to the optional sequence of ConstraintSets in the existing spec. 
> 
> Any of these three types of constraints may be absent from a call to getUserMedia  or track.applyConstraints. If all three are missing, then the call is unconstrained, which in the case of gUM means the UA can pick any device it wants, and in the case of applyConstraints means all currently applied constraints must be removed. 
> 
> gUM works substantially as it does now, with the addition that the new non-required constraints must be applied as a final step.  Specifically, when gUM is called, the UA must first remove from consideration all devices that do not meet all of the required constraints.  If there are no devices left, the UA must call the error callback.  Otherwise, the next step is as defined in the current spec, that it must iterate over the optional (now advanced) ConstraintSets to perform a ranking, at each round removing from a so-called "winners' pool" all devices that do not satisfy the current ConstraintSet.  If in any round there are no devices left, the UA must back up to the set from the previous round and skip to the next round.  When the UA ends this process, it must finally rank just the winners by how many individual non-required constraints they satisfy.  Non-required constraints are to be considered individually and order must not matter.  If this still does not produce a winner, the UA must decide using any tie-breaker it wants.
> 
> When applyConstraints is called, if the Track in question cannot satisfy all the required constraints, the UA must call the failure callback.   Otherwise, it must apply the required constraints, then apply the 'advanced' ConstraintSets in order, skipping any ConstraintSet that cannot be satisfied.  When it finishes, the UA must attempt to apply, individually, each non-required constraint.  It must satisfy the largest number of non-required constraints it can, in any order. Then the UA must call the success callback. 
> 
> WebIDL (tentative): 
> dictionary MediaStreamConstraints { 
>     (boolean or MediaTrackConstraints) video = false; 
>     (boolean or MediaTrackConstraints) audio = false; 
>     DOMString peerIdentity; 
> }; 
> 
> dictionary MediaTrackConstraints : MediaTrackConstraintSet { 
>     sequence<DOMString> require; 
>     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; 
> 
>     // Extended through gUM-specific IANA registry. 
> }; 
> 
> typedef (long or ConstrainLongRange) ConstrainLong; 
> typedef (double or ConstrainDoubleRange) ConstrainDouble; 
> typedef (VideoFacingModeEnum or sequence<VideoFacingModeEnum>) ConstrainVideoFacingMode; 
> typedef (DOMString or sequence<DOMString>) ConstrainDOMString; 
> 
> 
> 
> Thanks,
> 
> Dan Burnett, Jan-Ivar Bruaroey, and Jim Barnett
> 

Received on Wednesday, 2 April 2014 14:22:38 UTC