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 stream is finished, throw an INVALID_STATE_ERR exception.

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

4. 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 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 run the following steps:

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

2. If stream is finished, throw an INVALID_STATE_ERR exception.

3. If track is in stream's track set, remove it.

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 examlpe 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 independent of sources. However, if the sourceType is "none", the readonly attribute is true, or the remote attribute is true, the track's constraints will not be applied to the source.

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 should perform the same actions to re-evaluate the constraints of each track affected by that source change.

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;
    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 either of the "noaccess" or "peerIdentity" constraints is applied to a MediaStreamTrack, the track shall be isolated so that its content is not accessible to the content JS. An isolated media stream may be used for two purposes:

• Displayed in an appropriate tag (e.g., a video or audio element). The video element MUST have a unique origin so that it is inaccessible to the content JS. This is the same security mechanism as is used with an ordinary audio or video element which has a src= property from a separate origin.

• Used as the argument to addStream() for a PeerConnection, subject to the restrictions detailed in the WebRTC document.

When the noaccess=true constraint applies to a track, that track may be added to any PeerConnection.

When the peerIdentity=foo constraint applies to a track, then that track may be added only to PeerConnections with compatible peer identities as described in the WebRTC document.

Both the noaccess and peerIdentity constraints must be mandatory. Any use of them in the optional block must trigger an error.

4.4.1 Constructors

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

 

4.5.1 VideoStreamTrack interface

Video tracks may be instantiated with optional media track constraints. These constraints can be later modified on the track as needed by the application, or created after-the-fact if the initial constraints are unknown to the application.

new VideoStreamTrack();

new VideoStreamTrack( { optional: [ { sourceId: "20983-20o198-109283-098-09812" }, { width: { min: 800, max: 1200 }}, { height: { min: 600 }}] });

[ Constructor (optional Constraints videoConstraints)]
interface VideoStreamTrack : MediaStreamTrack {
};

4.5.2 AudioStreamTrack

new AudioStreamTrack();

new AudioStreamTrack( { optional: [ { sourceId: "64815-wi3c89-1839dk-x82-392aa" }, { gain: 0.5 }] });

[ Constructor (optional Constraints audioConstraints)]
interface AudioStreamTrack : MediaStreamTrack {
};

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

The syntax for getUserMedia() is still under discussion. Some questions are: whether it creates media streams or just initializes ones already created; whether it creates streams synchronously (immediate return of MediaStream with callback later when user grants permission) or asynchronously (MediaStream available only upon callback).

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.

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

capabilities() of type Capabilities, readonly

Contains the dictionary of the capabilities that the object supports. Note that it is possible that the underlying hardware may not exactly map to the range defined in the specification. In this case, an implementation should make a reasonable attempt to translate and scale the hardware's setting onto the mapping provided by the relevant specification.

Note

An example of the user agent providing an alternative mapping: if a source supports a hypothetical fluxCapacitance capability that is defined to be the range from -10 (min) to 10 (max), but the source's (hardware setting) for fluxCapacitance only supports values of "off" "medium" and "full", then the user agent should map the range value of -10 to "off", 10 should map to "full", and 0 should map to "medium". Constraints imposing a strict value of 3 will cause the user agent to attempt to set the value of "medium" on the hardware, and return a fluxCapacitance of 0, the closest supported setting. No error event is raised in this scenario.

Issue 6

What about the case where the object uses the same units as the specification, but supports only a sub-range of the specified values? What about an object whose fluxCapacitance range is only -5 to 5? Should it map those to -10 to 10, or leave them as they are?

constraints of type Constraints, readonly

Contains all the Constraints that were applied to the object in the last succesfull call of applyConstraints(). The list MUST contain only the constraints that were successfully applied, and MUST maintain the order that they were specified in.

If no mandatory constraints have been defined, the mandatory field will not be present (it will be undefined). If no optional constraints have been defined, the optional field will not be present (it will be undefined). If neither optional nor mandatory constraints have been created, the value will be null.

The UA MUST raise a MediaErrorEvent named "overconstrained" if changing circumstances at runtime result in the currently valid mandatory constraints no longer being satisfied. 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 satisifed. 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 satisifies the constraints. The UA MAY take other actions as a result of the overconstrained situation.

onoverconstrained of type EventHandler,

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

settings of type Settings, readonly

Contains the current settings of all the 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.

11.1.2 Methods

applyConstraints

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

• A sequence of values for the properties of an object O satisfy constraint set C if each value a) is in the set of supported values specified by the corresponding Capability of O, and b) is in the set specified by any constraints in C that apply to that property, and c) there is no constraint in C that does not correspond to a Capability in O. (Note that although this definition ignores the difference between mandatory and optional constraints, the algorithm below distinguishes between them.)
• A set of constraints C can be satisifed by an object O if it is possible to choose a sequence of values for the properties of O that satisfy C.
• To apply a set of constraints C to object O is to choose such a sequence of values that satisfy C 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 desiredContraints 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 constraints.
2. Let newConstraints be an initially empty set of constraints
3. 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 constraints removed.)
4. If the mandatory constraints in desiredConstraints is cannot be satisifed by copy, call the errorCallback, passing it a new MediaError with name ConstraintNotSatisfied and constraintName set to the mandatory constraints that could not be satisfied, and return. (Note that there may be more than one way of selecting the set of constraints that were not satisfied.) existingConstraints remain in effect on object in this case.
5. Otherwise add the mandatory constraints to newConstraints
6. Iterate over the optional constraints in desiredConstraints in the order in which they were specified. For each constraint,if it and newConstraints together can be satisfied by copy, add it to newConstraints. Otherwise, ignore it.
7. In a single operation, remove all existing constraints from object, apply newConstraints, set the value of the constraints attribute to newConstraints, and fire the successCallback passing it newConstraints as its argument. Note: the UA MAY modify the values of one or more properties of object at any time, as long as the resulting set of values satisfy the current set of constraints.

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

Return type: void

11.1.3 applyConstraints Failure Callback

callback ConstraintErrorCallback = void (MediaError error);

11.1.4 Capabilities, Constraints, and Settings

dictionary PropertyValueRange {
    any max;
    any min;
};

Settings is a dictionary containing one or more key-value pairs. It MUST contain each key returned in capabilities(). There MUST be a single value for each key and the value MUST a member of the set defined for that property by capabilities(). Thus the Settings dictionary contains the actual values that the UA has chosen for the object's Capabilities.

dictionary Constraints {
    ConstraintSet? mandatory;
    Constraint[]   optional;
};