Media Capture and Streams

4.2.1 Attributes

ended of type boolean,

The MediaStream.ended attribute MUST return true if the MediaStream has finished, and false otherwise.

When a MediaStream object is created, its ended attribute MUST be set to false, unless it is being created using the MediaStream() constructor whose arguments are lists of MediaStreamTrack objects that are all ended, in which case the MediaStream object MUST be created with its ended attribute set to true.

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.

onaddtrack of type EventHandler,

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

onended of type EventHandler,

This event handler, of type ended, 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.2 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. Create a new MediaStreamTrack object and let it inherit track’s underlying source, kind and label attributes. Add the new MediaStreamTrack to stream’s track set.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘

Return type: void

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 not in stream’s track set, abort these steps.

4. Remove track from stream’s track set.

Parameter	Type	Nullable	Optional	Description
track	MediaStreamTrack	✘	✘

Return type: void

4.3.1 Attributes

enabled of type boolean,

The MediaStreamTrack.enabled attribute, on getting, MUST return the last value to which it was set. On setting, it MUST be set to the new value, and then, if the MediaStreamTrack object is still associated with a track, MUST enable the track if the new value is true, and disable it otherwise.

Note

Thus, after a MediaStreamTrack is disassociated from its track, its enabled attribute still changes value when set; it just doesn’t do anything with that new value.

id of type DOMString, readonly

Unless a MediaStreamTrack object is created as a part a of special purpose algorithm that specifies how the track id must be initialized, the user agent MUST generate a globally unique identifier string and initialize the object’s id attribute to that string.

An example of an algorithm that specifies how the track id must be initialized is the algorithm to represent an incoming network component with a MediaStreamTrack object. [WEBRTC10]

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

kind of type DOMString, readonly

The MediaStreamTrack.kind attribute MUST return the string "audio" if the object represents an audio track or "video" if object represents a video track.

label of type DOMString, readonly

User agents MAY label audio and video sources (e.g., "Internal microphone" or "External USB Webcam"). The MediaStreamTrack.label attribute MUST return the label of the object’s corresponding track, if any. If the corresponding track has or had no label, the attribute MUST instead return the empty string.

Note

Thus the kind and label attributes do not change value, even if the MediaStreamTrack object is disassociated from its corresponding track.

onended of type EventHandler,

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

onmute of type EventHandler,

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

onoverconstrained of type EventHandler,

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

onstarted of type EventHandler,

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

onunmute of type EventHandler,

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

readyState of type MediaStreamTrackState, readonly

The readyState attribute represents the state of the track. It MUST return the value to which the user agent last set it.

When a MediaStreamTrack object is created via getUserMedia(), its readyState is either live or muted, depending on the state of the track's underlying media source. For example, a track in a MediaStream created with getUserMedia() MUST initially have its readyState attribute set to live.

sourceId of type DOMString, readonly

The application-unique identifier for this source. The same identifier must be valid between sessions of this application, but must also be different for other applications. Some sort of GUID is recommended for the identifier.

sourceType of type SourceTypeEnum, readonly

Returns the type information associated with the currently attached source (if any).

4.3.2 Methods

appendConstraint

Appends (at the end of the list) the provided constraint name and value. This method does not consider whether a same-named constraint already exists in the optional constraints list.

This method applies exclusively to optional constraints; it does not modify mandatory constraints.

This method is a convenience API for programmatically building constraint structures.

Parameter	Type	Nullable	Optional	Description
constraintName	DOMString	✘	✘	The name of the constraint to append to the list of optional constraints.
constraintValue	any	✘	✘	Either a primitive value (float/DOMString/etc), or a MinMaxConstraint dictionary.

Return type: void

applyConstraints

This API will replace all existing constraints with the provided constraints (if existing constraints exist). Otherwise, it will apply the newly provided constraints to the track.

Parameter	Type	Nullable	Optional	Description
constraints	MediaTrackConstraints	✘	✘	A new constraint structure to apply to this track.

Return type: void

constraints

Returns the complete constraints object associated with the track. 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 null is returned.

No parameters.

Return type: MediaTrackConstraints, nullable

getConstraint

Retrieves a specific named constraint value from the track. The named constraints are the same names used for the capabilities API, and also are the same names used for the source's state attributes.

Returns one of the following types:

null

If no constraint matching the provided constraintName exists in the respective optional or mandatory set on this track.

sequence<MediaTrackConstraint>

If the mandatory flag is false and there is at least one optional matching constraint name defined on this track.

Each MediaTrackConstraint result in the list will contain a key which matches the requested constraintName parameter, and whose value will either be a primitive value, or a MinMaxConstraint object.

The returned list will be ordered from most important-to-satisfy at index 0, to the least-important-to-satisfy optional constraint.

Note

Example: Given a track with an internal constraint structure: { mandatory: { width: { min: 640 }, height: { min: 480 } }, optional: [ { width: 650 }, { width: { min: 650 }}, { frameRate: 60 }, { width: { max: 800 }}, { fillLightMode: "off" }, { facingMode: "user" } ] } and a request for getConstraint("width"), the following list would be returned: [ { width: 650 }, { width: { min: 650 }} { width: { max: 800 }} ]

MinMaxConstraint

If the mandatory flag is true, and the requested constraint is defined in the mandatory MediaTrackConstraintSet associated with this track, and the value of the constraint is a min/max range object.

primitive_value

If the mandatory flag is true, and the requested constraint is defined in the mandatory MediaTrackConstraintSet associated with this track, and the value of the constraint is a primitive value (DOMString, unsigned long, float, etc.).

Parameter	Type	Nullable	Optional	Description
constraintName	DOMString	✘	✘	The name of the setting for which the current value of that setting should be returned
mandatory	boolean = false	✘	✔	true to indicate that the constraint should be looked up in the mandatory set of constraints, otherwise, the constraintName should be retrieved from the optional list of constraints.

Return type: any

prependConstraint

Prepends (inserts before the start of the list) the provided constraint name and value. This method does not consider whether a same-named constraint already exists in the optional constraints list.

This method applies exclusively to optional constraints; it does not modify mandatory constraints.

This method is a convenience API for programmatically building constraint structures.

Parameter	Type	Nullable	Optional	Description
constraintName	DOMString	✘	✘	The name of the constraint to prepend to the list of optional constraints.
constraintValue	any	✘	✘	Either a primitive value (float/DOMString/etc), or a MinMaxConstraint dictionary.

Return type: void

setConstraint

This method updates the value of a same-named existing constraint (if found) in either the mandatory or optional list, and otherwise sets the new constraint.

This method searches the list of optional constraints from index 0 (highest priority) to the end of the list (lowest priority) looking for matching constraints. Therefore, for multiple same-named optional constraints, this method will only update the value of the highest-priority matching constraint.

If the mandatory flag is false and the constraint is not found in the list of optional constraints, then a new optional constraint is created and appended to the end of the list (thus having lowest priority).

Note

Note: This behavior allows applications to iteratively call setConstraint and have their constraints added in the order specified in the source.

Parameter	Type	Nullable	Optional	Description
constraintName	DOMString	✘	✘	The name of the constraint to set.
constraintValue	any	✘	✘	Either a primitive value (float/DOMString/etc), or a MinMaxConstraint dictionary.
mandatory	boolean = false	✘	✔	A flag indicating whether this constraint should be applied to the optional or mandatory constraints.

Return type: void

stop

When a MediaStreamTrack object’s stop() method is invoked, if no source is attached (e.g., sourceType is "none"), then this call returns immediately (e.g., is a no-op). Otherwise, the user agent MUST queue a task that runs the following steps:

1. Let track be the current MediaStreamTrack object.

2. End track. The track starts outputting only silence and/or blackness, as appropriate.

3. Permanently stop the generation of data for track's source. If the data is being generated from a live source (e.g., a microphone or camera), then the user agent SHOULD remove any active "on-air" indicator for that source. If the data is being generated from a prerecorded source (e.g. a video file), any remaining content in the file is ignored.

The task source for the tasks queued for the stop() method is the DOM manipulation task source.

No parameters.

Return type: void

4.3.3 Track Source Types

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

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

[Constructor(optional MediaTrackConstraints videoConstraints)]
interface VideoStreamTrack : MediaStreamTrack {
    static sequence<DOMString> getSourceIds ();
    void                       takePhoto ();
                attribute EventHandler onphoto;
                attribute EventHandler onphotoerror;
};

4.4.2 Photo-related Event Definitions

[Constructor(DOMString type, optional BlobEventInit blobInitDict)]
interface BlobEvent : Event {
    readonly    attribute Blob data;
};

dictionary BlobEventInit : EventInit {
    Blob data;
};

4.4.3 AudioStreamTrack

[Constructor(optional MediaTrackConstraints audioConstraints)]
interface AudioStreamTrack : MediaStreamTrack {
    static sequence<DOMString> getSourceIds ();
};

8.1.1 Methods

getUserMedia

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

Issue 4

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 (if any) 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, if any, or null otherwise.

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

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

6. If successCallback is null, abort these steps.

7. 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, queue a task to invoke errorCallback with a new NavigatorUserMediaError object whose name attribute has the value CONSTRAINT_NOT_SATISFIED and whose constraintName atribute is set to the name of the constraint that caused the error and then jump to the step labeled 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, queue a task to invoke errorCallback with a new NavigatorUserMediaError object whose name attribute has the value CONSTRAINT_NOT_SATISFIED and whose constraintName atribute is set to the name of the constraint that caused the error and then jump to the step labeled 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.

• Return, and run the remaining steps asynchronously.

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

• 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. Unless and until a new set of constraints is provided, the user agent MAY change its choice of track at any point, provided that 1) the new choice does not violate given user permissions, and 2) it notifies the application code by raising an event. It may wish to do this, for example, if the user interface or network congestion changes. Note that no such change will have an effect on the presence or absence of each type of track, merely the contents.

  Issue 5

  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 failure below. If the user never responds, this algorithm stalls on this step.

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

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

• Abort these steps.

• Failure: If errorCallback is null, abort these steps.

• Let error be a new NavigatorUserMediaError object whose name attribute has the value PERMISSION_DENIED.

• Queue a task to invoke errorCallback with error as its argument.

• 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

8.2.1 Dictionary MediaStreamConstraints Members

audio of type booleanMediaTrackConstraints, defaulting to false

Issue 7

Provide definition of audio constraints here.

video of type booleanMediaTrackConstraints, defaulting to false

Issue 6

Provide definition of video constraints here.

8.2.2 Dictionary MediaTrackConstraints Members

mandatory of type MediaTrackConstraintSet, nullable, defaulting to null

Issue 8

Provide definition of mandatory constraints here.

optional of type array of MediaTrackConstraint, nullable, defaulting to null

Issue 9

Provide definition of optional constraints here.

8.3.1 Callback NavigatorUserMediaSuccessCallback Parameters

stream of type MediaStream

Issue 10

Add explanation of handleEvent

8.4.1 Attributes

constraintName of type DOMString, readonly , nullable

The name of the constraint that caused the error. Only used for some types of errors. For NavigatorUserMediaError with a name of CONSTRAINT_NOT_SATISFIED , the constraintName attribute in the NavigatorUserMediaError object MUST be set to the name of the constraint that caused the error.

message of type DOMString, readonly , nullable

A human readable description of the error. This string may vary between different user agents.

name of type DOMString, readonly

A string representing the type of error. This string must be one of those defined by the NavigatorUserMediaErrorName enum for the error object to be valid.

8.4.2 Callback NavigatorUserMediaErrorCallback Parameters

error of type NavigatorUserMediaError

Issue 11

Add explanation of handleEvent

10.1.1 Dictionary MinMaxConstraint Members

max of type any

The related constraint's maximum allowed value.

min of type any

The related constraint's minimum allowed value.