Constraining the media stream

Now that we know how to get a stream from the browser, we will cover configuring this stream using the first parameter of the getUserMedia API. This parameter expects an object of keys and values telling the browser how to look for and process streams coming from the connected devices. The first options we will cover are simply turning on or off the video or audio streams:

navigator.getUserMedia({ video: false, audio: true }, function (stream) {
  // Now our stream does not contain any video!
});

When you add this stream to the <video> element, it will now not show any video coming from the camera. You can also do the opposite and get just a video feed and no audio. This is great while developing a WebRTC application when you do not want to listen to yourself talk all day!

Tip

Typically, you will be calling yourself a lot while developing the WebRTC applications. This creates the phenomenon known as audio feedback where you are being recorded through the microphone and also playing those sounds through the speakers, creating an endless echo or loud ringing sound. Turning the audio off temporarily helps fix this issue during the development!

Let's take a look at the following screenshot, which illustrates a drop-down popup stating that http://localhost/8080 needs access to the microphone:

This can also be useful while creating a communication application that allows users to make audio-only calls, replicating a normal phone call. If someone does not want to share his/her video, it will only request access to the microphone in the browser. This will also prevent the camera from turning on or showing any lights, indicating that the browser is recording them.

Constraining the video capture

The options for constraining the getUserMedia API not only allows the true or false values, but also allows you to pass in an object with a complex set of constraints. You can see the full set of constraints provided in the specification detailed at https://tools.ietf.org/html/draft-alvestrand-constraints-resolution-03. These allow you to constrain options such as minimum required resolution and frameRate, video aspect ratio, and optional parameters all through the configuration object passed into the getUserMedia API.

This helps developers tackle several different scenarios that are faced while creating a WebRTC application. It gives the developer an option to request certain types of streams from the browser depending on the situation that the user is currently in. Some of these streams are listed here:

• Asking for a minimum resolution in order to create a good user experience for everyone participating in a video call
• Providing a certain width and height of a video in order to stay in line with a particular style or brand associated with the application
• Limiting the resolution of the video stream in order to save computational power or bandwidth if on a limited network connection

For instance, let's say that we wanted to ensure the video playback is always set to the aspect ratio of 16:9. This would be to avoid the video coming back in a smaller than desired aspect ratio, such as 4:3. If you change your getUserMedia call to the following, it will enforce the correct aspect ratio:

navigator.getUserMedia({
    video: {
      mandatory: {
        minAspectRatio: 1.777,
        maxAspectRatio: 1.778
      },
      optional: [
        { maxWidth: 640 },
        { maxHeigth: 480 }
      ]
    },
    audio: false
  }, function (stream) {
    var video = document.querySelector('video');
    video.src = window.URL.createObjectURL(stream);
  }, function (error) {
    console.log("Raised an error when capturing:", error);
  });

When you refresh your browser and give permission to the page to capture your camera, you should see the video is now wider than it used to be. In the first section of the configuration object, we gave it a mandatory aspect ratio of 16:9 or 1.777. In the optional section, we told the browser that we would like to stay under a width and height of 640 x 480. The optional block tells the browser to try and meet these requirements, if at all possible. You will probably end up with a 640 x 360 width and height for your video as this is a common solution to these constraints that most cameras support.

You will also notice that we passed in a second function to getUserMedia call. This is the error callback function and gets called if there are any issues with capturing the media stream. This could happen to you in the preceding example if your camera did not support 16:9 resolutions. Be sure to keep an eye on the development console in your browser to see any errors that get raised when this happens. If you successfully run this project, you can also change minAspectRatio or maxAspectRatio to see which parameters your browser can successfully run:

The power this gives us is the ability to adapt to the situations of the user's environment to provide the best video stream possible. This is incredibly helpful since the environment for browsers is vast and varied from user to user. If your WebRTC application plans to have a lot of users, you will have to find unique solutions to every unique environment. One of the biggest pains is supporting mobile devices. Not only do they have limited resources, but also limited screen space. You might want the phone to only capture a 480 x 320 resolution or smaller video stream in order to conserve power, processing, and bandwidth. A good way to test whether the user is on a mobile device is to use the user agent string in the browser and test it against the names of common mobile web browsers. Changing the getUserMedia call to the following will accomplish this:

var constraints = {
    video: {
      mandatory: {
        minWidth: 640,
        minHeight: 480
      }
    },
    audio: true
  };
  if (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
    // The user is using a mobile device, lower our minimum resolution
    constraints = {
      video: {
        mandatory: {
          minWidth: 480,
          minHeight: 320,
          maxWidth: 1024,
          maxHeight: 768
        }
      },
      audio: true
    };
  }
  navigator.getUserMedia(constraints, function (stream) {
    var video = document.querySelector('video');
    video.src = window.URL.createObjectURL(stream);
  }, function (error) {
    console.log("Raised an error when capturing:", error);
  });

Constraints are not something to quickly glance over. They are the easiest way to increase the performance of a WebRTC application. While you are reading through the chapters in this book, you should be thinking about the different environments your application will run in and how you can best support each. We will also cover this in more depth in Chapter 8, Advanced Security and Large-scale Optimization, when we talk about WebRTC performance.