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

2. Obtaining local multimedia content

2.1 Definition

2.1.1 NavigatorUserMedia

[NoInterfaceObject]
interface NavigatorUserMedia {
    void getUserMedia (MediaStreamOptions? options, NavigatorUserMediaSuccessCallback? successCallback, optional NavigatorUserMediaErrorCallback? errorCallback);
};

2.1.1.1 Methods

getUserMedia

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

The options argument is an object of type MediaStreamOptions.

If the user accepts, the successCallback is invoked, with a suitable LocalMediaStream object [WEBRTC10] as its argument.

If the user declines, the errorCallback (if any) is invoked.

When the getUserMedia() method is called, the user agent must run the following steps:

Let options 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.
If successCallback is null, abort these steps.
For each member of the MediaStreamOptions dictionary create a local representation and set it to false.
For each property in options that is present and set to true, let the corresponding local representation be true.
If none of the local representations of the MediaStreamOptions dictionary members is set to true, then throw a NOT_SUPPORTED_ERR exception and abort these steps.
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 [WEBRTC10] representing a media stream.

The provided media should include a track for each local representation of the MediaStreamOptions dictionary members that is set to true.

The provided media must not include a track for any of the local representation of the MediaStreamOptions dictionary members that is not set to true.

User agents are encouraged to default to using the user's primary or system default camera and/or microphone (as appropriate) to generate the media stream. User agents may allow users to use any media source, including pre-recorded media files.

User agents may wish to offer the user more control over the provided media. For example, a user agent could offer to enable a camera light or flash, or to change settings such as the frame rate or shutter speed.

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

Parameter	Type	Nullable	Optional
options	`MediaStreamOptions`	✔	✘
successCallback	`NavigatorUserMediaSuccessCallback`	✔	✘
errorCallback	`NavigatorUserMediaErrorCallback`	✔	✔

No exceptions.

Return type: void

Navigator implements NavigatorUserMedia;

All instances of the Navigator type are defined to also implement the NavigatorUserMedia interface.

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.1.3 NavigatorUserMediaSuccessCallback

[Callback=FunctionOnly, NoInterfaceObject]
interface NavigatorUserMediaSuccessCallback {
    void handleEvent (LocalMediaStream stream);
};

2.1.3.1 Methods

handleEvent

(Explanation of handleEvent TBD)

Parameter	Type	Nullable	Optional	Description
stream	`LocalMediaStream`	✘	✘

No exceptions.

Return type: void

2.1.4 NavigatorUserMediaError and NavigatorUserMediaErrorCallback

[NoInterfaceObject]
interface NavigatorUserMediaError {
    const unsigned short PERMISSION_DENIED = 1;
    readonly attribute unsigned short code;
};

2.1.4.1 Attributes

code of type unsigned short, readonly: Returns the current error's error code. At this time, this will always be 1, for which the constant PERMISSION_DENIED is defined.
No exceptions.

2.1.4.2 Constants

PERMISSION_DENIED of type unsigned short: The user denied the page permission to use the user's media devices.

[Callback=FunctionOnly, NoInterfaceObject]
interface NavigatorUserMediaErrorCallback {
    void handleEvent (NavigatorUserMediaError error);
};

2.1.4.3 Methods

handleEvent

(Explanation of handleEvent TBD)

Parameter	Type	Nullable	Optional	Description
error	`NavigatorUserMediaError`	✘	✘

No exceptions.

Return type: void

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

-

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

W3C Editor's Draft 22 December 2011

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Obtaining local multimedia content

2.1 Definition

2.1.1 NavigatorUserMedia

2.1.1.1 Methods

2.1.2 MediaStreamOptions

2.1.2.1 Dictionary `MediaStreamOptions` Members

2.1.3 NavigatorUserMediaSuccessCallback

2.1.3.1 Methods

2.1.4 NavigatorUserMediaError and NavigatorUserMediaErrorCallback

2.1.4.1 Attributes

2.1.4.2 Constants

2.1.4.3 Methods

2.2 Examples

3. Garbage collection

4. Event definitions

5. Event summary

5.1 Change Log

To Do Items

Dec 21 2011

Nov 29 2011

Nov 15 2011

Nov 9 2011

5.2 Acknowledgements

A. References

A.1 Normative references

A.2 Informative references

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

W3C Editor's Draft 22 December 2011

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Obtaining local multimedia content

2.1 Definition

2.1.1 NavigatorUserMedia

2.1.1.1 Methods

2.1.2 MediaStreamOptions

2.1.2.1 Dictionary MediaStreamOptions Members

2.1.3 NavigatorUserMediaSuccessCallback

2.1.3.1 Methods

2.1.4 NavigatorUserMediaError and NavigatorUserMediaErrorCallback

2.1.4.1 Attributes

2.1.4.2 Constants

2.1.4.3 Methods

2.2 Examples

3. Garbage collection

4. Event definitions

5. Event summary

5.1 Change Log

To Do Items

Dec 21 2011

Nov 29 2011

Nov 15 2011

Nov 9 2011

5.2 Acknowledgements

A. References

A.1 Normative references

A.2 Informative references

2.1.2.1 Dictionary `MediaStreamOptions` Members