Note: This is a legacy API for backwards compatibility. Please use MediaDevices.getUserMedia() in new applications.

Prompts the user for permission to use one video and/or one audio input device such as a camera or screensharing and/or a microphone. If the user provides permission, then the successCallback is invoked with the resulting MediaStream object as its argument. If the user denies permission or media is not available, then the errorCallback is called with PermissionDeniedError or NotFoundError respectively. Note that it is possible for neither completion callback to be called, as the user is not required to make a choice.

Syntax

navigator.getUserMedia(constraints, successCallback, errorCallback);

Parameters

Parameter Required/Optional Description
constraints Required A MediaStreamConstaints object specifying the types of media to request, along with any requirements for each type.
successCallback  Required The function to invoke with the resulting MediaStream object if the call succeeds.
errorCallback Required The function to invoke with the resulting MediaStreamError if the call fails.

constraints

See constraints section under the modern navigator.mediaDevices.getUserMedia API.

successCallback

The getUserMedia() function will call the function specified in the successCallback with the MediaStream 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(stream) {
   var video = document.querySelector('video');
   video.src = window.URL.createObjectURL(stream);
   video.onloadedmetadata = function(e) {
      // Do something with the video here.
   };
}

errorCallback

The getUserMedia() function will call the function specified in the errorCallback with a MediaStreamError argument which is modeled on DOMException. The error codes are described as follows:

Error Description
PermissionDeniedError Permission to use a media device was denied by the user or the system.
NotFoundError No media tracks of the type specified were found that satisfy the constraints specified.

Examples

Width and height

Here's an example of using getUserMedia(), including code to cope with various browsers' prefixes.

navigator.getUserMedia = navigator.getUserMedia ||
                         navigator.webkitGetUserMedia ||
                         navigator.mozGetUserMedia;

if (navigator.getUserMedia) {
   navigator.getUserMedia({ audio: true, video: { width: 1280, height: 720 } },
      function(stream) {
         var video = document.querySelector('video');
         video.src = window.URL.createObjectURL(stream);
         video.onloadedmetadata = function(e) {
           video.play();
         };
      },
      function(err) {
         console.log("The following error occured: " + err.name);
      }
   );
} else {
   console.log("getUserMedia not supported");
}

See Examples section under the modern navigator.mediaDevices.getUserMedia API for more examples.

Permissions

To use getUserMedia() in an installable app (for example, a Firefox OS app), you need to specify one or both of the following fields inside your manifest file:

"permissions": {
  "audio-capture": {
    "description": "Required to capture audio using getUserMedia()"
  },
  "video-capture": {
    "description": "Required to capture video using getUserMedia()"
  }
}

See permission: audio-capture and permission: video-capture for more information.

Specifications

Specification Status Comment
Media Capture and Streams
The definition of 'navigator.getUserMedia' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Stream API 21webkit[1] 17moz[2] Not supported

12[1]
18webkit

Not supported
Feature Android Firefox Mobile (Gecko) Firefox OS (Gecko) IE Phone Opera Mobile Safari Mobile
Stream API 40webkit[1] 24moz[2] 1.2moz[3]
1.4moz
Not supported 12[1] Not supported

[1] Chrome and Opera still use an outdated constraint syntax, but the syntax described here is available through the adapter.js polyfill.

[2] The constraint syntax described here is available as of Firefox 38. Earlier versions (32-37) used an outdated constraint syntax, but the syntax described here is available there through the adapter.js polyfill.

[3] In Firefox OS 1.2 only audio was supported, 1.4 added support for video.

See also

Document Tags and Contributors

Last updated by: jwhitlock,
Hide Sidebar