mozilla
Your Search Results

    NavigatorUserMedia.getUserMedia()

    This article is in need of a technical review.

    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.

    Syntax

    navigator.getUserMedia(constraints, successCallback, errorCallback);

    Parameters

    Parameter Required/Optional Description
    constraints Required The media types that support the LocalMediaStream object returned in the successCallback.
    successCallback  Required The function on the calling application to invoke when passing the LocalMediaStream object.
    errorCallback Optional (Required in Firefox) The function on the calling application to invoke if the call fails. Please note, this argument is required in recent versions of Firefox. Not providing this argument will throw an NS_ERROR_XPC_NOT_ENOUGH_ARGS error.

    constraints

    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 }

    successCallback

    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.src = window.URL.createObjectURL(localMediaStream);
       video.onloadedmetadata = function(e) {
          // Do something with the video here.
       };
    },

    errorCallback

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

    Error  Description 
    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.

    Example

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

    navigator.getUserMedia = ( navigator.getUserMedia ||
                           navigator.webkitGetUserMedia ||
                           navigator.mozGetUserMedia ||
                           navigator.msGetUserMedia);
    
    if (navigator.getUserMedia) {
       navigator.getUserMedia (
    
          // constraints
          {
             video: true,
             audio: true
          },
    
          // successCallback
          function(localMediaStream) {
             var video = document.querySelector('video');
             video.src = window.URL.createObjectURL(localMediaStream);
             // Do something with the video here, e.g. video.play()
          },
    
          // errorCallback
          function(err) {
             console.log("The following error occured: " + err);
          }
       );
    } else {
       console.log("getUserMedia not supported");
    }

    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.

    Browser compatibility

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

    12
    18webkit

    Not supported 
    Feature Android Firefox Mobile (Gecko) Firefox OS (Gecko) IE Phone Opera Mobile Safari Mobile
    Stream API  Not supported  24moz  1.2 for audio moz
    1.4 for video moz
    Not supported  12 Not supported 

    Currently, using WebRTC to access the camera is supported in Chrome, Opera, and Firefox 20 and later.

    See also

    Document Tags and Contributors

    Last updated by: Sheppy,
    Hide Sidebar