The getUserMedia spec is evolving heavily as the standardization group is closing in on WebRTC version 1.0. This blog post was written based on the spec in beginning of June 2016.
Getting access to user media, ie. camera and microphone, is one of the first things a WebRTC application needs to do before it can function as intended. Failing to get access to a user’s media is problematic, as the user would only be able to see and listen to other people in the conference. To get access to the devices, the WebRTC application needs to implement the getUserMedia (gUM) API. In some cases, gUM errors can account for up to 14% of all the failures in a WebRTC service.
A request for camera permission in Opera browser in OS X. You can test it yourself at WebRTC samples on Github.
In this blog post we will go through in more detail the different error types that we have observed and how to handle or fix them.
getUserMedia API execution and error codes
The gUM API is executed in three steps which starts with showing a permission dialog to the user. If no devices are available the gUM API throws a failure error. Further, if the device is found, media source constraints are applied. Next, if the device is unable to apply the constraints, the gUM API will throw an overconstrained error.
At the beginning of the year, the spec changed to map most of the WebRTC gUM errors to the DOMExceptions:
- SourceAvailableError to a NotReadableError DOMException, with the error message: “The I/O read operation failed.”
- PermissionDeniedError to a SecurityError DOMException, with the error message: “The operation is insecure.”
- NotSupportedError with the error message: “The operation is not supported.”
- NotFoundError with the error message: “The object can not be found here.
- AbortError with the error message: “The operation was aborted.”
- Overconstrained Error returns an object containing the incorrect or invalid constraint name and the associated error message. Typically, stating why the constraint was not satisfied.
Device related errors
A media device can disappear, for example, in a case where it takes a long time to allow permission for a device, and in the meantime the device, for example a USB camera, has been disconnected from the computer. In this case the browser throws a NotFoundError for the device.
Device not found error thrown when a microphone was detached before allowing access
Device unavailable occurs when the resource is already reserved. This can happen, for example, if another application is using a camera when the WebRTC application attempts to gain access to the camera as well.
Constraints related errors
Accessing the media device can also fail when the device is unable to satisfy the settings requested by the application (constraints). An application sends the device a range for each setting, and the gUM API throws an error if the device cannot deliver within the given range. For example, a VGA camera, which has a maximum width of 640 pixels and height of 480 pixels, cannot deliver Full HD quality (minimum 1920 x 1080).
| Microphone constraints | Camera constraints |
|---|---|
| Volume | Width |
| Sample rate and size | Height |
| Latency | Aspect ratio |
| Echo cancellation | Frame rate |
| Channel count |
Permission related errors
To gain access to a user’s media the WebRTC application needs to request permission for camera and/or microphone. Platforms have different conventions but the basic rule is that on desktop camera and microphone permission can be granted in the same request and on mobile each permission requires its own dialogue.
If a user blocks media access, the browser creates a MediaConfigError, which is logged to callstats.io. The error is listed in the failed connections table in the conference timeline view, which is displayed below.
User did not allow access for camera device
Furthermore, if the permission has been blocked, the app cannot request the permission again with a popup window but the user needs to change the permission in the settings. When a user doesn’t allow access to media they usually have a good reason for it. In some cases the permission requests asks permission for both, camera and microphone, and the user would only like to grant access to either one. Splitting up the permission request could lead to more users allowing access to their media.
Hangouts requesting access to camera and microphone separately on iOS
In some cases the users might feel that they don’t understand why media access is requested. Furthermore, in some cases the request might appear too early for the user. For both cases a good solution is to explain why the access is requested and what will happen once the permission has been granted. Also, delaying the permission request as late as possible in the process should ensure that the user actually wants to take part in a conference or make a call, thus wants to grant media access.
If you are looking to understand what kind of errors happen in your WebRTC app, sign up for a free callstats.io account or schedule a personal demo of the product with Binoy on our contact page.
