Navigator.getUserMedia

  • Revision slug: WebRTC/navigator.getUserMedia
  • Revision title: navigator.getUserMedia
  • Revision id: 360401
  • Created:
  • Creator: merihakar
  • Is current revision? No
  • Comment Compatibility table data was outdated

Revision Content

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 );

Example

Here's an example of using getUserMedia() with browser prefixes.

navigator.getMedia = ( navigator.getUserMedia ||
                       navigator.webkitGetUserMedia ||
                       navigator.mozGetUserMedia ||
                       navigator.msGetUserMedia);

navigator.getMedia (

   // constraints
   {
      video: true,
      audio: true
   },

   // successCallback
   function(localMediaStream) {
      var video = document.querySelector('video');
      video.src = window.URL.createObjectURL(localMediaStream);
      video.onloadedmetadata = function(e) {
         // Do something with the video here.
      };
   },

   // errorCallback
   function(err) {
    console.log("The following error occured: " + err);
   }

);

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 The function on the calling application to invoke if the call fails.

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.

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Stream API  21{{property_prefix("webkit")}}  18{{property_prefix("moz")}}  {{CompatNo}}  12 {{CompatUnknown}} 
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Stream API  {{CompatNo}}  {{CompatUnknown}} {{CompatUnknown}}  12 {{CompatNo}} 

Currently using WebRTC for accessing the camera is supported in Chrome, Opera and Firefox Nightly 18. Enabling WebRTC in Firefox Nightly requires you to set a flag in the configuration:

  • Type "about:config" in the address bar and say yes that you want to make changes
  • Find the "media.navigator.enabled" entry and set it to true

See also

Revision Source

<p>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 <a href="/en-US/docs/WebRTC/MediaStream_API#LocalMediaStream" title="WebRTC/MediaStream_API#LocalMediaStream">LocalMediaStream</a> object as its argument.</p>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox">navigator.getUserMedia ( constraints, successCallback, errorCallback );</pre>
<p><strong>Example</strong></p>
<p>Here's an example of using getUserMedia() with browser prefixes.</p>
<pre class="brush: js">navigator.getMedia = ( navigator.getUserMedia ||
                       navigator.webkitGetUserMedia ||
                       navigator.mozGetUserMedia ||
                       navigator.msGetUserMedia);

navigator.getMedia (

   // constraints
   {
      video: true,
      audio: true
   },

   // successCallback
   function(localMediaStream) {
      var video = document.querySelector('video');
      video.src = window.URL.createObjectURL(localMediaStream);
      video.onloadedmetadata = function(e) {
         // Do something with the video here.
      };
   },

   // errorCallback
   function(err) {
    console.log("The following error occured: " + err);
   }

);</pre>
<h2 id="Parameters">Parameters</h2>
<table>
  <thead>
    <tr>
      <th scope="col">parameter </th>
      <th scope="col">Required/ <br>
        Optional </th>
      <th scope="col">Description </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>constraints</td>
      <td>Required</td>
      <td>The media types that support the LocalMediaStream object returned in the successCallback.</td>
    </tr>
    <tr>
      <td>successCallback </td>
      <td>Required</td>
      <td>The function on the calling application to invoke when passing the LocalMediaStream object.</td>
    </tr>
    <tr>
      <td>errorCallback</td>
      <td>Optional</td>
      <td>The function on the calling application to invoke if the call fails.</td>
    </tr>
  </tbody>
</table>
<h3 id="constraints">constraints</h3>
<p>The constraints parameter is a MediaStreamConstraints object with two Boolean members: <code>video</code> and <code>audio</code>. These describe the media types supporting the <a href="/en-US/docs/WebRTC/MediaStream_API#LocalMediaStream" title="WebRTC/MediaStream_API#LocalMediaStream">LocalMediaStream</a> 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.</p>
<p>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:</p>
<pre>{ video: true, audio: true }</pre>
<h3 id="successCallback">successCallback</h3>
<p>The getUserMedia function will call the function specified in the successCallback with the <a href="/en-US/docs/WebRTC/MediaStream_API#LocalMediaStream" title="WebRTC/MediaStream_API#LocalMediaStream">LocalMediaStream</a> 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:</p>
<pre>function(localMediaStream) {
   var video = document.querySelector('video');
   video.src = window.URL.createObjectURL(localMediaStream);
   video.onloadedmetadata = function(e) {
      // Do something with the video here.
   };
},</pre>
<h3 id="errorCallback">errorCallback</h3>
<p>The getUserMedia function will call the function specified in the errorCallback with a <code>code</code> argument. The error codes are described as follows:</p>
<table>
  <thead>
    <tr>
      <th scope="col">Error </th>
      <th scope="col">Description </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>PERMISSION_DENIED </td>
      <td>The user denied permission to use a media device required for the operation. </td>
    </tr>
    <tr>
      <td>NOT_SUPPORTED_ERROR </td>
      <td>A constraint specified is not supported by the browser.</td>
    </tr>
    <tr>
      <td>MANDATORY_UNSATISFIED_ERROR </td>
      <td>No media tracks of the type specified in the constraints are found.</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
  {{CompatibilityTable}}</div>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Stream API </td>
        <td>21{{property_prefix("webkit")}} </td>
        <td>18{{property_prefix("moz")}} </td>
        <td>{{CompatNo}} </td>
        <td>12</td>
        <td>{{CompatUnknown}} </td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Stream API </td>
        <td>{{CompatNo}} </td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}} </td>
        <td>12</td>
        <td>{{CompatNo}} </td>
      </tr>
    </tbody>
  </table>
</div>
<p><span style="line-height: 1.5em; ">Currently using WebRTC for accessing the camera is supported in Chrome, Opera and Firefox Nightly 18. Enabling WebRTC in Firefox Nightly requires you to set a flag in the configuration:</span></p>
<ul style="padding-top: 0px; padding-right: 0px; padding-bottom: 0px; margin: 0px 0px 1.286em; ">
  <li>Type "about:config" in the address bar and say yes that you want to make changes</li>
  <li>Find the "media.navigator.enabled" entry and set it to true</li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/WebRTC" title="WebRTC">WebRTC</a> - the introductory page to the API</li>
  <li><a href="/en-US/docs/WebRTC/MediaStream_API" title="WebRTC/MediaStream_API">MediaStream API</a> - the API for the media stream objects</li>
  <li><a href="/en-US/docs/WebRTC/taking_webcam_photos" title="WebRTC/taking_webcam_photos">Taking webcam photos</a> - a tutorial on using getUserMedia()</li>
</ul>
Revert to this revision