<p>WebRTC is constantly evolving and with it, it&rsquo;s most known function&nbsp;<code>getUserMedia()</code>. With it you can get access to the device&rsquo;s webcams and microphones and request a video stream, an audio stream or both.</p>

<p>In this article we will be focusing on the video constraints available to us when requesting a video stream through&nbsp;<code>getUserMedia()</code>. In a previous blog post we&rsquo;ve focused on the&nbsp;<a href="../../../../blog/getusermedia-audio-constraints/">audio constraints</a>.</p>

<h3 id="mediastreamconstraints">MediaStreamConstraints</h3>

<p>The&nbsp;<code>getUserMedia()</code>&nbsp;function receives only one parameter, a&nbsp;<code>MediaStreamConstraints</code>object used to specify what kind of tracks (audio, video or both) to request, and, optionally, any requirements for each track.</p>

<p>Here&rsquo;s a basic example of how this object is sent to the newer, promise based,&nbsp;<code>getUserMedia()</code>:</p>

<pre class="wp-block-code"><code>var constraints = {
    audio: true,
    video: true
}
navigator.mediaDevices.getUserMedia(constraints).then(function(stream) {
    /* use the stream */
}).catch(function(err) {
    /* handle the error */
});</code></pre>

<p>The&nbsp;<code>constraints</code>&nbsp;object can have one or both of these 2 properties:</p>

<ul>
<li>video &ndash; indicates whether or not a video track is required</li>
<li>audio &ndash; indicates whether or not an audio track is required</li>
</ul>

<p>Here&rsquo;s how a basic constraint object that requires both an audio and a video stream looks like (the same one used above):</p>

<p>var constraints = { audio:true, video:true}</p>

<p>If you&rsquo;re just taking a picture and don&rsquo;t need an audio track just set the audio property to false like this:</p>

<pre class="wp-block-code"><code>var constraints = {
    audio: false,
    video: true
}</code></pre>

<p>If&nbsp;<code>true</code>&nbsp;is specified for video or audio, the resulting stream is&nbsp;<em>required</em>&nbsp;to have that particular media track in it, else the call to&nbsp;<code>getUserMedia()</code>&nbsp;will result in an&nbsp;<code>NotFoundError</code>error (see&nbsp;<a href="../../../../blog/common-getusermedia-errors/">common getUserMedia() Errors</a>&nbsp;for more details).</p>

<h3 id="mediatrackconstraints">MediaTrackConstraints</h3>

<p>The audio and video properties can take 2 types of values:</p>

<ul>
<li>a Boolean value (true or false) as above</li>
<li>a&nbsp;<code>MediaTrackConstraints</code>&nbsp;object which provides specific properties like width and height that must be met by the track.</li>
</ul>

<h4 id="videotrackconstraintsresolution">Video Track Constraints: Resolution</h4>

<p>One can use the&nbsp;<code>width</code>&nbsp;and&nbsp;<code>height</code>&nbsp;properties to request a certain resolution from the webcam. In this example the browser will request a 720p (1280&times;720) video stream:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 1280,
        height: 720
    }
}</code></pre>

<p><strong>The browser will try to honor this, but may return a different resolution stream.</strong>From my experience this often happens because the webcam does not support the requested resolution (try requesting odd resolutions like 721&times;55 and see what happens). It might also be that the constraints were overridden by another&nbsp;<code>getUserMedia()</code>&nbsp;call from a different app on Mac (where webcam access is shared) or a different Chrome tab (shared access). Other reasons might exist too.</p>

<p>You can try the&nbsp;<a href="https://webrtchacks.github.io/WebRTC-Camera-Resolution/" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">WebRTC camera resolution finder</a>&nbsp;to see what resolutions are supported by your browser and webcam combo.</p>

<h4 id="keywords">Keywords</h4>

<p>If the resolution is important to you and the device and browser can not guarantee it then you can use the&nbsp;<code>min</code>,&nbsp;<code>max</code>&nbsp;and&nbsp;<code>exact</code>&nbsp;keywords to help you get the best resolution from any device.&nbsp;These keywords apply to&nbsp;<em>any</em>&nbsp;MediaTrackConstraint property.</p>

<p>If for example you&rsquo;re doing image recognition in video streams and absolutely require 1280&times;720 resolution use this constraint :</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: {
            exact: 1280
        },
        height: {
            exact: 720
        }
    }
}</code></pre>

<p>In the example above, if no camera exists that supports the exact resolution, then the returned promise will be rejected with&nbsp;<code>OverconstrainedError</code>, and the user will not be prompted(see&nbsp;<a href="../../../../blog/common-getusermedia-errors/">common getUserMedia() Errors</a>&nbsp;for details).</p>

<p>The following constraint also requests a of 1280&times;720 resolution but it also mentions 320&times;240 as the minimum resolution since not all webcams support 1280&times;720 and in some use cases it&rsquo;s better to get something rather than nothing:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: {
            min: 320,
            max: 1280
        },
        height: {
            min: 240,
            max: 720
        }
    }
}</code></pre>

<p>Values without the&nbsp;<code>min</code>,&nbsp;<code>max</code>&nbsp;and&nbsp;<code>exact</code>&nbsp;keywords are considered&nbsp;<code>ideal</code>&nbsp;values, which itself is a keyword but it is not mandatory. These 2 examples do the same thing:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 1280,
        height: 720
    }
}</code></pre>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: {
            ideal: 1280
        },
        height: {
            ideal: 720
        }
    }
}</code></pre>

<h4 id="videotrackconstraintsgettingthefrontorrearcameraonmobiledevices">Video Track Constraints: Getting The Front Or Rear Camera On Mobile Devices</h4>

<p>One can use the&nbsp;<code>facingMode</code>&nbsp;property for the video track constraint. Accepted values are:&nbsp;<code>user</code>&nbsp;(front camera),&nbsp;<code>environment</code>&nbsp;(rear camera),&nbsp;<code>left</code>&nbsp;and&nbsp;<code>right</code>.</p>

<p>Here&rsquo;s how to request a video stream that should&nbsp;<em>ideally</em>&nbsp;come from the back camera:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 640,
        height: 480,
        facingMode: "environment"
    }
}</code></pre>

<p>or</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 640,
        height: 480,
        facingMode: {
            ideal: "environment"
        }
    }
}</code></pre>

<p>Here&rsquo;s how to request a video stream that should&nbsp;<em>absolutely</em>&nbsp;come from the back camera:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 640,
        height: 480,
        facingMode: {
            exact: "environment"
        }
    }
}</code></pre>

<p>I am not sure how well these are supported by mobile browsers.</p>

<h4 id="videotrackconstraintsframerate">Video Track Constraints: Frame Rate</h4>

<p>Since frame rate has a direct impact on video quality but also bandwidth, in some cases, like publishing a video stream over low bandwidth connections, it might be a good idea to limit the frame rate. I was able to obtain a 60fps stream from the Logitech C925E by using:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        width: 320,
        height: 240,
        frameRate: {
            ideal: 60,
            min: 10
        }
    }
}</code></pre>

<p>Keep in mind the frame rate of a stream coming from a webcam depends a lot on the light in the room.</p>

<h3 id="usingacertainwebcamormicrophonedevice">Using a Certain Webcam or Microphone Device</h3>

<p>There is one constraint property that applies to both audio and video tracks:&nbsp;<code>deviceId</code>. It specifies the device ID (or an array of IDs which) which should be used for capturing that stream. The device ID is unique and will be the same across browsing sessions on the same origin. You will need to first obtain the device id using&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices" target="_blank" rel="noopener"><code>MediaDevices.enumerateDevices()</code></a>.</p>

<p>Once you know the&nbsp;<code>deviceId</code>&nbsp;you can ask for a specific webcam or microphone:</p>

<pre class="wp-block-code"><code>{
    audio: true,
    video: {
        deviceId: {
            exact: "the_device_id"
        }
    }
}</code></pre>

<p>There&rsquo;s also&nbsp;<code>groupId</code>, a shared id by all media sources that come from the same physical device. For example: a microphone and speaker that come from the same headset will share the same group ID.</p>

<p><a href="https://webrtc.github.io/samples/src/content/devices/input-output/" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">This example</a>&nbsp;allows you to switch between the available devices used for input (mic &amp; cam) and output (speaker).</p>

<h3 id="mediadevicesgetsupportedconstraints">MediaDevices.getSupportedConstraints()</h3>

<p>Chrome 53, Firefox 44 and Safari 11 added support for&nbsp;<code>MediaDevices.getSupportedConstraints()</code>. The function returns a dictionary listing the constraints supported by the user agent.</p>

<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getSupportedConstraints#Result" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Click here</a>&nbsp;to run it for your current browser.</p>

<p>The function seems to return a lot of false positives,&nbsp;<code>track.getSettings()</code>&nbsp;gives better results.</p>

<h3 id="mediastreamtrackgetsettings">MediaStreamTrack.getSettings()</h3>

<p>You can also check which constraints are supported by using&nbsp;<code>track.getSettings()</code>. It returns an object containing all applicable constraints, including those supported by the browser but whose defaults have not been changed through code.</p>

<p>Here&rsquo;s how to use the function and print the result to the console:</p>

<pre class="wp-block-code"><code>navigator.mediaDevices.getUserMedia(constraints).then(function success(stream) {
    video.srcObject = stream;
    stream.getTracks().forEach(function(track) {
        console.log(track.getSettings());
    })
});</code></pre>

<p>This&nbsp;<a href="https://codepen.io/naicuoctavian/pen/EbZwMy" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">code pen</a>&nbsp;will write in page the result of&nbsp;<code>track.getSettings()</code>&nbsp;for your browser.</p>

<p>The function has been added in Chrome 59 and it&rsquo;s also supported by Firefox and Safari 11.</p>

<h3 id="oldconstraints">Old Constraints</h3>

<p>The&nbsp;<a href="https://w3c.github.io/mediacapture-main/getusermedia.html#media-track-constraints" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">specifications for the constraints object</a>&nbsp;has changed in the past. Constraints using the old spec looked like this:</p>

<pre class="wp-block-code"><code>var constraints = {
    audio: true,
    video: {
        mandatory: {
            minWidth: 640,
            maxWidth: 640,
            minHeight: 480,
            maxHeight: 480
        }
    }
}</code></pre>

<p>The old spec was the only one supported by Chrome until Chrome 59 (June 2017) which added support for the new one. Older versions of Chrome can also use the new spec through&nbsp;<a href="https://github.com/webrtc/adapter" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">adapter.js</a></p>

<p>Firefox 38+ (May 2015) and Safari 11 both support the new video constraints spec.</p>

WebRTC is constantly evolving and with it, it’s most known function getUserMedia(). With it you can get access to the device’s webcams...

getUserMedia() Video Constraints - TCMHACK

getUserMedia() Video Constraints

<p>The&nbsp;<a href="https://www.w3.org/TR/mediacapture-streams/" target="_blank" rel="noopener">Media Capture and Streams spec</a>&nbsp;governs the cross browser audio options that should be implemented by all browsers and, in it&rsquo;s&nbsp;<a href="https://www.w3.org/TR/mediacapture-streams/" target="_blank" rel="noopener">latest Candidate Recommendation incarnation</a>, it defines quite a few audio constraints.</p>

<p>Here&rsquo;s the full list with explanations&nbsp;<a href="https://www.w3.org/TR/mediacapture-streams/#def-constraint-volume" target="_blank" rel="noopener">from both the spec</a>&nbsp;and from my knowledge around how digital sound works:</p>

<ul>
<li><code>sampleRate</code>: specifies a desired sample rate, not sure if it should be used as an encoding setting or as a hardware requirement, higher is better (Audio CDs for example have 44000 samples/s or 44kHz)</li>
<li><code>sampleSize</code>: each sample&rsquo;s size in bits, higher is better (Audio CDs have a sample size of 16 bits/sample )</li>
<li><code>volume</code>: it takes values between 0.0 (silence) and 1.0 (max volume), it&rsquo;s used as a multiplier for each sample&rsquo;s value</li>
<li><code>echoCancellation</code>: whether or not to use echo cancellation to try and remove the audio that went to the speakers from the input that comes through the mic</li>
<li><code>autoGainControl</code>: whether or not to modify the volume of the input from the mic</li>
<li><code>noiseSuppression</code>: whether or not to try and remove the background noise from the audio signal</li>
<li><code>latency</code>: specified in seconds, controls the time between the start of the sound processing and the data being made available to the next step, not so sure why you&rsquo;d want higher latency but audio codecs do differ in latency</li>
<li><code>channelCount</code>: specifies the number of channels to use with 1 being mono, 2 being stereo. It works with some webcams and laptops with dual mics.</li>
</ul>

<p>A surprisingly comprehensive list &ndash; at least&nbsp;<a href="http://audior.ec/blog/audio-quality-and-bitrate-in-flash-as3-web-apps/" target="_blank" rel="noopener">when comparing with the options Flash gave us</a>&nbsp;&ndash; but just as surprising most of them are not widely supported by browsers. Understandably some of them are new (autoGainControl and noiseSuppression) but others (sampleRate, sampleSize, and echoCancellation) were added to the spec as early as February 2014. Adding support for these constraints would open up&nbsp;<a href="https://hacks.mozilla.org/2012/09/its-opus-it-rocks-and-now-its-an-audio-codec-standard/" target="_blank" rel="noopener">Opus&rsquo; flexibility</a>to developers.</p>

<h3 id="browsersupportincludingsafari11">Browser Support (Including Safari 11)</h3>

<p>I&rsquo;ve used&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getSettings" target="_blank" rel="noopener"><code>MediaStreamTrack.getSettings()</code></a>&nbsp;to log to console the settings supported by each browser as&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getSupportedConstraints" target="_blank" rel="noopener"><code>MediaDevices.getSupportedConstraints()</code></a>&nbsp;returns too many false positives . I also tested the latest versions of Chrome, Firefox and Safari to make sure changing the constraints has an effect.</p>

<table class="wp-block-table">
<thead>
<tr>
<td>&nbsp;</td>
<th>CHROME 62</th>
<th>FIREFOX 56</th>
<th>SAFARI 11</th>
</tr>
</thead>
<tbody>
<tr>
<td>echoCancellation</td>
<td>supported, on by default</td>
<td>supported, on by default</td>
<td>supported, on by default</td>
</tr>
<tr>
<td>sampleRate</td>
<td>fixed: 48000</td>
<td>fixed: 48000</td>
<td>fixed: 44100</td>
</tr>
<tr>
<td>noiseSuppression</td>
<td>on by default, constraint not supported</td>
<td>supported, true by default</td>
<td>no</td>
</tr>
<tr>
<td>autoGainControl</td>
<td>on by default, constraint not supported</td>
<td>supported, false by default</td>
<td>no</td>
</tr>
<tr>
<td>channelCount</td>
<td>no</td>
<td>supported, records<br>max avb. channels by<br>default</td>
<td>no</td>
</tr>
<tr>
<td>volume</td>
<td>no</td>
<td>no</td>
<td>supported, defaults<br>to 1 (the maximum)</td>
</tr>
</tbody>
</table>

<p>Use&nbsp;<a href="https://codepen.io/naicuoctavian/pen/EbZwMy" target="_blank" rel="noopener" aria-label=" (opens in a new tab)">this code pen</a>&nbsp;to check future browser support (does not work in Safari because Safari does not allow getUserMedia() in cross origin iframes).</p>

<h3 id="usingaudioconstraintswithgetusermedia">Using Audio Constraints With getUserMedia()</h3>

<p>All constraints can be sent to&nbsp;<code>getUserMedia()</code>&nbsp;as a property of the audio object inside the constraints object. Here&rsquo;s an example using the newer promise based&nbsp;<code>getUserMedia()</code>:</p>

<pre class="wp-block-code"><code>var constraints = {
    audio: {
        sampleRate: 48000,
        channelCount: 2,
        volume: 1.0
    },
    video: true
}
navigator.mediaDevices.getUserMedia(constraints).then(function(stream) {
    /* use the stream */
}).catch(function(err) {
    /* handle the error */
});</code></pre>

<p>If you just want to use whatever defaults are set on the browser just pass true for the audio object:</p>

<pre class="wp-block-code"><code>var constraints = { audio: true, video:true }</code></pre>

<h3 id="stereoaudiorecordingsinfirefox55and56">Stereo Audio Recordings in Firefox 55 and 56</h3>

<p><a href="https://www.mozilla.org/en-US/firefox/55.0/releasenotes/" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Firefox 55</a>&nbsp;added support for stereo recordings so I was able to record a video with dual channel (stereo) audio with:</p>

<ul>
<li>the Logitech C925e (dual mics)</li>
<li>the older Logitech C920 (dual mics)</li>
<li>a 15&Prime; Mid 2017 MacBook PRO (3 mics)</li>
</ul>
<p><img src="../../../../uploads/1744774797180-stereo-webm-recording-with-arrow-300x208.png" alt="" width="300" height="208"></p>

<p>The channel separation was very clear with the&nbsp;<a href="https://www.logitech.com/en-us/product/c925e-webcam" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Logitech C925e</a>&nbsp;where the mics are widely spaced apart as opposed to MacBook PRO&rsquo;s 3 microphones which&nbsp;<a href="https://www.ifixit.com/Teardown/MacBook+Pro+13-Inch+Touch+Bar+Teardown/73480#s148070" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">are closely grouped together on the right side of the keyboard</a>.</p>

<p><a href="https://www.mozilla.org/en-US/firefox/56.0/releasenotes/" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Firefox 56</a>&nbsp;also added support for the&nbsp;<code>channelCount</code>&nbsp;constraint meaning I was able to switch from stereo recording &ndash; which seems to be the default when using webcams with dual mics &ndash; to mono recordings which should take up less bandwidth. Here&rsquo;s how to request a mono stream:</p>

<pre class="wp-block-code"><code>{
    audio: {
        channelCount: 1
    },
    video: true
}</code></pre>

<p>A value of 0, the default, tells&nbsp;<code>getUserMedia()</code>&nbsp;to capture all of the available, supported, channels.</p>

<p>Chrome 62 records just mono audio and setting the&nbsp;<code>channelCount</code>&nbsp;constraint (<a href="https://blog.addpipe.com/audio-constraints-getusermedia/getSupportedConstraints()" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getSupportedConstraints</a>&nbsp;lists it as supported) to 2 has no effect. There&rsquo;s an&nbsp;<a href="https://bugs.chromium.org/p/chromium/issues/detail?id=731170" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">open issue</a>&nbsp;requesting &amp; tracking&nbsp;<code>channelCount</code>,&nbsp;<code>sampleRate</code>&nbsp;and&nbsp;<code>sampleSize</code>&nbsp;implementations in Chrome.</p>

<p>UPDATE: Chrome 63 has implemented stereo audio recording.</p>

<h3 id="echocancellationnoisesuppressionandautogain">Echo Cancellation, Noise Suppression and Auto Gain</h3>

<p>The&nbsp;<code>echoCancellation</code>&nbsp;constraint works by default on&nbsp;<strong>Chrome</strong>,&nbsp;<strong>Firefox</strong>(<a href="https://stackoverflow.com/a/28911694/813988" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">supported since Firefox 46</a>) and&nbsp;<strong>Safari 11</strong>. It&rsquo;s especially noticeable when&nbsp;<a href="https://addpipe.com/media-recorder-api-demo/" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">recording videos through this unmuted MediaRecorderAPI demo</a>. It&rsquo;s very aggressive on Firefox, much more than Chrome.</p>

<p>Here&rsquo;s the constraint one can use with a user agent that supports it but does not turn it on by default:</p>

<pre class="wp-block-code"><code>{
    audio: {
        echoCancellation: true
    },
    video: true
}</code></pre>

<p><code>noiseSuppression</code>&nbsp;works beautifully in&nbsp;<strong>Firefox</strong>&nbsp;(it&rsquo;s on by default), I could clearly hear the noise picked up by the mic with it turned off:</p>

<pre class="wp-block-code"><code>{
    audio: {
        noiseSuppression: false
    },
    video: true
}</code></pre>

<p><strong>Chrome</strong>&nbsp;definitely applies noise removal even if it does not support the constraint.</p>

<p><strong>Safari 11</strong>&nbsp;does not support noise suppression at this time.</p>

<p><code>autoGainControl</code>&nbsp;is turned off by default on Firefox. Here&rsquo;s how to turn it on:</p>

<pre class="wp-block-code"><code>{
    audio: {
        autoGainControl: true
    },
    video: true
}</code></pre>

<p>After turning it on it clearly lowered the volume when (almost) screaming into the mic.</p>

<p><a href="https://testing.googleblog.com/2015/10/audio-testing-automatic-gain-control.html" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Chrome applies autoGainControl by default</a>, but you can&rsquo;t control it through the&nbsp;<code>autoGainControl</code>&nbsp;constraint, to turn it off you actually need to set&nbsp;<code>echoCancellation</code>&nbsp;to false or use the old</p>

<pre class="wp-block-code"><code>{
    mandatory: {
        googAutoGainControl: false
    }
}</code></pre>

<p>constraint. When testing on macOS the input level notch moved to the left as I moved the microphone towards the sound source (but not when&nbsp;<code>echoCancellation</code> was set to false).</p>
<p><img src="../../../../uploads/1744774836257-screen-shot-2017-11-28-at-17.09" alt="" width="780" height="612"></p>

<h3 id="keywords">Keywords</h3>

<p>The keywords (&nbsp;<code>min</code>,&nbsp;<code>max</code>,&nbsp;<code>exact</code>&nbsp;and&nbsp;<code>ideal</code>) should also work with these audio constraints. Per the spec, in the example above, the&nbsp;<code>channelCount</code>&nbsp;property should be treated as an&nbsp;<code>ideal</code>&nbsp;property, and it should produce the same result as:</p>

<pre class="wp-block-code"><code>{
    audio: {
        channelCount: {
            ideal: 1
        }
    },
    video: true
}</code></pre>

<p>A more complex constraint which requests at least 1 channel audio but preferably 2 would be:</p>

<pre class="wp-block-code"><code>{
    audio: {
        channelCount: {
            ideal: 2,
            min: 1
        }
    },
    video: true
}</code></pre>

<p>A constraint which requests exactly 2 channel audio would be:</p>

<pre class="wp-block-code"><code>{
    audio: {
        channelCount: {
            exact: 2
        }
    },
    video: true
}</code></pre>

<p>The above constraint will result in an&nbsp;<code>OverconstrainedError</code>&nbsp;if the device does not have a dual mic webcam. For more details, check out&nbsp;<a href="../../../../blog/common-getusermedia-errors/">common getUserMedia errors</a>.</p>

The Media Capture and Streams spec governs the cross browser audio options that should be implemented by all browsers and, in it’s latest...

getUserMedia() Audio Constraints - TCMHACK

getUserMedia() Audio Constraints

<p>Once you get&nbsp;<code>getUserMedia()</code>&nbsp;working with&nbsp;<a href="../../../../blog/getusermedia-audio-constraints/">audio</a>&nbsp;and&nbsp;<a href="../../../../blog/getusermedia-video-constraints/">video constraints</a>&nbsp;you immediately start hitting problems like:</p>

<ol>
<li>user has no webcam, just a microphone</li>
<li>user has (accidentally) denied access to the webcam</li>
<li>user plugs in the webcam/microphone after your&nbsp;<code>getUserMedia()</code>&nbsp;code has initialized</li>
<li>the device is already used by another app on Windows</li>
<li>Firefox only: the device is already used by another Firefox tab</li>
<li>Chrome only: the user dismisses the privacy dialog</li>
</ol>

<p>To tackle these situations the&nbsp;<a href="https://www.w3.org/TR/mediacapture-streams/#overconstrainederror-object" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Media Capture and Streams spec</a>&nbsp;that governs&nbsp;<code>getUserMedia()</code>&nbsp;defines several errors that you can look out for in your code (and correctly inform the user).</p>

<p>The table below lists the top 5 errors. They&rsquo;re different between Firefox, which currently follows the spec more closely, and Chrome. On top of these 5, the spec also defines&nbsp;<code>AbortError</code>&nbsp;&amp;&nbsp;<code>SecurityError</code>, but I was never able to trigger them.</p>

<table class="wp-block-table">
<thead>
<tr>
<th>FIREFOX 56</th>
<th>CHROME 62</th>
</tr>
</thead>
<tbody>
<tr>
<td>NotFoundError</td>
<td>DevicesNotFoundError</td>
</tr>
<tr>
<td>NotReadableError</td>
<td>TrackStartError</td>
</tr>
<tr>
<td>OverconstrainedError</td>
<td>ConstraintNotSatisfiedError</td>
</tr>
<tr>
<td>NotAllowedError</td>
<td>PermissionDeniedError</td>
</tr>
</tbody>
</table>

<h3 id="notfounderror">NotFoundError</h3>

<p>This one&rsquo;s&nbsp;<br>very common, it&rsquo;s thrown in these 3 cases:</p>

<ol>
<li>when you&rsquo;re&nbsp;<a href="../../../../blog/getusermedia-video-constraints/">requesting just a video track through constraints</a>&nbsp;but&nbsp;<strong>the user does not have a webcam</strong>.</li>
<li>when you&nbsp;<a href="../../../../blog/getusermedia-audio-constraints/">request just an audio track</a>&nbsp;but&nbsp;<strong>the user does not have a microphone<em>device</em></strong>:</li>
</ol>

<ul>
<li>the computer or device has no sound card or</li>
<li>the computer or device has a sound card but the recording&nbsp;<em>device</em>&nbsp;is disabled because there&rsquo;s no mic plugged in or</li>
<li>the recording&nbsp;<em>device</em> is disabled manually from the OS (can be done on Windows) but that&rsquo;s rare.<br><img src="../../../../uploads/1744775099043-2017-11-14-13_07_53-295x300.png" alt="" width="295" height="300"></li>
</ul>

<ol>
<li>when you&rsquo;re requesting both video and audio tracks but&nbsp;<strong>the user does not have a webcam OR a microphone</strong>&nbsp;(it&rsquo;s enough for one device to be missing for the error to be thrown)</li>
</ol>

<p>Firefox will throw a&nbsp;<code>MediaStreamError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;NotFoundError&rdquo; and the message &ldquo;The object can not be found here&rdquo;.</p>

<p>Chrome will throw a&nbsp;<code>NavigatorUserMediaError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;DevicesNotFoundError&rdquo;.</p>

<h3 id="notreadableerror">NotReadableError</h3>

<p>It most commonly happens on Windows when the browser tries to access the webcam or mic but they&rsquo;re already in use (by Skype, etc.) &ndash;&nbsp;<br>on Windows where processes get exclusive access to the webcam&nbsp;&ndash; but people have also been reporting the error showing up&nbsp;<a href="https://stackoverflow.com/a/36695835/813988" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">when using experimental constraints removed by Chrome</a>&nbsp;or&nbsp;<a href="https://stackoverflow.com/questions/44481163/webrtc-issue-in-chrome-59" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">because of bugs in the Chrome screen recording code</a>. On macOS, where processes share the webcam and microphone, I&rsquo;ve only seen it reported by Firefox.</p>

<p>The&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">Mozilla Developer Network Web Docs explanation covers all these situations</a>:</p>

<blockquote class="wp-block-quote">
<p>Although the user granted permission to use the matching devices, a hardware error occurred at the operating system, browser, or Web page level which prevented access to the device.</p>
</blockquote>

<p>On Windows Firefox will throw a&nbsp;<code>MediaStreamError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;NotReadableError&rdquo; and it&rsquo;s message property set to &ldquo;Failed to allocate videosource&rdquo; when another app (or Firefox tab) is using the webcam or microphone.</p>

<p>On Windows Chrome will throw a&nbsp;<code>NavigatorUserMediaError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;TrackStartError&rdquo;, the non-spec Chrome-specific version, with no message. Different Chrome tabs can share the same webcam.</p>

<p>On macOS it&rsquo;s only thrown by Firefox when another Firefox tab tries to get access to the webcam and mic. On macOs it&rsquo;s paired with the message: &ldquo;Concurrent mic process limit&rdquo;.</p>

<h3 id="overconstrainederror">OverconstrainedError</h3>

<blockquote class="wp-block-quote">
<p>The specified constraints resulted in no candidate devices which met the criteria requested. The error is an object of type&nbsp;<code>OverconstrainedError</code>, and has a&nbsp;<code>constraint</code>&nbsp;property whose string value is the name of a constraint which was impossible to meet, and a&nbsp;<code>message</code>&nbsp;property containing a human-readable string explaining the problem.</p>
</blockquote>

<p>It&rsquo;s thrown when you&rsquo;re requesting a constraint that can not be satisfied by the available hardware, for example a high frame rate or high resolution requested using the&nbsp;<code>min</code>&nbsp;or&nbsp;<code>exact</code>&nbsp;keywords.</p>

<p>Firefox will throw a&nbsp;<code>MediaStreamError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;OverconstrainedError&rdquo; .</p>

<p>Chrome will throw a&nbsp;<code>NavigatorUserMediaError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;ConstraintNotSatisfiedError&rdquo;, the non-spec Chrome-specific version.</p>

<p>Chrome &amp; Firefox will return the requested resolution or the closest one when using&nbsp;<code>ideal</code>&nbsp;values but if you start using the&nbsp;<code>min</code>&nbsp;keyword with high values or the&nbsp;<code>exact</code>keyword with unsupported values you will immediately trigger the error.</p>

<p>The error object will also mention the constraint that could not be satisfied through the&nbsp;<code>constraintName</code>&nbsp;property and the&nbsp;<code>message</code> &ldquo;Constraints could be not satisfied.&rdquo;.</p>
<p><img src="../../../../uploads/1744775185524-screen-shot-2017-11-21-at-11.22" alt="" width="1024" height="293"></p>

<h3 id="notallowederror">NotAllowedError</h3>

<p>Is thrown when the user denies (or has previously denied) access to the webcam or microphone.</p>

<p>Firefox will throw a&nbsp;<code>MediaStreamError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;NotAllowedError&rdquo; and the message &ldquo;The request is not allowed by the user agent or the platform in the current context&rdquo;.</p>

<p>Chrome will throw a&nbsp;<code>NavigatorUserMediaError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code> property set to &ldquo;PermissionDeniedError&rdquo;.</p>
<p><img src="../../../../uploads/1744775241851-screen-shot-2017-11-27-at-16.07" alt="" width="538" height="328"></p>

<h3 id="typeerror">TypeError</h3>

<p>It&rsquo;s thrown when the constraints object passed to&nbsp;<code>getUserMedia()</code>&nbsp;is empty or has all tracks (audio, video or both) set to false.</p>

<p>Firefox will throw a&nbsp;<code>MediaStreamError</code>&nbsp;with it&rsquo;s&nbsp;<code>name</code>&nbsp;property set to &ldquo;TypeError&rdquo; and the message &ldquo;audio and/or video is required&rdquo;.</p>

<p>Chrome will throw a &ldquo;TypeError: Failed to execute &lsquo;getUserMedia&rsquo; on &lsquo;MediaDevices&rsquo;: At least one of audio and video must be requested&rdquo;.</p>

<h3 id="permissiondismissederror">PermissionDismissedError</h3>

<p>It&rsquo;s thrown by Chrome when the user closes the privacy dialog asking for mic and webcam access.</p>
<p><img src="../../../../uploads/1744775282357-screen-shot-2017-11-27-at-16.10" alt="" width="431" height="234"></p>

<p>Dismissing the dialog is only possible on Chrome so there&rsquo;s no equivalent error on other browsers.&nbsp;<strong>It&rsquo;s not spec compliant</strong>&nbsp;so the error might be removed in Chrome 64 in the&nbsp;<a href="https://bugs.chromium.org/p/chromium/issues/detail?id=721412" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">move towards spec compliant errors</a>.</p>

<h3 id="handlingtheseerrors">Handling these errors</h3>

<p>Handling these errors is quite simple when using the newer&nbsp;<a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">promise based&nbsp;</a><code><a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">getUserMedia()</a></code>. You can use the code below or&nbsp;<a href="https://codepen.io/naicuoctavian/pen/wPeZWO" target="_blank" rel="noreferrer noopener" aria-label=" (opens in a new tab)">this code pen.</a></p>

<pre class="wp-block-code"><code>var constraints = {
    video: false,
    audio: false
}
navigator.mediaDevices.getUserMedia(constraints).then(function success(stream) {
    /* do stuff */
}).catch(function(err) {
    //log to console first 
    console.log(err); /* handle the error */
    if (err.name == "NotFoundError" || err.name == "DevicesNotFoundError") {
        //required track is missing 
    } else if (err.name == "NotReadableError" || err.name == "TrackStartError") {
        //webcam or mic are already in use 
    } else if (err.name == "OverconstrainedError" || err.name == "ConstraintNotSatisfiedError") {
        //constraints can not be satisfied by avb. devices 
    } else if (err.name == "NotAllowedError" || err.name == "PermissionDeniedError") {
        //permission denied in browser 
    } else if (err.name == "TypeError" || err.name == "TypeError") {
        //empty constraints object 
    } else {
        //other errors 
    }
});</code></pre>

<p>The code starts out with false for both the video and audio track to immediately trigger the&nbsp;<code>TypeError</code>&nbsp;.</p>

Once you get getUserMedia() working with audio and video constraints you immediately start hitting problems like: user has no webcam, just a m...

getUserMedia() Video Constraints

getUserMedia() Audio Constraints

Common getUserMedia() Errors