W3C

Media Capture and Streams

W3C Editor's Draft 12 December 2012

This version:
http://dev.w3.org/2011/webrtc/editor/archives/20121212/getusermedia.html
Latest published version:
http://www.w3.org/TR/mediacapture-streams/
Latest editor's draft:
http://dev.w3.org/2011/webrtc/editor/getusermedia.html
Previous editor's draft:
http://dev.w3.org/2011/webrtc/editor/archives/20121115/getusermedia.html
Editors:
Daniel C. Burnett, Voxeo
Adam Bergkvist, Ericsson
Cullen Jennings, Cisco
Anant Narayanan, Mozilla (until November 2012)

Abstract

This document defines a set of JavaScript APIs that allow local media, including audio and video, to be requested from a platform.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

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:

This document was published by the Web Real-Time Communication Working Group and Device APIs Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All feedback is welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Web Real-Time Communication Working Group, Device APIs Working Group) made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

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.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

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.

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

4. Stream API

4.1 Introduction

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 accessible media sources (that does not require any additional permissions) using the MediaStream() constructor. The constructor argument can either be an existing MediaStream object, in which case the given stream is cloned, or an array of MediaStreamTrack objects. The latter from makes it possible to compose a stream from different source streams.

A MediaStream

The ability to duplicate a MediaStream, specifically create a new MediaStream object using an other stream as input, 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.

4.2 MediaStream

The MediaStream() constructor takes zero or one argument. If the argument is supplied, it must either be of type MediaStream or an array of MediaStreamTrack objects. When the constructor is invoked, the UA must run the following steps:

  1. Let stream be a newly constructed MediaStream object.

  2. Initialize stream’s id attribute to a newly generated value.

  3. If the constructor’s argument is present, run the sub steps that corresponds to the argument type.

  4. 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 a track set. The track set must contain the MediaStreamTrack objects that correspond to the tracks of the stream. The relative order of the tracks in the set is user agent defined and the API will never put any requirements on the order. The proper way to find a specific MediaStreamTrack object in the set is to look it up by its id.

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

Note

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:

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

  2. Set the object’s ended attribute to true.

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

typedef MediaStreamTrack[] MediaStreamTrackArray;
Throughout this specification, the identifier MediaStreamTrackArray is used to refer to the array of MediaStreamTrack type.
[Constructor (),
        Constructor (MediaStream stream),
        Constructor (MediaStreamTrackArray tracks)]
interface MediaStream : EventTarget {
    readonly attribute DOMString    id;
    sequence<MediaStreamTrack> getAudioTracks ();
    sequence<MediaStreamTrack> getVideoTracks ();
    MediaStreamTrack           getTrackById (DOMString trackId);
    void                       addTrack (MediaStreamTrack track);
    void                       removeTrack (MediaStreamTrack track);
             attribute boolean      ended;
             attribute EventHandler onended;
             attribute EventHandler onaddtrack;
             attribute EventHandler onremovetrack;
};

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

ParameterTypeNullableOptionalDescription
trackMediaStreamTrack
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.

ParameterTypeNullableOptionalDescription
trackIdDOMString
Return type: MediaStreamTrack
getVideoTracks

Returns a sequence of MediaStreamTrack objects representing the video tracks in this stream.

The getVideoTracks() method must return a sequence that represents a snapshot of all the MediaStreamTrack objects in this stream’s track set whose kind is equal to "video". The conversion from the track set to the sequence is user agent defined and the order does not have to 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.

ParameterTypeNullableOptionalDescription
trackMediaStreamTrack
Return type: void

4.3 LocalMediaStream

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.

interface LocalMediaStream : MediaStream {
    void stop ();
};

4.3.1 Methods

stop

When a LocalMediaStream object’s stop() method is invoked, the user agent must queue a task that runs the following steps on every track:

  1. Let track be the current MediaStreamTrack object.

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

  3. Dereference track’s underlying media source.

  4. If the reference count of track’s underlying media source is greater than zero, then abort these steps.

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

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.

Note

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:

  1. If the track’s readyState attribute has the value ended already, then abort these steps.

  2. Set track’s readyState attribute to ended.

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

interface MediaStreamTrack {
    readonly attribute DOMString             kind;
    readonly attribute DOMString             id;
    readonly attribute DOMString             label;
             attribute boolean               enabled;
    readonly attribute MediaStreamTrackState readyState;
             attribute EventHandler          onmute;
             attribute EventHandler          onunmute;
             attribute EventHandler          onended;
};

4.4.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.
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, its readyState is either live or muted, 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.

enum MediaStreamTrackState {
    "live",
    "muted",
    "ended"
};
Enumeration description
live

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.

muted

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.

ended

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 ends if the user unplugs the USB web camera that acts as the track’s media source.

4.5 URL

partial interface URL {
    static DOMString createObjectURL (MediaStream stream);
};

4.5.1 Methods

createObjectURL, static

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.

ParameterTypeNullableOptionalDescription
streamMediaStream
Return type: DOMString

4.6 MediaStreams as Media Elements

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.

Issue 1

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:

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

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.

4.7 Event summary

This section is non-normative.

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.
addtrack MediaStreamTrackEvent A new MediaStreamTrack has been added to this stream.
removetrack MediaStreamTrackEvent A MediaStreamTrack has been removed from this stream.

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.

5. Obtaining local multimedia content

5.2 MediaStreamConstraints

dictionary MediaStreamConstraints {
    (boolean or MediaTrackConstraints) video = false;
    (boolean or MediaTrackConstraints) audio = false;
};

5.2.1 Dictionary MediaStreamConstraints Members

audio of type booleanMediaTrackConstraints, defaulting to false
Issue 4

Provide definition of audio constraints here.

video of type booleanMediaTrackConstraints, defaulting to false
Issue 3

Provide definition of video constraints here.

dictionary MediaTrackConstraints {
    MediaTrackConstraintSet? mandatory = null;
    MediaTrackConstraint[]?  optional = null;
};

5.2.2 Dictionary MediaTrackConstraints Members

mandatory of type MediaTrackConstraintSet, nullable, defaulting to null
Issue 5

Provide definition of mandatory constraints here.

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

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.

5.5 Implementation Suggestions

This section is non-normative.

Best Practice 1: Resource reservation

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.

Best Practice 2: Handling multiple devices

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.

6. Examples

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

Example 1
<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.

Example 2
<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="&#x1F4F7;" 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>

7. IANA Registrations

7.1 Constraints Registrations

IANA is requested to register the following constraints as specified in [RTCWEB-CONSTRAINTS]:

8. Change Log

This section will be removed before publication.

November 15 2012

  1. Introduced new representation of tracks in a stream (removed MediaStreamTrackList).
  2. Updated MediaStreamTrack.readyState to use an enum type (instad of unsigned short constants).
  3. Renamed MediaStream.label to MediaStream.id (the definition needs some more work).

October 1 2012

  1. Limited the track kind values to "audio" and "video" only (could previously be user defined as well).
  2. Made MediaStream extend EventTarget.
  3. Simplified the MediaStream constructor.

June 23 2012

  1. Rename title to "Media Capture and Streams".
  2. Update document to comply with HTML5.
  3. Update image describing a MediaStream.
  4. Add known issues and various other editorial changes.

June 22 2012

  1. Update wording for constraints algorithm.

June 19 2012

  1. Added "Media Streams as Media Elements section".

June 12 2012

  1. Switch to respec v3.

June 5 2012

  1. Added non-normative section "Implementation Suggestions".
  2. Removed stray whitespace.

June 1 2012

  1. Added media constraint algorithm.

Apr 23 2012

  1. Remove MediaStreamRecorder.

Apr 20 2012

  1. Add definitions of MediaStreams and related objects.

Dec 21 2011

  1. Changed to make wanted media opt in (rather than opt out). Minor edits.

Nov 29 2011

  1. Changed examples to use MediaStreamOptions objects rather than strings. Minor edits.

Nov 15 2011

  1. Removed MediaStream stuff. Refers to webrtc 1.0 spec for that part instead.

Nov 9 2011

  1. Created first version by copying the webrtc spec and ripping out stuff. Put it on github.

A. Acknowledgements

B. References

B.1 Normative references

[FILE-API]
Arun Ranganathan; Jonas Sicking. File API. 20 October 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-FileAPI-20111020/
[HTML5]
Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[RTCWEB-CONSTRAINTS]
D. Burnett. IANA Registry for RTCWeb Media Constraints. URL: http://datatracker.ietf.org/doc/draft-burnett-rtcweb-constraints-registry/
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/
[WEBRTC10]
A Bergkvist; D Burnett; C Jennings; A Narayanan. WebRTC 1.0. 27 October 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-webrtc-20111027/