4.2.1 Constructors

MediaStream

See the MediaStream constructor algorithm

No parameters.

MediaStream

See the MediaStream constructor algorithm

Parameter	Type	Nullable	Optional	Description
stream	MediaStream	✘	✘

MediaStream

See the MediaStream constructor algorithm

Parameter	Type	Nullable	Optional	Description
tracks	sequence<MediaStreamTrack>	✘	✘

4.2.2 Attributes

active of type boolean, readonly

This attribute is true if the MediaStream is active and false otherwise.

id of type DOMString, readonly

When a MediaStream object is created, the User Agent MUST generate an identifier string, and MUST initialize the object's id attribute to that string. A good practice is to use a UUID [rfc4122], which is 36 characters long in its canonical form.

The id attribute MUST return the value to which it was initialized when the object was created.

onactive of type EventHandler,

This event handler, of type active, is executed when the MediaStream becomes active.

onaddtrack of type EventHandler,

This event handler, of type addtrack, is executed when a MediaStreamTrack is added to the MediaStream.

oninactive of type EventHandler,

This event handler, of type inactive, is executed when the MediaStream becomes inactive.

onremovetrack of type EventHandler,

This event handler, of type removetrack, is executed when a MediaStreamTrack is removed from the MediaStream.

4.2.3 Methods

addTrack

Adds the given MediaStreamTrack to this MediaStream.

When the addTrack() method is invoked, the User Agent MUST run the following steps:

1. Let track be the MediaStreamTrack argument and stream this MediaStream object.

2. If track is already in stream's track set, then abort these steps.

3. Add track to stream's track set.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘

Return type: void

clone

Clones the given MediaStream and all its tracks.

When the MediaStream.clone() method is invoked, the User Agent MUST run the following steps:

1. Let streamClone be a newly constructed MediaStream object.

2. Initialize streamClone's id attribute to a newly generated value.

3. Let clonedTracks be a list that contains the result of running MediaStreamTrack.clone() on all the tracks in the stream on which this method was called.

4. Let clonedTracks be streamClone's track set.

5. Return streamClone.

No parameters.

Return type: MediaStream

getAudioTracks

Returns a sequence of MediaStreamTrack objects representing the audio tracks in this stream.

The getAudioTracks() method MUST return a sequence that represents a snapshot of all the MediaStreamTrack objects in this stream's track set whose kind is equal to "audio". The conversion from the track set to the sequence is user agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<MediaStreamTrack>

getTrackById

The getTrackById() method MUST return either a MediaStreamTrack object from this stream's track set whose id is equal to trackId, or null, if no such track exists.

Parameter	Type	Nullable	Optional	Description
trackId	DOMString	✘	✘

Return type: MediaStreamTrack, nullable

getTracks

Returns a sequence of MediaStreamTrack objects representing all the tracks in this stream.

The getTracks() method MUST return a sequence that represents a snapshot of all the MediaStreamTrack objects in this stream's track set, regardless of kind. The conversion from the track set to the sequence is User Agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<MediaStreamTrack>

getVideoTracks

Returns a sequence of MediaStreamTrack objects representing the video tracks in this stream.

The getVideoTracks() method MUST return a sequence that represents a snapshot of all the MediaStreamTrack objects in this stream's track set whose kind is equal to "video". The conversion from the track set to the sequence is user agent defined and the order does not have to be stable between calls.

No parameters.

Return type: sequence<MediaStreamTrack>

removeTrack

Removes the given MediaStreamTrack object from this MediaStream.

When the removeTrack() method is invoked, the User Agent MUST remove the MediaStreamTrack object, indicated by the method's argument, from the stream's track set, if present.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘

Return type: void

4.3.1 Life-cycle and Media Flow

Life-cycle

A MediaStreamTrack has two states in its life-cycle: live and ended. A newly created MediaStreamTrack can be in either state depending on how it was created. For example, cloning an ended track results in a new ended track. The current state is reflected by the object's readyState attribute.

In the live state, the track is active and media is available for use by consumers (but may be replaced by zero-information-content if the MediaStreamTrack is muted or disabled, see below).

A muted or disabled MediaStreamTrack renders either silence (audio), black frames (video), or a zero-information-content equivalent. For example, a video element sourced by a muted or disabled MediaStreamTrack (contained within a MediaStream ), is playing but the rendered content is the muted output. When all tracks connected to a source are muted or disabled, the "on-air" or "recording" indicator for that source can be turned off; when the track is no longer muted or disabled, it MUST be turned back on.

The muted/unmuted state of a track reflects whether the source provides any media at this moment. The enabled/disabled state is under application control and determines whether the track outputs media (to its consumers). Hence, media from the source only flows when a MediaStreamTrack object is both unmuted and enabled.

A MediaStreamTrack is muted when the source is temporarily unable to provide the track with data. A track can be muted by a user. Often this action is outside the control of the application. This could be as a result of the user hitting a hardware switch or toggling a control in the operating system / browser chrome. A track can also be muted by the User Agent.

Applications are able to enable or disable a MediaStreamTrack to prevent it from rendering media from the source. A muted track will however, regardless of the enabled state, render silence and blackness. A disabled track is logically equivalent to a muted track, from a consumer point of view.

For a newly created MediaStreamTrack object, the following applies. The track is always enabled unless stated otherwise (for example when cloned) and the muted state reflects the state of the source at the time the track is created.

A MediaStreamTrack object is said to end when the source of the track is disconnected or exhausted.

A MediaStreamTrack can be detached from its source. It means that the track is no longer dependent on the source for media data. If no other MediaStreamTrack is using the same source, the source will be stopped. MediaStreamTrack attributes such as kind and label MUST NOT change values when the source is detached.

When a MediaStreamTrack object ends for any reason (e.g., because the user rescinds the permission for the page to use the local camera, or because the application invoked the stop() method on the MediaStreamTrack object, or because the User Agent has instructed the track to end for any reason) it is said to be ended.

When a MediaStreamTrack track ends for any reason other than the stop() method being invoked, the User Agent MUST queue a task that runs the following steps:

1. If the track's readyState attribute has the value ended already, then abort these steps.

2. Set track's readyState attribute to ended.

3. Detach track's source.

4. Fire a simple event named ended at the object.

If the end of the stream was reached due to a user request, the event source for this event is the user interaction event source.

Media Flow

There are two concepts related to the media flow for a live MediaStreamTrack : muted / not muted, and enabled / disabled.

Muted refers to the input to the MediaStreamTrack. If live samples are not made available to the MediaStreamTrack it is muted.

Muted is out of control for the application, but can be observed by the application by reading the muted attribute and listening to the associated events mute and unmute. There can be several reasons for a MediaStreamTrack to be muted: the user pushing a physical mute button on the microphone, the user toggling a control in the operating system, the user clicking a mute button in the browser chrome, the User Agent (on behalf of the user) mutes, etc.

Enabled/disabled on the other hand is available to application to control (and observe) via the enabled attribute.

The result for the consumer is the same in the meaning that whenever MediaStreamTrack is muted or disabled (or both) the consumer gets zero-information-content, which means silence for audio and black frames for video. In other words, media from the source only flows when a MediaStreamTrack object is both unmuted and enabled. For example, a video element sourced by a muted or disabled MediaStreamTrack (contained in a MediaStream ), is playing but rendering blackness.

For a newly created MediaStreamTrack object, the following applies: the track is always enabled unless stated otherwise (for example when cloned) and the muted state reflects the state of the source at the time the track is created.

4.3.2 Tracks and Constraints

Constraints are set on tracks and may affect sources.

Whether Constraints were provided at track initialization time or need to be established later at runtime, the APIs defined in the ConstrainablePattern Interface allow the retrieval and manipulation of the constraints currently established on a track.

Each track maintains an internal version of the Constraints structure, namely a mandatory set of constraints (no duplicates) and an optional ordered list of individual constraint objects (may contain duplicates). The internal stored constraint structure is exposed to the application by the constraints attribute, and may be modified by the applyConstraints() method.

When applyConstraints() is called, a User Agent MUST queue a task to evaluate those changes when the task queue is next serviced.

If the MediaStreamError event named overconstrained is thrown, the track MUST be muted until either new satisfiable constraints are applied or the existing constraints become satisfiable.

4.3.3 Interface Definition

interface MediaStreamTrack : EventTarget {
    readonly    attribute DOMString             kind;
    readonly    attribute DOMString             id;
    readonly    attribute DOMString             label;
                attribute boolean               enabled;
    readonly    attribute boolean               muted;
                attribute EventHandler          onmute;
                attribute EventHandler          onunmute;
    readonly    attribute boolean               _readonly;
    readonly    attribute boolean               remote;
    readonly    attribute MediaStreamTrackState readyState;
                attribute EventHandler          onended;
    MediaStreamTrack       clone ();
    void                   stop ();
    MediaTrackCapabilities getCapabilities ();
    MediaTrackConstraints  getConstraints ();
    MediaTrackSettings     getSettings ();
    Promise<void>          applyConstraints (MediaTrackConstraints constraints);
                attribute EventHandler          onoverconstrained;
};

enum MediaStreamTrackState {
    "live",
    "ended"
};

4.3.4 Track Source Types

enum SourceTypeEnum {
    "camera",
    "microphone"
};

4.3.5 MediaTrackSupportedConstraints

MediaTrackSupportedConstraints represents the list of constraints recognized by a User Agent for controlling the Capabilities of a MediaStreamTrack object.

Future specification can extend the MediaTrackSupportedConstraints dictionary by defining a partial dictionary with dictionary members of type boolean and an identifier that is a Property Name registered in the [RTCWEB-CONSTRAINTS] registry.

dictionary MediaTrackSupportedConstraints {
    boolean width;
    boolean height;
    boolean aspectRatio;
    boolean frameRate;
    boolean facingMode;
    boolean volume;
    boolean sampleRate;
    boolean sampleSize;
    boolean echoCancellation;
    boolean deviceId;
    boolean groupId;
};

4.3.6 MediaTrackCapabilities

MediaTrackCapabilities represents the Capabilities of a MediaStreamTrack object.

Future specification can extend the MediaTrackCapabilities dictionary by defining a partial dictionary with dictionary members of appropriate type and an identifier that is a Property Name registered in the [RTCWEB-CONSTRAINTS] registry.

dictionary MediaTrackCapabilities {
    (long or LongRange)     width;
    (long or LongRange)     height;
    (double or DoubleRange) aspectRatio;
    (double or DoubleRange) frameRate;
    DOMString               facingMode;
    (double or DoubleRange) volume;
    (long or LongRange)     sampleRate;
    (long or LongRange)     sampleSize;
    sequence<boolean>       echoCancellation;
    DOMString               deviceId;
    DOMString               groupId;
};

4.3.7 MediaTrackConstraints

dictionary MediaTrackConstraints : MediaTrackConstraintSet {
    sequence<MediaTrackConstraintSet> advanced;
};

Future specification can extend the MediaTrackConstraintSet dictionary by defining a partial dictionary with dictionary members of appropriate type and an identifier that is a Property Name registered in the [RTCWEB-CONSTRAINTS] registry.

dictionary MediaTrackConstraintSet {
    ConstrainLong      width;
    ConstrainLong      height;
    ConstrainDouble    aspectRatio;
    ConstrainDouble    frameRate;
    ConstrainDOMString facingMode;
    ConstrainDouble    volume;
    ConstrainLong      sampleRate;
    ConstrainLong      sampleSize;
    ConstrainBoolean   echoCancellation;
    ConstrainDOMString deviceId;
    ConstrainDOMString groupId;
};

4.3.8 MediaTrackSettings

MediaTrackSettings represents the Settings of a MediaStreamTrack object.

Future specification can extend the MediaTrackSettings dictionary by defining a partial dictionary with dictionary members of appropriate type and an identifier that is a Property Name registered in the [RTCWEB-CONSTRAINTS] registry.

dictionary MediaTrackSettings {
    long      width;
    long      height;
    double    aspectRatio;
    double    frameRate;
    DOMString facingMode;
    double    volume;
    long      sampleRate;
    long      sampleSize;
    boolean   echoCancellation;
    DOMString deviceId;
    DOMString groupId;
};

4.4.1 Constructors

MediaStreamTrackEvent

Constructs a new MediaStreamTrackEvent.

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	MediaStreamTrackEventInit	✘	✘

4.4.2 Attributes

track of type MediaStreamTrack, readonly

The track attribute represents the MediaStreamTrack object associated with the event.

4.4.3 Dictionary MediaStreamTrackEventInit Members

track of type MediaStreamTrack, defaulting to null

6.1.1 Attributes

srcObject of type MediaStream, , nullable

Holds the MediaStream that provides media for this element. This attribute overrides both the src attribute and any <source> elements. Specifically, if srcObject is specified, the User Agent MUST use it as the source of media, even if the src attribute is also set or <source> children are present. If the value of srcObject is replaced or set to null the User Agent MUST re-run the media element load algorithm

7.1.1 Attributes

constraintName of type DOMString, readonly , nullable

This attribute is only used for some types of errors. For MediaStreamError with a name of ConstraintNotSatisfiedError or of OverconstrainedError, this attribute MUST be set to the name of the constraint that caused the error.

message of type DOMString, readonly , nullable

A User Agent-dependent string offering extra human-readable information about the error.

name of type DOMString, readonly

The name of the error

7.1.2 Constructors

MediaStreamErrorEvent

Constructs a new MediaStreamErrorEvent.

Parameter	Type	Nullable	Optional	Description
type	DOMString	✘	✘
eventInitDict	MediaStreamErrorEventInit	✘	✘

7.1.3 Attributes

error of type MediaStreamError, readonly , nullable

The MediaStreamError describing the error that triggered the event (if any).

7.1.4 Dictionary MediaStreamErrorEventInit Members

error of type MediaStreamError, nullable, defaulting to null

The MediaStreamError describing the error associated with the event (if any)

9.1.1 Attributes

mediaDevices of type MediaDevices, readonly

Returns the MediaDevices object associated with this Navigator object.

9.2.1 Attributes

ondevicechange of type EventHandler,

This event handler, of type devicechange, is executed when the set of media devices available to the user agent has changed.

9.2.2 Methods

enumerateDevices

Collects information about the User Agents available media input and output devices.

Returns a promise. The promise will be fulfilled with a sequence of MediaDeviceInfo dictionaries representing the User Agent's available media input and output devices if enumeration is successful.

Camera and microphone sources should be enumerable. Specifications that add additional types of source will provide recommendations about whether the source type should be enumerable.

When the enumerateDevices() method is called, the User Agent must run the following steps:

1. Let p be a new promise.

2. Run the following steps asynchronously:

   1. Let resultList be an empty list.

   2. If this method has been called previously within this application session, let oldList be the list of MediaDeviceInfo objects that was produced at that call (resultList); otherwise, let oldList be an empty list.

   3. Probe the User Agent for available media devices, and run the following sub steps for each discovered device, device:

      1. If device is represented by a MediaDeviceInfo object in oldList, append that object to resultList, abort these steps and continue with the next device (if any).

      2. Let deviceInfo be a new MediaDeviceInfo object to represent device.

      3. If device belongs to the same physical device as a device, already represented in oldList or resultList, initialize deviceInfo's groupId member to the groupId value of the existing MediaDeviceInfo object. Otherwise, let deviceInfo's groupId member be a newly generated unique identifier.

      4. Append deviceInfo to resultList.

   4. If none of the local devices are attached to an active MediaStreamTrack in the current browsing context, and if no persistent permission to access these local devices have been granted to the page's origin, let filteredList be a copy of resultList, and all its elements, where the label member is the empty string.

   5. If filteredList is a non-empty list, then resolve p with filteredList. Otherwise, resolve p with resultList.

3. Return p.

No parameters.

Return type: Promise<sequence<MediaDeviceInfo>>

9.2.3 Access control model

The algorithm described above means that the access to media device information depends on whether or not permission has been granted to the page's origin to use media devices.

If no such access has been granted, the MediaDeviceInfo dictionary will contain the deviceId, kind, and groupId.

If access has been granted for a media device, the MediaDeviceInfo dictionary will contain the deviceId, kind, label, and groupId.

9.3.1 Attributes

deviceId of type DOMString, readonly

A unique identifier for the represented device.

All enumerable devices have an identifier that MUST be unique to the application and persistent across sessions. Unique and stable identifiers let the application save, identify the availability of, and directly request specific sources.

This identifier MUST be un-guessable by other applications to prevent the identifier being used to correlate the same user across different applications.

Since deviceId persists across sessions and to reduce its potential as a fingerprinting mechanism, deviceId is to be treated as other persistent storage mechanisms such as cookies [COOKIES]. User agents should reset per-application device identifiers when other persistent storages are cleared.

groupId of type DOMString, readonly

Returns the group identifier of the represented device. Two devices have the same group identifier if they belong to the same physical device; for example a monitor with a built in camera and microphone.

kind of type MediaDeviceKind, readonly

Describes the kind of the represented device.

label of type DOMString, readonly

A label describing this device (for example "External USB Webcam"). If the device has no associated label, then this attribute MUST return the empty string.

10.1.1 Methods

getUserMedia

Prompts the user for permission to use their Web cam or other video or audio input.

The constraints argument is a dictionary of type MediaStreamConstraints.

The successCallback will be invoked with a suitable MediaStream object as its argument if the user accepts valid tracks as described in MediaDevices.getUserMedia().

The errorCallback will be invoked if there is a failure in finding valid tracks or if the user denies permission, as described in MediaDevices.getUserMedia().

When the getUserMedia() method is called, the User Agent MUST run the following steps:

1. Let constraints be the method's first argument.

2. Let successCallback be the callback indicated by the method's second argument.

3. Let errorCallback be the callback indicated by the method's third argument.

4. Invoke MediaDevices.getUserMedia() with constraints as the argument, and let p be the resulting promise.

5. Upon fulfillment of p with value stream, run the following step:

   1. Invoke successCallback with stream as the argument.

6. Upon rejection of p with reason r, run the following step:

   1. Invoke errorCallback with r as the argument.

Parameter	Type	Nullable	Optional	Description
constraints	MediaStreamConstraints	✘	✘
successCallback	NavigatorUserMediaSuccessCallback	✘	✘
errorCallback	NavigatorUserMediaErrorCallback	✘	✘

Return type: void

10.2.1 Methods

getSupportedConstraints

Returns a dictionary whose members are the constrainable properties known to the User Agent. A supported constrainable property MUST be represented by a member whose name is the constraint name and whose value is true. Any constrainable properties not supported by the User Agent MUST not be present in the returned dictionary. The values returned represent what the browser implements and will not change during a session.

No parameters.

Return type: MediaTrackSupportedConstraints

getUserMedia

Prompts the user for permission to use their Web cam or other video or audio input.

Issue 3

(Remove when other issues are removed. This is only here to keep the issues from being renumbered)

The constraints argument is a dictionary of type MediaStreamConstraints.

Returns a promise. The promise will be fulfilled with a suitable MediaStream object if the user accepts valid tracks as described below.

The promise will be rejected if there is a failure in finding valid tracks or if the user denies permission, as described below.

When the getUserMedia() method is called, the User Agent MUST run the following steps:

1. Let p be a new promise.

2. Let constraints be the method's first argument.

3. Run the following steps asynchronously:

   1. Let requestedMediaTypes be the set of media types in constraints with either a dictionary value or a value of "true".

   2. If requestedMediaTypes is the empty set, let error be a new MediaStreamError object whose name attribute has the value NotSupportedError and jump to the step labeled Error Task below.

   3. Let finalSet be an (initially) empty set.

   4. For each media type T in requestedMediaTypes,

      1. For each possible source for that media type, construct an unconstrained MediaStreamTrack with that source as its source.

         Call this set of tracks the candidateSet.

      2. If the value of the T entry of constraints is "true", set CS to the empty constraint set (no constraint). Otherwise, continue with CS set to the value of the T entry of constraints.

      3. Run the SelectSettings algorithm on each track in CandidateSet with CS as the constraint set. If the algorithm does not return undefined, add the track to finalSet. This eliminates devices unable to satisfy the constraints, by verifying that at least one settings dictionary exists that satisfies the constraints.

      If finalSet is the empty set, let error be a new MediaStreamError object whose name attribute has the value NotFoundError and jump to the step labeled Error Task below.

   5. Optionally, e.g., based on a previously-established user preference, for security reasons, or due to platform limitations, jump to the step labeled Permission Failure below.

   6. Prompt the user in a User Agent specific manner for permission to provide the entry script's origin with a MediaStream object representing a media stream.

      The provided media MUST include precisely one track of each media type in requestedMediaTypes from the finalSet. The decision of which tracks to choose from the finalSet is completely up to the user agent and may be determined by asking the user. Once selected, the source of a MediaStreamTrack MUST not change.

      The user agent MAY use the value of the computed "fitness distance" from the SelectSettings algorithm, or any other internally-available information about the devices, as an input to the selection algorithm.

      User Agents are encouraged to default to using the user's primary or system default camera and/or microphone (when possible) to generate the media stream. User Agents MAY allow users to use any media source, including pre-recorded media files.

      If the user grants permission to use local recording devices, User Agents are encouraged to include a prominent indicator that the devices are "hot" (i.e. an "on-air" or "recording" indicator), as well as a "device accessible" indicator indicating that the page has been granted access to the source.

      If the user denies permission, jump to the step labeled Permission Failure below. If the user never responds, this algorithm stalls on this step.

      If the user grants permission but a hardware error such as an OS/program/webpage lock prevents access, jump to the step labeled Unavailable Failure below.

      If the user grants permission but device access fails for any reason other than those listed above, jump to the step labeled General Failure below.

   7. Let stream be the MediaStream object for which the user granted permission.

   8. Run the ApplyConstraints() algorithm on all tracks in stream with the appropriate constraints.

   9. Resolve p with stream.

   10. Abort these steps.

   11. Permission Failure: Let error be a new MediaStreamError object whose name attribute has the value PermissionDeniedError and jump to the step labeled Error Task below.

   12. Constraint Failure: Let error be a new MediaStreamError object whose name attribute has the value ConstraintNotSatisfiedError and whose constraintName attribute is set to the name of the constraint that caused the error.

   13. Unavailable Failure: Let error be a new MediaStreamError object whose name attribute has the value SourceUnavailableError and jump to the step labeled Error Task below.

   14. General Failure: Let error be a new MediaStreamError object whose name attribute has the value AbortError and jump to the step labeled Error Task below.

   15. Error Task: Reject p with error.

4. Return p.

Parameter	Type	Nullable	Optional	Description
constraints	MediaStreamConstraints	✘	✘

Return type: Promise<MediaStream>

10.3.1 Dictionary MediaStreamConstraints Members

audio of type (boolean or MediaTrackConstraints), defaulting to false

If true, it requests that the returned MediaStream contain an audio track. If a Constraints structure is provided, it further specifies the nature and settings of the audio Track. If false, the MediaStream MUST not contain an audio Track.

video of type (boolean or MediaTrackConstraints), defaulting to false

If true, it requests that the returned MediaStream contain a video track. If a Constraints structure is provided, it further specifies the nature and settings of the video Track. If false, the MediaStream MUST not contain a video Track.

10.4.1 Callback NavigatorUserMediaSuccessCallback Parameters

stream of type MediaStream

Issue 4

Add explanation of handleEvent

10.5.1 Callback NavigatorUserMediaErrorCallback Parameters

error of type MediaStreamError

Issue 5

Add explanation of handleEvent

11.1.1 Attributes

onoverconstrained of type EventHandler,

This event handler, of type overconstrained, is executed when the User Agent is no longer able to satisfy the requiredConstraints from the currently valid Constraints.

When executed, the event handler is passed a MediaStreamErrorEvent as parameter, which references a MediaStreamError whose name is OverconstrainedError, and whose constraintName attribute is set to one of the requiredConstraints that can no longer be satisfied. The message attribute of the MediaStreamError SHOULD contain a string that is useful for debugging. The conditions under which this error might occur are platform and application-specific. For example, the user might physically manipulate a camera in a way that makes it impossible to provide a resolution that satisfies the constraints. The User Agent MAY take other actions as a result of the overconstrained situation.

11.1.2 Methods

applyConstraints

The applyConstraints() algorithm for applying constraints is stated below. Here are some preliminary definitions that are used in the statement of the algorithm:

We use the term settings dictionary for the set of values that might be applied as settings to the object.

We define the fitness distance between a settings dictionary and a constraint set CS as the sum, for each constraint provided for a constraint name in CS, of the following values:

1. If the constraint is not supported by the browser, the fitness distance is 0.

2. If the constraint is required ('min', 'max', or 'exact'), and the settings dictionary's value for the constraint does not satisfy the constraint, the fitness distance is positive infinity.

3. If no ideal value is specified, the fitness distance is 0.
4. For all positive numeric non-required constraints (such as height, width, frameRate, aspectRatio, sampleRate and sampleSize), the fitness distance is the result of the formula

   (actual == ideal) ? 0 : |actual -
                     ideal|/max(|actual|,|ideal|)

5. For all string and enum non-required constraints (sourceId, groupId, facingMode, echoCancellation), the fitness distance is the result of the formula

   (actual == ideal) ? 0 : 1

More definitions:

• We refer to each element of a ConstraintSet (other than the special term 'advanced') as a 'constraint' since it is intended to constrain the acceptable settings for the given property from the full list or range given in the corresponding Capability of the ConstrainablePattern object to a value that is within the range or list of values it specifies.
• We refer to the "effective Capability" C of an object O as the possibly proper subset of the possible values of C (as returned by getCapabilities) taking into consideration environmental limitations and/or restrictions placed by other constraints. For example given a ConstraintSet that constrains the aspectRatio, height, and width properties, the values assigned to any two of the properties limit the effective Capability of the third. The set of effective Capabilities may be platform dependent. For example, on a resource-limited device it may not be possible to set properties P1 and P2 both to 'high', while on another less limited device, this may be possible.
• A settings dictionary, which is a set of values for the constrainable properties of an object O, satisfies ConstraintSet CS if the fitness distance between the set and CS is less than infinity.
• A set of ConstraintSets CS1...CSn (n >= 1) can be satisfied by an object O if it is possible to find a settings dictionary of O that satisfies CS1...CSn simultaneously.
• To apply a set of ConstraintSets CS1...CSn to object O is to choose such a sequence of values that satisfy CS1...CSn and assign them as the settings for the properties of O.

We define the SelectSettings algorithm as follows:

1. Each constraint specifies one or more values (or a range of values) for its property. A property MAY appear more than once in the list of 'advanced' ConstraintSets. If an empty object or list has been given as the value for a constraint, it MUST be interpreted as if the constraint were not specified (in other words, an empty constraint == no constraint).

   Note that unknown properties are discarded by WebIDL, which means that unknown/unsupported required constraints will silently disappear. To avoid this being a surprise, application authors are expected to first use the getSupportedConstraints() method as shown in the Examples below.

2. Let object be the ConstrainablePattern object on which this algorithm is applied. Let copy be an unconstrained copy of object (i.e., copy should behave as if it were object with all ConstraintSets removed.)

3. For every possible settings dictionary of copy compute its fitness distance, treating bare values of properties as ideal values. Let candidates be the set of settings dictionaries for which the fitness distance is finite.

4. If candidates is empty, return undefined as the result of the function.

5. Iterate over the 'advanced' ConstraintSets in newConstraints in the order in which they were specified. For each ConstraintSet:

   1. compute the fitness distance between it and each settings dictionary in candidates, treating bare values of properties as exact.

   2. If the fitness distance is finite for one or more settings dictionaries in candidates, keep those settings dictionaries in candidates, discarding others.

      If the fitness distance is infinite for all settings dictionaries in candidates, ignore this ConstraintSet.

6. Select one settings dictionary from the list of possible settings, and return this as the result of the SelectSettings() algorithm. The UA SHOULD use the one with the smallest fitness distance, as calculated in step 3.

When applyConstraints is called, the User Agent MUST run the following steps:

1. Let p be a new promise.

2. Let newContraints be the argument to this function.

3. Run the following steps asynchronously:

   1. Let successfulSettings be the result of running the SelectSettings algorithm with newConstraints as the constraint set.

   2. If successfulSettings is undefined, reject p with a new MediaStreamError with name ConstraintNotSatisfied and constraintName set to any of the required constraints that could not be satisfied, and abort these steps. existingConstraints remain in effect in this case.

   3. In a single operation, remove existingConstraints from object, apply newConstraints, and apply successfulSettings as the current settings.
   4. Finally, resolve p. From this point on until applyConstraints() is called successfully again, getConstraints() must return the newConstraints that were passed as an argument to this call.

4. Return p.

Note

Any implementation that has the same result as the algorithm above is an allowed implementation. For instance, the implementation may choose to keep track of the maximum and minimum values for a setting that are OK under the constraints considered, rather than keeping track of all possible values for the setting.

Note

When picking a settings dictionary, the UA can use any information available to it. Examples of such information may be whether the selection is done as part of device selection in getUserMedia, whether the energy usage of the camera varies between the settings dictionaries, or whether using a settings dictionary will cause the device driver to apply resampling.

The User Agent MAY choose new settings for the constrainable properties of the object at any time. When it does so it MUST attempt to satisfy the current Constraints, in the manner described in the algorithm above.

Parameter	Type	Nullable	Optional	Description
constraints	Constraints	✘	✘	A new constraint structure to apply to this object.

Return type: Promise<void>

getCapabilities

The getCapabilities() method returns the dictionary of the names of the constrainable properties that the object supports.

Note

It is possible that the underlying hardware may not exactly map to the range defined in the registry entry. Where this is possible, the entry SHOULD define how to translate and scale the hardware's setting onto the values defined in the entry. For example, suppose that a registry entry defines a hypothetical fluxCapacitance property that ranges from -10 (min) to 10 (max), but there are common hardware devices that support only values of "off" "medium" and "full". The registry entry might specify that for such hardware, the user agent should map the range value of -10 to "off", 10 to "full", and 0 to "medium". It might also indicate that given a ConstraintSet imposing a strict value of 3, the User Agent should attempt to set the value of "medium" on the hardware, and and that getSettings() should return a fluxCapacitance of 0, since that is the value defined as corresponding to "medium".

No parameters.

Return type: Capabilities

getConstraints

The getConstraints method returns the Constraints that were the argument to the most recent successful call of applyConstraints(), maintaining the order in which they were specified. Note that some of the optional ConstraintSets returned may not be currently satisfied. To check which ConstraintSets are currently in effect, the application should use getSettings.

No parameters.

Return type: Constraints

getSettings

The getSettings() method returns the current settings of all the constrainable properties of the object, whether they are platform defaults or have been set by applyConstraints(). Note that the actual setting of a property MUST be a single value.

No parameters.

Return type: Settings

11.2.1 Dictionary DoubleRange Members

max of type double

The maximum legal value of this property.

min of type double

The minimum value of this Property.

11.2.2 Dictionary ConstrainDoubleRange Members

exact of type double

The exact required value for this property.

ideal of type double

The ideal (target) value for this property.

11.2.3 Dictionary LongRange Members

max of type long

The maximum legal value of this property.

min of type long

The minimum value of this property.

11.2.4 Dictionary ConstrainLongRange Members

exact of type long

The exact required value for this property.

ideal of type long

The ideal (target) value for this property.

11.2.5 Dictionary ConstrainBooleanParameters Members

exact of type boolean

The exact required value for this property.

ideal of type boolean

The ideal (target) value for this property.

11.2.6 Dictionary ConstrainDOMStringParameters Members

exact of type (DOMString or sequence<DOMString>)

The exact required value for this property.

ideal of type (DOMString or sequence<DOMString>)

The ideal (target) value for this property.

11.5.1 Dictionary Constraints Members

advanced of type sequence<ConstraintSet>

The list of ConstraintSets that the User Agent MUST attempt to satisfy, in order, skipping only those that cannot be satisfied. The order of these ConstraintSets is significant. In particular, when they are passed as an argument to applyConstraints, the User Agent MUST try to satisfy them in the order that is specified. Thus if optional ConstraintSets C1 and C2 can be satisfied individually, but not together, then whichever of C1 and C2 is first in this list will be satisfied, and the other will not. The User Agent MUST attempt to satisfy all optional ConstraintSets in the list, even if some cannot be satisfied. Thus, in the preceding example, if optional constraint C3 is specified after C1 and C2, the User Agent will attempt to satisfy C3 even though C2 cannot be satisfied. Note that a given property name may occur only once in each ConstraintSet but may occur in more than one ConstraintSet.