This document defines a set of JavaScript APIs that allow local media, including audio and video, to be requested from a platform.
This document is not complete. It is subject to major changes and, while early experimentations are encouraged, it is therefore not intended for implementation. The API is based on preliminary work done in the WHATWG. The Media Capture Task Force expects this specification to evolve significantly based on:
Access to multimedia streams (video, audio, or both) from local devices (video cameras, microphones, Web cams) can have a number of uses, such as real-time communication, recording, and surveillance.
This document defines the APIs used to get access to local devices that can generate multimedia stream data. This document also defines the stream API by which JavaScript is able to manipulate the stream data or otherwise process it.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.
The
EventHandler
interface represents a callback used for event
handlers as defined in [[!HTML5]].
The concepts queue a task and fires a simple event are defined in [[!HTML5]].
The terms event handlers and event handler event types are defined in [[!HTML5]].
The MediaStream
interface is used to represent
streams of media data, typically (but not necessarily) of audio and/or
video content, e.g. from a local camera. The data from a
MediaStream
object does not necessarily have a
canonical binary form; for example, it could just be "the video currently
coming from the user’s video camera". This allows user agents to
manipulate media streams in whatever fashion is most suitable on the
user’s platform.
Each MediaStream
object can contain zero or more
tracks, in particular audio and video tracks. All tracks in a MediaStream
are intended to be synchronized when rendered. Different MediaStreams do
not need to be synchronized.
Each track in a MediaStream object has a corresponding
MediaStreamTrack
object.
A MediaStreamTrack
represents content comprising
one or more channels, where the channels have a defined well known
relationship to each other (such as a stereo or 5.1 audio signal).
A channel is the smallest unit considered in this API specification.
A MediaStream
object has an input and an output.
The input depends on how the object was created: a
LocalMediaStream
object generated by a getUserMedia()
call (which is
described later in this document), for instance, might take its input
from the user’s local camera. The output of the object controls how the
object is used, e.g., what is saved if the object is written to a file or
what is displayed if the object is used in a video
element.
Each track in a MediaStream
object can be
disabled, meaning that it is muted in the object’s output. All tracks are
initially enabled.
A MediaStream
can be finished, indicating
that its inputs have forever stopped providing data.
The output of a MediaStream
object MUST correspond
to the tracks in its input. Muted audio tracks MUST be replaced with
silence. Muted video tracks MUST be replaced with blackness.
A new MediaStream
object can be created from
existing MediaStreamTrack
objects using the
MediaStream()
constructor.
The constructor takes two lists of MediaStreamTrack
objects as arguments: one for audio tracks and one for video tracks. The
lists can either be the track lists of another stream, subsets of such
lists, or compositions of MediaStreamTrack
objects
from different MediaStream
objects.
The ability to duplicate a MediaStream
, i.e.
create a new MediaStream
object from the track lists
of an existing stream, allows for greater control since separate
MediaStream
instances can be manipulated and
consumed individually.
The LocalMediaStream
interface is used when the
user agent is generating the stream’s data (e.g. from a camera or
streaming it from a local video file).
When a LocalMediaStream
object is being generated
from a local file (as opposed to a live audio/video source), the user
agent SHOULD stream the data from the file in real time, not all at once.
The MediaStream
object is also used in contexts outside
getUserMedia
, such as [[!WEBRTC10]]. In both cases, ensuring
a realtime stream reduces the ease with which pages can distinguish live
video from pre-recorded video, which can help protect the user’s
privacy.
The MediaStream()
constructor takes zero or one argument. If the argument,
trackContainers, is supplied, it specifies a list of
MediaStream
, MediaStreamTrackList
and
MediaStreamTrack
objects. The list objects specifies
existing tracks whose sources will be used to constuct the tracks in the
new MediaStream
object. A
MediaStreamTrack
object specifies a track directly, while
MediaStream
and MediaStreamTrackList
objects specifiy all tracks contained within these objects. When
the constructor is invoked, the UA must run the following steps:
Let trackContainers be the constructor’s argument, if any, or null otherwise.
Let stream be a newly constructed
MediaStream
object.
Set stream’s label attribute to a newly generated value.
If trackContainers is not null, then run the following sub steps for every element, trackContainer, in trackContainers:
If trackContainer is null, then abort these steps and continue with the next element.
If trackContainer is of type
MediaStreamTrack
, then run the following sub
steps:
Add track: Let track be the
MediaStreamTrack
about to be processed.
If track’s kind attribute is not
"audio
" or "video
", then throw a
SyntaxError
exception.
If track has ended or if there is already
a MediaStreamTrack
contained within
stream that has the same underlying source as
track, then abort these steps.
Create a new MediaStreamTrack
object
and let it inherit track’s underlying source,
kind
and
label
attributes. Append the new MediaStreamTrack
to the corresponding track list
(audioTracks
or
videoTracks
)
in stream according to kind.
If trackContainer is of type
MediaStreamTrackList
, then run the sub steps
labeled Add track (above) for every
MediaStreamTrack
in trackContainer.
If trackContainer is of type
MediaStream
, then run the sub steps labeled
Add track (above) for every
MediaStreamTrack
in trackContainer’s
two track lists
(audioTracks
and
videoTracks
).
Return stream.
A MediaStream
can have multiple audio and video
sources (e.g. because the user has multiple microphones, or because the
real source of the stream is a media resource with many media tracks).
The stream represented by a MediaStream
thus has zero
or more tracks.
The tracks of a MediaStream
are stored in two
track lists represented by MediaStreamTrackList
objects: one for audio tracks and one for video tracks. The two track
lists MUST contain the MediaStreamTrack
objects that
correspond to the tracks of the stream. The relative order of all tracks
in a user agent MUST be stable. Tracks that come from a media resource
whose format defines an order MUST be in the order defined by the format;
tracks that come from a media resource whose format does not define an
order MUST be in the relative order in which the tracks are declared in
that media resource. Within these constraints, the order is user agent
defined.
An object that reads data from the output of a
MediaStream
is referred to as a
MediaStream
consumer. The list of
MediaStream
consumers currently includes the media
elements and the PeerConnection
API specified in
[[!WEBRTC10]].
MediaStream
consumers must be able to
handle tracks being added and removed. This behavior is specified per
consumer.
A MediaStream
object is said to be
finished when all tracks belonging to the stream have
ended. When this happens for any reason other than the
stop()
method being
invoked, the user agent MUST queue a task that runs the following
steps:
If the object’s ended
attribute has the value
true already, then abort these steps. (The stop()
method was probably called
just before the stream stopped for other reasons, e.g. the user
clicked an in-page stop button and then the user agent provided stop
button.)
Set the object’s ended
attribute to true.
Fire a simple event named ended
at the object.
If the end of the stream was reached due to a user request, the task source for this task is the user interaction task source. Otherwise the task source for this task is the networking task source.
The union type we want to express here is not supported
by ReSpec at the moment. Until it is supported, let
TracksUnionType
be defined as (MediaStream? or
MediaStreamTrackList or MediaStreamTrack)[]
.
When a LocalMediaStream
object is created, the
user agent MUST generate a globally unique identifier string, and
MUST initialize the object’s label
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.
When a MediaStream
is created from another
using the MediaStream()
constructor, the label
attribute is initialized to
a newly generated value.
The label
attribute MUST return the value to which it was initialized when the
object was created.
Returns a MediaStreamTrackList
object
representing the audio tracks that can be enabled and disabled.
The audioTracks
attribute MUST return an array host
object for objects of type
MediaStreamTrack
that is fixed length
and read only. The same object MUST be returned each time
the attribute is accessed.
Returns a MediaStreamTrackList
object
representing the video tracks that can be enabled and disabled.
The videoTracks
attribute MUST return an array host
object for objects of type
MediaStreamTrack
that is fixed length
and read only. The same object MUST be returned each time
the attribute is accessed.
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.
ended
, MUST be supported by all
objects implementing the MediaStream
interface.Before the web application can access the user's media input devices
it must let getUserMedia()
create a
LocalMediaStream
. Once the application is done
using, e.g., a webcam and a microphone, it may revoke its own access by
calling stop()
on the
LocalMediaStream
.
A web application may, once it has access to a
LocalMediaStream
, use the MediaStream()
constructor to construct
additional MediaStream
objects. Since a derived
MediaStream
object is created from the tracks of an
existing stream, it cannot use any media input devices that have not been
approved by the user.
When a LocalMediaStream
object’s stop()
method is invoked,
the user agent MUST queue a task that runs the following steps on
every track:
Let track be the current
MediaStreamTrack
object.
End track. The track starts outputting only silence and/or blackness, as appropriate.
Dereference track’s underlying media source.
If the reference count of track’s underlying media source is greater than zero, then abort these steps.
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.
A MediaStreamTrack
object represents a media
source in the user agent. Several MediaStreamTrack
objects can represent the same media source, e.g., when the user chooses
the same camera in the UI shown by two consecutive calls to
getUserMedia()
.
A MediaStreamTrack
object can reference its media
source in two ways, either with a strong or a weak reference, depending
on how the track was created. For example, a track in a
MediaStream
, derived from a
LocalMediaStream
with the MediaStream()
constructor, has a weak
reference to a local media source, while a track in a
LocalMediaStream
has a strong reference. This means
that a track in a MediaStream
, derived from a
LocalMediaStream
, will end if there is no
non-ended track in a LocalMediaStream
which
references the same local media source.
The concept with strong and weak references to media
sources allows the web application to derive new
MediaStream
objects from
LocalMediaStream
objects (created via getUserMedia()
) and still be
able to revoke all given permissions with LocalMediaStream.stop()
.
A MediaStreamTrack
object is said to end
when the user agent learns that no more data will ever be forthcoming for
this track.
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, or because
the reference count of the track’s underlying media source has reached
zero, it is said to be ended. When track instance
track ends for any reason other than the stop()
method being invoked on the
LocalMediaStream
object that represents
track, the user agent MUST queue a task that runs the
following steps:
If the track’s readyState
attribute
has the value ENDED
(2) already, then
abort these steps.
Set track’s readyState
attribute to
ENDED
(2).
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.
The MediaStreamTrack.kind
attribute MUST return the string "audio
" if the object’s
corresponding track is or was an audio track, "video
" if
the corresponding track is or was a video track, and a user agent
defined string otherwise.
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.
Thus the kind
and label
attributes do not
change value, even if the MediaStreamTrack
object
is disassociated from its corresponding track.
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.
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.
The track is active (the track’s underlying media source is making a best-effort attempt to provide data in real time).
The output of a track in the LIVE
state can be switched
on and off with the enabled
attribute.
The track is muted (the track’s underlying media source is temporarily unable to provide data).
A MediaStreamTrack
in a
LocalMediaStream
may be muted if the user
temporarily revokes the web application’s permission to use a media
input device.
The track has ended (the track’s underlying media source is no longer providing data, and will never provide more data for this track).
For example, a video track in a
LocalMediaStream
finishes if the user unplugs the
USB web camera that acts as the track’s media source.
The readyState
attribute represents the state of the track. It MUST return the value
to which the user agent last set it (as defined below). It can have
the following values: LIVE, MUTED or
ENDED.
When a MediaStreamTrack
object is created, its
readyState
is either
LIVE
(0) or
MUTED
(1),
depending on the state of the track’s underlying media source. For
example, a track in a LocalMediaStream
, created
with getUserMedia()
, MUST
initially have its readyState
attribute
set to LIVE
(1).
muted
, MUST be supported by
all objects implementing the MediaStreamTrack
interface.unmuted
, MUST be supported
by all objects implementing the MediaStreamTrack
interface.ended
, MUST be supported by
all objects implementing the MediaStreamTrack
interface.Mints a Blob URL to refer to the given
MediaStream
.
When the createObjectURL()
method
is called with a MediaStream
argument, the user
agent MUST return a unique Blob URL for the
given MediaStream
. [[!FILE-API]]
For audio and video streams, the data exposed on that stream MUST
be in a format supported by the user agent for use in
audio
and video
elements.
A Blob URL is the
same as what the File API specification calls a Blob URI, except that
anything in the definition of that feature that refers to
File
and Blob
objects is hereby extended to
also apply to MediaStream
and
LocalMediaStream
objects.
A MediaStreamTrackList
object’s corresponding
MediaStream
refers to the
MediaStream
object which the current
MediaStreamTrackList
object is a property of.
MediaStreamTrack
object at the
specified index.Adds the given MediaStreamTrack
to this
MediaStreamTrackList
according to the ordering
rules for tracks.
When the add()
method is
invoked, the user agent MUST run the following steps:
Let track be the
MediaStreamTrack
argument.
Let stream be the
MediaStreamTrackList
object’s corresponding
MediaStream
object.
If stream is finished, throw an
INVALID_STATE_ERR
exception.
If track is already in the
MediaStreamTrackList
object’s internal list,
then abort these steps.
Add track to the end of the
MediaStreamTrackList
object’s internal
list.
Removes the given MediaStreamTrack
from this
MediaStreamTrackList
.
When the remove()
method
is invoked, the user agent MUST run the following steps:
Let track be the
MediaStreamTrack
argument.
Let stream be the
MediaStreamTrackList
object’s corresponding
MediaStream
object.
If stream is finished, throw an
INVALID_STATE_ERR
exception.
If track is not in the
MediaStreamTrackList
object’s internal list,
then abort these steps.
Remove track from the
MediaStreamTrackList
object’s internal
list.
addtrack
, MUST be
supported by all objects implementing the
MediaStreamTrackList
interface.removetrack
, MUST
be supported by all objects implementing the
MediaStreamTrackList
interface.A MediaStream
may be assigned to media elements as defined in HTML5 [[!HTML5]]
by calling createObjectURL
to obtain a URL for the MediaStream
and then
setting the media elements src
attribute to that URL. A MediaStream
is
not preloadable or seekable and represents a simple, potentially infinite,
linear media timeline. The timeline starts at 0 and increments linearly
in real time as long as the MediaStream
is playing. The timeline does not
increment when the MediaStream
is paused.
Do we also need to support direct assignment and access of the underlying stream?
The nature of the MediaStream
places certain restrictions on the
behavior and attribute values of the associated media element and on the
operations that can be performed on it, as shown below:
media.readystate
to HAVE_ENOUGH_DATA.
Attribute Name | Attribute Type | Valid Values | Additional considerations |
---|---|---|---|
src
|
DOMString |
a local URI referencing a MediaStream | N.B. Revocation of the URI does not count as a change to this field. |
currentSrc
|
DOMString |
a local URI referencing a MediaStream | - |
preload
|
DOMString |
none |
A MediaStream cannot be preloaded. |
buffered
|
TimeRanges
|
buffered.length MUST return 1 .buffered.start(0) MUST return 0 .buffered.end(0) MUST return 0 . |
A MediaStream cannot be preloaded. Therefore, the amount buffered is always an empty TimeRange. |
currentTime
|
double |
Any positive integer. The initial value is 0 and the values increments linearly in real time whenever the stream is playing. | The value is the current stream position, in seconds. The UA MUST ignore attempts to set this attribute. |
duration
|
double |
Infinity |
A MediaStream does not have a pre-defined duration.
If the underlying MediaStream is destroyed, the UA MUST set this property to the value
of the last known |
seeking
|
boolean |
false | A MediaStream is not seekable. Therefore, this attribute
MUST always have the value
false . |
defaultPlaybackRate
|
double |
1.0 | A MediaStream is not seekable. Therefore, this attribute
MUST always have the value
1.0 and any attempt to alter it MUST fail. |
playbackRate
|
double |
1.0 | A MediaStream is not seekable. Therefore, this attribute
MUST always have the value
1.0 and any attempt to alter it MUST fail. |
played
|
TimeRanges
|
played.length MUST return 1 .played.start(0) MUST return 0 .played.end(0) MUST return the last known currentTime .
|
A MediaStream's timeline always consists of a single range, starting at 0 and extending up to the currentTime. |
seekable
|
TimeRanges
|
seekable.length MUST return 0 .seekable.start() MUST return currentTime .seekable.end() MUST return currentTime .
|
A MediaStream is not seekable. |
startOffsetTime
|
Date |
Not-a-Number (NaN) | A MediaStream does not specify a timeline offset. |
loop
|
boolean |
false | A MediaStream has no defined end and therefore cannot be looped. |
The following event fires on
MediaStream
objects:
Event name | Interface | Fired when... |
---|---|---|
ended
|
Event
|
The
MediaStream
finished as a result of all tracks in the
MediaStream
ending. |
The following event fires on
MediaStreamTrack
objects:
Event name | Interface | Fired when... |
---|---|---|
muted
|
Event
|
The
MediaStreamTrack
object's source is temporarily unable to provide
data. |
unmuted
|
Event
|
The
MediaStreamTrack
object's source is live again after having been
temporarily unable to provide data. |
ended
|
Event
|
The
MediaStreamTrack
object's source will no longer provide any data, either
because the user revoked the permissions, or because the source
device has been ejected, or because the remote peer stopped
sending data, or because the
stop()
method was invoked. |
The following event fires on
MediaStreamTrackList
objects:
Event name | Interface | Fired when... |
---|---|---|
addtrack
|
MediaStreamTrackEvent
|
A new
MediaStreamTrack
has been added to this list. |
removetrack
|
MediaStreamTrackEvent
|
A
MediaStreamTrack
has been removed from this list. |
Prompts the user for permission to use their Web cam or other video or audio input.
The constraints argument is an object of type
MediaStreamConstraints
.
The successCallback will be invoked with a suitable
LocalMediaStream
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:
Let constraints be the method's first argument.
Let successCallback be the callback indicated by the method's second argument.
Let errorCallback be the callback indicated by the method's third argument, if any, or null otherwise.
Let requestedMediaTypes be the set of media types in constraints with either a dictionary value or a value of "true".
Let finalSet be an (initially) empty set.
If successCallback is null, abort these steps.
For each media type T in requestedMediaTypes,
Let candidateSet be all possible tracks of media type T that the browser could return.
For each constraint key-value pair in the "mandatory" dictionary,
If the constraint is not supported by the browser,
queue a task to invoke errorCallback with a
new NavigatorUserMediaError object whose code attribute
has the numeric value ???
(NOT_SUPPORTED_ERR
) and jump to the step
labeled failure below. ***N.B. - also need to
find a way to return the name of the constraint that
failed***
Remove from the candidateSet any track that cannot satisfy the value given for the constraint.
If the candidateSet no longer contains at
least one track, queue a task to invoke
errorCallback with a new
NavigatorUserMediaError object whose code attribute has
the numeric value ???
(MANDATORY_UNSATISFIED_ERR
) and jump to the
step labeled failure below. (***N.B. - also need
to find a way to return the name of the constraint that
failed***). Otherwise, continue with the next mandatory
constraint.
Let the secondPassSet be the current contents of the candidateSet.
For each constraint key-value pair in the "optional" sequence of the constraints that are for the current media type, in order,
If the constraint is not supported by the browser, skip it and continue with the next constraint.
Remove from the secondPassSet any tracks that cannot satisfy the value given for the constraint.
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.
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
LocalMediaStream
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.
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
LocalMediaStream
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 code
attribute has
the numeric value 1 (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.
Provide definition of video constraints here.
Provide definition of audio constraints here.
Provide definition of mandatory constraints here.
Provide definition of optional constraints here.
A MediaTrackConstraintSet is a dictionary containing one or more key-value pairs, where each key MUST be a valid registered constraint name in the IANA-hosted RTCWeb Media Constraints registry [[!RTCWEB-CONSTRAINTS]] and its value SHOULD be as defined in the associated reference[s] given in the registry.
A MediaTrackConstraint is a dictionary containing exactly one key-value pair, where the key MUST be a valid registered constraint name in the IANA-hosted RTCWeb Media Constraints registry [[!RTCWEB-CONSTRAINTS]] and the value SHOULD be as defined in the associated reference[s] given in the registry.
Add explanation of handleEvent
PERMISSION_DENIED
is defined.Add explanation of handleEvent
The user agent is encouraged to reserve resources when it has determined that a given call to getUserMedia() will succeed. It is preferable to reserve the resource prior to invoking the success callback provided by the web page. Subsequent calls to getUserMedia() (in this page or any other) should treat the resource that was previously allocated, as well as resources held by other applications, as busy. Resources marked as busy should not be provided as sources to the current web page, unless specified by the user. Optionally, the user agent may choose to provide a stream sourced from a busy source but only to a page whose origin matches the owner of the original stream that is keeping the source busy.
This document recommends that in the permission grant dialog or device selection interace (if one is present), the user be allowed to select any available hardware as a source for the stream requested by the page (provided the resource is able to fulfill mandatory constraints, if any were specified), in addition to the ability to substitute a video or audio source with local files and other media. A file picker may be used to provide this functionality to the user.
This document also recommends that the user be shown all resources that are currently busy as a result of prior calls to getUserMedia() (in this page or any other page that is still alive) and be allowed to terminate that stream and utilize the resource for the current page instead. If possible in the current operating environment, it is also suggested that resources currently held by other applications be presented and treated in the same manner. If the user chooses this option, the track corresponding to the resource that was provided to the page whose stream was affected must be removed. Additionally, if removing a track in this manner causes the stream to contain no more tracks, the onended event must be raised on it.
A MediaStream may contain more than one video and audio track. This makes it possible to include video from two or more webcams in a single stream object, for example. However, the current API does not allow a page to express a need for multiple video streams from independent sources.
It is recommended for multiple calls to getUserMedia() from the same page be allowed as a way for pages to request multiple, discrete, video or audio streams.
A single call to getUserMedia() will always return a stream with either zero or one audio tracks, and either zero or one video tracks. If a script calls getUserMedia() multiple times before reaching a stable state, this document advises the UI designer that the permission dialogs should be merged, so that the user can give permission for the use of multiple cameras and/or media sources in one dialog interaction. The constraints on each getUserMedia call can be used to decide which stream gets which media sources.
This sample code exposes a button. When clicked, the button is disabled and the user is prompted to offer a stream. The user can cause the button to be re-enabled by providing a stream (e.g., giving the page access to the local camera) and then disabling the stream (e.g., revoking that access).
<input type="button" value="Start" onclick="start()" id="startBtn"> <script> var startBtn = document.getElementById('startBtn'); function start() { navigator.getUserMedia({audio:true, video:true}, gotStream); startBtn.disabled = true; } function gotStream(stream) { stream.onended = function () { startBtn.disabled = false; }; } </script>
This example allows people to take photos of themselves from the local video camera.
<article> <style scoped> video { transform: scaleX(-1); } p { text-align: center; } </style> <h1>Snapshot Kiosk</h1> <section id="splash"> <p id="errorMessage">Loading...</p> </section> <section id="app" hidden> <p><video id="monitor" autoplay></video> <canvas id="photo"></canvas> <p><input type=button value="📷" onclick="snapshot()"> </section> <script> navigator.getUserMedia({video:true}, gotStream, noStream); var video = document.getElementById('monitor'); var canvas = document.getElementById('photo'); function gotStream(stream) { video.src = URL.createObjectURL(stream); video.onerror = function () { stream.stop(); }; stream.onended = noStream; video.onloadedmetadata = function () { canvas.width = video.videoWidth; canvas.height = video.videoHeight; document.getElementById('splash').hidden = true; document.getElementById('app').hidden = false; }; } function noStream() { document.getElementById('errorMessage').textContent = 'No camera available.'; } function snapshot() { canvas.getContext('2d').drawImage(video, 0, 0); } </script> </article>
IANA is requested to register the following constraints as specified in [[!RTCWEB-CONSTRAINTS]]:
This section will be removed before publication.