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 returns true if the MediaStream is active (see inactive), and false otherwise.

When a MediaStream object is created, its active attribute MUST be set to true, unless stated otherwise (for example by the MediaStream() constructor algorithm).

id of type DOMString, readonly

When a MediaStream object is created, the user agent MUST generate a globally unique identifier string, and MUST initialize the object's id attribute to that string. Such strings MUST only use characters in the ranges U+0021, U+0023 to U+0027, U+002A to U+002B, U+002D to U+002E, U+0030 to U+0039, U+0041 to U+005A, U+005E to U+007E, and MUST be 36 characters long.

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, MUST be supported by all objects implementing the MediaStream interface.

onaddtrack of type EventHandler,

This event handler, of type addtrack, MUST be supported by all objects implementing the MediaStream interface.

oninactive of type EventHandler,

This event handler, of type inactive, MUST be supported by all objects implementing the MediaStream interface.

onremovetrack of type EventHandler,

This event handler, of type removetrack, MUST be supported by all objects implementing the MediaStream interface.

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 trackSetClone be a list that contains the result of running MediaStreamTrack.clone() on all the tracks in this stream.

4. Let trackSetClone be streamClone's track set.

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 stable between calls.

No parameters.

Return type: sequence<MediaStreamTrack>

getTrackById

The getTrackById() method MUST return the first MediaStreamTrack object in this stream's track set whose id is equal to trackId. The method MUST return null if no track matches the trackId argument.

Parameter	Type	Nullable	Optional	Description
trackId	DOMString	✘	✘

Return type: MediaStreamTrack, nullable

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 stable between calls.

No parameters.

Return type: sequence<MediaStreamTrack>

removeTrack

Removes the given MediaStreamTrack from this MediaStream.

When the removeTrack() method is invoked, the user agent MUST remove the track, 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

A MediaStreamTrack has three stages in its lifecycle; new, live and ended. A track begins as new prior to being connected to an active source.

Once connected, the started event fires and the track becomes live. In the live state, the track is active and media is available for rendering at a MediaStream consumer.

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.

The muted/unmuted state of a track reflects if the source provides any media at this moment. The enabled/disabled state is under application control and determines if 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 or browser chrome. A track can also be muted by the user agent. For example, a track that is a member of a MediaStream, received via a RTCPeerConnection [WEBRTC10], is muted if the application on the other side disables the corresponding track in the MediaStream being sent.

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.

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 data comes from a finite file and the file's end has been reached and the user has not requested that it be looped, or because the UA has instructed the track to end for any reason, it is said to be ended. When track instance track ends for any reason other than the stop() method being invoked on the MediaStreamTrack object that represents track, 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. (The stop() method was probably called just before the track stopped for other reasons.)

2. Set track's readyState attribute to ended.

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

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 Constrainable 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. Similarly, if the sourceType changes, then the user agent MUST perform the same actions to re-evaluate the constraints of each track affected by that source change.

If the MediaError 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

MediaStreamTrack implements Constrainable;

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          onstarted;
                attribute EventHandler          onended;
    Settings         getNativeSettings ();
    MediaStreamTrack clone ();
    void             stop ();
};

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

4.3.4 Track Source Types

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

4.3.5 Isolated Media Streams

When the peerIdentity option is supplied to getUserMedia, the resulting MediaStream is isolated so that its content is not accessible to any application. An isolated MediaStream may be used for two purposes:

• Displayed in an appropriate tag (e.g., a video or audio element). The browser MUST ensure that content is inaccessible to the application by ensuring that the resulting content is given the same protections as content that is CORS cross-origin, as described in the relevant Security and privacy considerations section of [HTML5].

• Used as the argument to addStream() for an RTCPeerConnection, subject to the restrictions detailed in [WEBRTC10].

A MediaStreamTrack that is added to another MediaStream remains isolated. Tracks that are isolated can be added to other MediaStreams, but this causes the resulting MediaStream to have a combination of isolation restrictions. A MediaStream containing MediaStreamTrack instances with mixed isolation properties can be displayed, but cannot be sent using RTCPeerConnection.

Any peerIdentity property MUST be retained on cloned copies of MediaStreamTracks.

4.4.1 Constructors

MediaStreamTrackEvent

TODO

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, nullable

TODO

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 UA 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 UA MUST re-run the media element load algorithm

9.1.1 Methods

getMediaDevices

Collects information about the user agents available media input and output devices; for example a web camera or a headset. The method MUST only return information that the script is authorized to access (TODO expand authorized).

When the getMediaDevices() method is called, the user agent must queue a task that runs the following steps:

1. Let resultCallback be the callback indicated by the methods first argument.

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. Let resultList be an empty list.

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

5. Invoke resultCallback with resultList as its argument.

Parameter	Type	Nullable	Optional	Description
resultCallback	MediaDeviceInfoCallback	✘	✘

Return type: void

9.2.1 Callback MediaDeviceInfoCallback Parameters

deviceInfoList of type sequence<MediaDeviceInfo>

A sequence of MediaDeviceInfo objects representing the result of a call to Navigator.getMediaDevices() .

9.2.2 Dictionary MediaDeviceInfo Members

deviceId of type DOMString

The unique id for the represented device.

groupId of type DOMString

Returns the group identifier of the represented device. Two devices has the same group identifier if they belong to the same physical device; for example a headset.

kind of type MediaDeviceKind

Describes the kind of the represented device.

label of type DOMString

A label describing this device (for example "External USB Webcam"). If the device has no associated label, then this dictionary member 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.

Issue 2

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

The constraints argument is an object of type MediaStreamConstraints.

The successCallback will be invoked with a suitable MediaStream object as its argument if the user accepts valid tracks as described below.

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

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

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

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

7. If successCallback is null, abort these steps.

8. For each media type T in requestedMediaTypes,

   1. Let candidateSet be all possible tracks of media type T that the browser could return.

   2. If the value of the T entry of constraints is "true", jump to the step labeled final below. Otherwise, continue.

   3. For each constraint key-value pair in the "mandatory" dictionary,

      1. If the constraint is not supported by the browser, jump to the step labeled Constraint Failure below.

      2. Remove from the candidateSet any track that cannot satisfy the value given for the constraint.

      3. If the candidateSet no longer contains at least one track, jump to the step labeled Constraint Failure below. Otherwise, continue with the next mandatory constraint.

   4. Let the secondPassSet be the current contents of the candidateSet.

   5. For each constraint key-value pair in the "optional" sequence of the constraints that are for the current media type, in order,

      1. If the constraint is not supported by the browser, skip it and continue with the next constraint.

      2. Remove from the secondPassSet any tracks that cannot satisfy the value given for the constraint.

      3. If the secondPassSet is now empty, let the secondPassSet be the current contents of the candidateSet. Otherwise, let the candidateSet be the current contents of the secondPassSet.

   6. Final: Add the tracks in the candidateSet to the finalSet.

9. Return, and run the remaining steps asynchronously.

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

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

    Issue 3

    Define the event that should be raised when the user agent changes its choice of track.

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

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

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

13. Queue a task to invoke successCallback with stream as its argument.

14. Abort these steps.

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

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

17. Error Task: Queue a task to invoke errorCallback with error as its argument.

18. The task source for these tasks is the user interaction task source.

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

Return type: void

10.2.1 Dictionary MediaStreamConstraints Members

audio of type (boolean or Constraints), 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.

peerIdentity of type DOMString

If the peerIdentity attribute is provided, the resulting MediaStream will be isolated from the application.

video of type (boolean or Constraints), 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.3.1 Callback NavigatorUserMediaSuccessCallback Parameters

stream of type MediaStream

Issue 4

Add explanation of handleEvent

10.4.1 Callback NavigatorUserMediaErrorCallback Parameters

error of type MediaError

Issue 5

Add explanation of handleEvent

11.1.1 Attributes

onoverconstrained of type EventHandler,

This event handler, of type overconstrained, must be supported by all objects implementing the Constrainable interface.

The UA must raise a MediaErrorEvent named "overconstrained" if changing circumstances at runtime result in it no longer being able to satisfy the currently valid mandatory ConstraintSet. This MediaErrorEvent must contain a MediaError whose name is "overconstrainedError", and whose constraintName attribute is set to one of the mandatory constraints that can no longer be satisfied. The message attribute of the MediaError 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 UA 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 refer to each immediate attribute of a ConstraintSet (as defined by HasOwnProperty) as a 'constraint' since it is intended to constrain the corresponding Capability of the Constrainable 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 Capabilities aspectRatio, height and width, the values assigned to any two of the Capabilities 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 Capabilities C1 and C2 both to 'high', while on another less limited device, this may be possible.
• A set of values for the Capabilities of an object O satisfy ConstraintSet CS if each value a) is in the range of the corresponding effective Capability of O, and b) is in the range or list of values specified by the corresponding constraint in CS, if there is one, and c) there is no constraint in CS that does not correspond to a Capability of O. (Note that although this definition ignores the difference between mandatory and optional ConstraintSets, the algorithm below distinguishes between them.)
• A set of ConstraintSets CS1...CSn (n ≥ 1) can be satisfied by an object O if it is possible to choose a sequence of values for the Capabilities of O that satisfy CS1...CSn simultaneously.
• To apply a set of ConstraintSet 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.

When applyConstraints is called, the UA must queue a task to run the following steps:

1. let newContraints be the argument to this function. Each constraint must specify one or more values (or a range of values) for its property. A property may appear more than once in the list of optional ConstraintSets.
2. Let object be the Constrainable object on which this method was called. Let copy be an unconstrained copy of object (i.e., copy should behave as if it were object with all ConstraintSets removed.)
3. If the mandatory ConstraintSet in desiredConstraints is non-null and cannot be satisfied by copy, call the errorCallback, passing it a new MediaError with name ConstraintNotSatisfied and constraintName set to any of the mandatory constraints that could not be satisfied, and return. existingConstraints remain in effect in this case.
4. Let successfullConstraints be a list of ConstraintSets, initially containing only the mandatory ConstraintSet. Iterate over the optional ConstraintSets in newConstraints in the order in which they were specified. For each ConstraintSet,if it and successfullConstraints together can be satisfied by copy, append it to the rear of successfullConstraints. Otherwise, ignore it.
5. In a single operation, remove existingConstraints from object, apply successfullConstraints, and fire the successCallback. From this point on until applyConstraints() is called successfully again, getConstraints() must return the newConstraints that were passed as an argument to this call.

The UA may choose new settings for the Capabilities of the object at any time. When it does so it must attempt to satisfy first the mandatory ConstraintSet and then the optional ConstraintSets in the order in which they were specified, as described in the algorithm above.

Parameter	Type	Nullable	Optional	Description
constraints	Constraints	✘	✘	A new constraint structure to apply to this object.
successCallback	VoidFunction	✘	✘	Called if the mandatory ConstraintSet can be satisfied.
errorCallback	ConstraintErrorCallback	✘	✘	Called if the mandatory ConstraintSet cannot be satisfied.

Return type: void

getCapabilities

The getCapabilities() method returns the dictionary of the capabilities 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 capability that is defined to be the range 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 last 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 properties of the object, whether they are platform defaults or have been set by applyConstraints(). The values returned for the properties of the object MUST lie within the currently satisfied set of constraints applied to this object. Note that the actual setting of a property must be a single value.

No parameters.

Return type: Settings

11.1.3 applyConstraints Failure Callback

callback ConstraintErrorCallback = void (MediaError error);

11.2.1 PropertyValueSet

typedef PropertyValueSet DOMString[];

11.2.2 PropertyValueDoubleRange

dictionary PropertyValueDoubleRange {
    double max;
    double min;
};

11.2.3 PropertyValueLongRange

dictionary PropertyValueLongRange {
    long max;
    long min;
};

11.5.1 Dictionary Constraints Members

mandatory of type ConstraintSet

The set of constraints that the UA must satisfy or else call the errorCallback.

optional of type sequence<ConstraintSet>

The list of ConstraintSets that the UA should try to satisfy but may ignore if they cannot be satisfied. The order of these ConstraintSets is significant. In particular, when they are passed as an argument to applyConstraints, the UA 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 UA 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 UA will attempt to satisfy C3 even though C2 cannot be satisfied. Note that a given property name may occur multiple times in these sets.

11.5.2 ConstraintSet

typedef (DOMString or long or double or boolean) ConstraintValue;

typedef (ConstraintValue or PropertyValueSet or PropertyValueLongRange or PropertyValueDoubleRange) ConstraintValues;

typedef object ConstraintSet;

In ECMAScript, ConstraintSet objects are represented using regular native objects with optional properties whose names represent constraint name. The conversion from an ECMAScript value, representing a ConstraintSet, to an IDL ConstraintSet must not fail if a property name in the ECMAScript value does not match any of the Capabilities of the Constrainable object.

In ECMAScript, all the properties of the ConstraintSet object are optional; the developer may specify any of these properties when creating the object. Note, however, that unknown property names will result in a ConstraintSet that can not be satisfied, as described in applyConstraints() above.