W3C

getusermedia: Getting access to local devices that can generate multimedia streams

W3C Editor's Draft 22 December 2011

This version:
http://dev.w3.org/2011/webrtc/editor/getusermedia-20111222.html
Latest published version:
http://www.w3.org/TR/getusermedia/
Latest editor's draft:
http://dev.w3.org/2011/webrtc/editor/getusermedia.html
Previous version:
http://dev.w3.org/2011/webrtc/editor/getusermedia-20111130.html
Editors:
Daniel C. Burnett, Voxeo
Anant Narayanan, Mozilla

Abstract

This document defines a set of 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 Media Capture TF as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org@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 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, surveillance.

This document defines the APIs used to get access to local devices (video cameras, microphones, Web cams) that can generate multimedia stream data.

2. Obtaining local multimedia content

2.1 Definition

2.1.2 MediaStreamOptions

dictionary MediaStreamOptions {
    boolean audio;
    boolean video;
};
2.1.2.1 Dictionary MediaStreamOptions Members
audio of type boolean
Set to true if an audio track is requested, default is false
video of type boolean
Set to true if a video track is requested, default is false

2.2 Examples

A voice chat feature in a game could attempt to get access to the user's microphone by calling the API as follows:

<script>
 navigator.getUserMedia({audio: true}, gotAudio);
 function gotAudio(stream) {
   // ... use 'stream' ...
 }
</script>

A video-conferencing system would ask for both audio and video:

<script>
   navigator.getUserMedia({audio: true, video: true}, gotStream);
 }
 function gotStream(stream) {
   // ... use 'stream' ...
 }
</script>

3. Garbage collection

4. Event definitions

-

5. Event summary

This section is non-normative.

5.1 Change Log

This section will be removed before publication.

To Do Items

-

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.

5.2 Acknowledgements

A. References

A.1 Normative references

[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/

A.2 Informative references

No informative references.