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

The MediaStream.active attribute MUST return true if this 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,

The event type of this event handler is active.

onaddtrack of type EventHandler,

The event type of this event handler is addtrack.

oninactive of type EventHandler,

The event type of this event handler is inactive.

onremovetrack of type EventHandler,

The event type of this event handler is removetrack.

4.2.3 Methods

addTrack

Adds the given MediaStreamTrack to this MediaStream.

When the addTrack() method is invoked, the User Agent MUST add the track, specified by the method's first argument, to this MediaStream.

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. Clone each track in this MediaStream object and add the result to streamClone's track set.

4. 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.

If all MediaStreamTracks that are using the same source are ended, the source will be stopped.

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. Notify track's source that track is ended so that the source may be stopped, unless other MediaStreamTrack objects depend on it.

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 dimensions 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.

To update a track's muted state to newState, the User Agent MUST queue a task to run the following steps:

1. Let track be the MediaStreamTrack in question.

2. Set track's muted attribute to newState.

3. If newState is true let eventName be mute, otherwise unmute.

4. Fire a simple event named eventName on track.

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

The result for the consumer is the same in the sense 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 overconstrained event 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

[Exposed=Window]
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 specifications 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 = true;
             boolean height = true;
             boolean aspectRatio = true;
             boolean frameRate = true;
             boolean facingMode = true;
             boolean volume = true;
             boolean sampleRate = true;
             boolean sampleSize = true;
             boolean echoCancellation = true;
             boolean latency = true;
             boolean channelCount = true;
             boolean deviceId = true;
             boolean groupId = true;
};

4.3.6 MediaTrackCapabilities

MediaTrackCapabilities represents the Capabilities of a MediaStreamTrack object.

Future specifications 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;
             (double or DoubleRange) latency;
             (long or LongRange)     channelCount;
             DOMString               deviceId;
             DOMString               groupId;
};

4.3.7 MediaTrackConstraints

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

Future specifications 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;
             ConstrainDouble    latency;
             ConstrainLong      channelCount;
             ConstrainDOMString deviceId;
             ConstrainDOMString groupId;
};

4.3.8 MediaTrackSettings

MediaTrackSettings represents the Settings of a MediaStreamTrack object.

Future specifications 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;
             double    latency;
             long      channelCount;
             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, required

7.2.1 OverconstrainedError Constructor

The OverconstrainedError Constructor is the %OverconstrainedError% intrinsic object. When OverconstrainedError is called as a function rather than as a constructor, it creates and initializes a new OverconstrainedError object. A call of the object as a function is equivalent to calling it as a constructor with the same arguments. Thus the function call OverconstrainedError(...) is equivalent to the object creation expression new OverconstrainedError(...) with the same arguments.

The OverconstrainedError constructor is designed to be subclassable. It may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified OverconstrainedError behaviour must include a super call to the OverconstrainedError constructor to create and initialize the subclass instance with an [[ErrorData]] internal slot.

7.2.2 Properties of the OverconstrainedError Constructor

The value of the [[Prototype]] internal slot of the OverconstrainedError constructor is the intrinsic object %Error%.

Besides the length property (whose value is 1), the OverconstrainedError constructor has the following properties:

7.2.3 Properties of the OverconstrainedError Prototype Object

The OverconstrainedError prototype object is an ordinary object. It is not an Error instance and does not have an [[ErrorData]] internal slot.

The value of the [[Prototype]] internal slot of the OverconstrainedError prototype object is the intrinsic object %ErrorPrototype%.

7.2.4 Properties of OverconstrainedError Instances

OverconstrainedError instances are ordinary objects that inherit properties from the OverconstrainedError prototype object and have an [[ErrorData]] internal slot whose value is undefined. The only specified use of [[ErrorData]] is by Object.prototype.toString ([ES6], section 19.1.3.6) to identify instances of Error or its various subclasses.

7.2.5 Constructors

OverconstrainedErrorEvent

Constructs a new OverconstrainedErrorEvent.

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

7.2.6 Attributes

error of type OverconstrainedError, readonly , nullable

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

7.2.7 Dictionary OverconstrainedErrorEventInit Members

error of type OverconstrainedError, , nullable, defaulting to null

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

7.3.1 Constructors

ErrorEvent

Constructs a new ErrorEvent.

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

7.3.2 Attributes

error of type Error, readonly , nullable

If the event was raised because of an error, this attribute may be set to that error object.

7.3.3 Dictionary ErrorEventInit Members

error of type Error, , nullable, defaulting to null

If the event was raised because of an error, this attribute may be set to that error object.

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,

The event type of this event handler is devicechange.

9.2.2 Methods

enumerateDevices

Collects information about the User Agent's available media input and output devices.

This method 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 in parallel:

   1. Let resultList be an empty list.

   2. If this method has been called previously within this browsing 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 has 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 page's origin. As long as no local device has been attached to an active MediaStreamTrack in a page from this origin, and no persistent permission to access local devices has been granted to this origin, then this identifier MUST NOT be reusable after the end of the current browsing session.

However, if any local devices have been attached to an active MediaStreamTrack in a page from this origin, or persistent permission to access local devices has been granted to this origin, then this identifier MUST be persisted across browsing 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 applications of other origins to prevent the identifier being used to correlate the same user across different origins.

Since deviceId may persist across browsing 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 MUST reset per-origin 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.

9.3.2 Serializer

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. Run the steps specified by the getUserMedia() algorithm 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 browsing session.

No parameters.

Return type: MediaTrackSupportedConstraints

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.

This method 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. Let requestedMediaTypes be the set of media types in constraints with either a dictionary value or a value of "true".

4. If requestedMediaTypes is the empty set, reject p with a new DOMException object whose name attribute has the value NotSupportedError and return p.

5. Run the following steps in parallel:

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

   2. 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.

         If candidateSet is the empty set, reject p with a new DOMException object whose name attribute has the value NotFoundError and abort these steps.

      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 constraint be any required constraint whose fitness distance was infinity for all settings dictionaries examined while executing the SelectSettings algorithm, let message be either undefined or an informative human-readable message, and reject p with a new OverconstrainedError created by calling OverconstrainedError(constraint, message), then abort these steps.

   3. 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.

   4. 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, reject p with a new DOMException object whose name attribute has the value NotReadableError and abort these steps.

      If the user grants permission but device access fails for any reason other than those listed above, reject p with a new DOMException object whose name attribute has the value AbortError and abort these steps.

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

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

   7. Resolve p with stream and abort these steps.

   8. Permission Failure: Reject p with a new DOMException object whose name attribute has the value SecurityError.

6. 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

MediaStream object representing the stream to which the user granted permission as described in the navigator.getUserMedia() algorithm.

10.5.1 Callback NavigatorUserMediaErrorCallback Parameters

error of type MediaStreamError

Error in obtaining a MediaStream as described in the failure steps of the navigator.getUserMedia() algorithm.

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 an OverconstrainedErrorEvent as parameter, which references an OverconstrainedError whose constraint attribute is set to one of the requiredConstraints that can no longer be satisfied. The message attribute of the OverconstrainedError 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 in parallel:

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

   2. If successfulSettings is undefined, let failedConstraint be any required constraint whose fitness distance was infinity for all settings dictionaries examined while executing the SelectSettings algorithm, let message be either undefined or an informative human-readable message, and reject p with a new OverconstrainedError created by calling OverconstrainedError(failedConstraint, message). The 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 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>,

This is 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.