This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

getUserMedia

Summary

Prompts the user for permission to use a media device such as a camera or microphone. If the user provides permission, the successCallback is invoked on the calling application with a LocalMediaStream object as its argument.

Method of dom/Navigatordom/Navigator

Syntax

var stream = navigator.getUserMedia(constraints, successCallback, errorCallback);

Parameters

constraints

Data-type
MediaStreamConstraints

The constraints parameter is a MediaStreamConstraints object with two Boolean members: video and audio. These describe the media types supporting the LocalMediaStream object. Either or both must be specified to validate the constraint argument. If a specified constraint is not supported by the browser, getUserMedia invokes the errorCallback with the NOT_SUPPORTED_ERROR. If the browser cannot find any media track with the specified type, getUserMedia invokes the errorCallback with the MANDATORY_UNSATISFIED_ERR.

If the value or the member is not specified in the object, the value for the member defaults to false. The following demonstrates how to set the constraints for both audio and video:

{ video: true, audio: true }

There are additional constraints available. http://simpl.info/getusermedia/constraints/ demonstrates the use of maxWidth and maxHeight constraints. There is a set of resolutions that is currently supported at the libjingle level. They are summarized in this chromium ticket and can be confirmed in the libjingle source code

successCallback

Data-type
function

The getUserMedia function will call the function specified in the successCallback with the LocalMediaStream object that contains the media stream. You may assign that object to the appropriate element and work with it, as shown in the following example:

function(localMediaStream) {
   var video = document.querySelector('video');
   video.srcObject = localMediaStream;
   video.onloadedmetadata = function(e) {
      // Do something with the video here.
   };
},

errorCallback

Data-type
function

(Optional)

The getUserMedia function will call the function specified in the errorCallback with a code argument. The error codes are described as follows:

  • PERMISSION_DENIED - The user denied permission to use a media device required for the operation.
  • NOT_SUPPORTED_ERROR - A constraint specified is not supported by the browser.
  • MANDATORY_UNSATISFIED_ERROR - No media tracks of the type specified in the constraints are found.

Return Value

Returns an object of type LocalMediaStreamLocalMediaStream

Examples

This live example uses feature detection to determine if the current web browser and operating system version supports the navigator.getUserMedia method.


View live example

Notes

The ms prefixed method is only available on windows 8 operating system. At the time of writing the standards getUserMedia method is ‘in development’

Attributions