Web API WebRTC.getUserMedia() Method

The MediaDevices.getUserMedia() is a part of the webRTC media capture API and is used to get access to the camera and the microphone connected to the user device (user computer, smartphone, etc.) from the browser. When getUserMedia() is invoked, the browser asks for permission from the user to use the media inputs (camera or microphone or both) connected to the user device.

Syntax :

navigator.mediaDevices.getUserMedia( MediaStreamConstraints )
     .then( MediaStream => {
        // Code that uses the MediaStream
     }).catch( error => {
        // Code to handle the error
     });

Using the getUserMedia() API: getUserMedia() can be accessed by accessing the navigator.mediaDevices singleton object that offers various methods for accessing the camera, microphone as well as screen sharing. When getUserMedia() is invoked, the browser prompts the User for permission to access the available device camera or microphone (based on the given MediaStreamConstraints parameter). If the User gives the permission, then it returns a Promise that resolves to a MediaStream. 

Note: getUserMedia() can be accessed through navigator.getUserMedia() also, but it is deprecated and hence not recommended.

What is a MediaStream?

MediaStream is simply a stream of audio or video content data that is not saved in the device memory, rather it is just “passed” to a specific video or audio element as the source data. Note that the media content data is not saved in the running memory, which means if you don’t have a “pre-downloaded” video or audio data, still you can use the media stream to play the video or audio content as it does not need to be downloaded.

What is MediaStreamConstraints?

MediaStreamConstraints is an object containing all the constraints like what type of data is/are to be streamed (video or audio or both ), what should be the resolution of the camera etc. 

const mediaStreamConstraints = {
    audio: true,
    video: true
}; 

// It basically tells the getUserMedia() to 
// open both the camera and the microphone
const stream = await navigator.mediaDevices
  .getUserMedia(mediaStreamConstraints);

Using the MediaStream received from the getUserMedia(): If the user gives permission to access the camera and the microphone, then this method returns a promise whose fulfillment handler receives a MediaStream that we can use in the handler function. Usually, we pass the received MediaStream to a video or audio element as the source (using the srcObject attribute of video or audio element).   

What if the user does not give permission to access the camera and microphone ?

If the User denies giving permission then getUserMedia() throws a NotAllowedError that we can catch using the catch block. If the user simply ignores the prompt, then nothing happens( the promise is never resolved nor rejected). 

Now, let’s discuss the MediaStreamConstraints with more details: 

MediaStreamConstraints:

This is basically an object containing all the information regarding what type of media to use, what should be the resolution of the camera, which device to use as the media input etc. The simplest MediaStreamConstraints object looks like this —

const constraints = {
      audio: false, // or true if you want to enable audio
      video: true  // or false if you want to disable video
}; // Includes only the video media if available

MediaStreamConstraints object has only two properties(members): audio and video, both of them accepts a boolean value that tells the browser whether to include that specific media content in the resulting media stream. “true” makes the media “required” in the resulting media stream, if that “required” media is not available then getUserMedia() throws “NotFoundError”.  For example, getUserMedia() will throw “NotFoundError” for the above constraints if the user device doesn’t have a camera.

Additionally, you can add more constraints to use media content with some preferred capabilities : 

You can specify the resolution of the camera the browser should prefer:

“prefer” because the above constraints object does not ensure that the browser will use a camera with that resolution. The browser first checks if there is any type of media input that matches the given constraints, and if there is any then only the browser uses that matching media input. But if there are none that match the given constraints, then the browser uses the device with the closest match. 

But if you want to make some capabilities “required” or mandatory or apply some limit on the capabilities, then you can use various key-words:

• The “min” and “max” keywords : 

As the names of the key-words suggest, the “min” key-word tells the browser that the corresponding media is required to have at least the given capabilities, similarly, the “max” key-word tells the browser that it is mandatory for the corresponding media to have at-most the specified constraint.  If no such media input device meets the given constraints, then the returned promise is rejected with “NotFoundError”.

• The “deviceId” keyword :

The “deviceId” property asks the browser to use the media input device having the given deviceId if available otherwise use other available input devices. The deviceId can be obtained from the navigator.mediaDevices.enumerateDevices() method that returns a promise that resolves to a list of connected cameras, microphones, headsets, etc. Each connected device has a unique and unguessable  id called “deviceId”.

3. The “exact” keyword :

The “exact” property tells the browser that it is mandatory to use a media having exactly the corresponding constraint 

4. The “ideal” property:

The “ideal” property tells the browser that the given constraint value is the ideal value and the device having the “ideal” constraint should be used. Any normal property values are inherently ideal 

5. The “facingMode” property: 

Specifies whether to use the front camera or the rear camera if available. It is mainly used for mobile devices.

Example of using getUserMedia() :

Output: 

Now if you click the “Open Camera” button, the browser will ask for your permission, if you allow, then you will see yourself on the screen. But if you deny, then you can see the error right below the video element in a red box:

How to close the camera and the microphone:

Till now, we have discussed how to open the camera from the browser, we have done nothing to stop using the camera and the microphone. Though, if you close the tab or window, the browser automatically stops using the camera and the microphone. But if you want to close the camera and the microphone yourself, then you can follow the below code

Example 2: First, add a “Close Camera” button and “closeCamera() method.

Output:

Before:

After click “Close Camera” button:

The closeCamera() method checks if the camera and the microphone both are closed or not by checking the receivedMediaStream variable. If it is null, it means the camera and the microphone both are closed, else it calls the getTracks() method of the received MediaStream which returns an array of MediaStreamTracks. You can stop those media tracks by calling its stop() method.