Custom getUserMedia and getDisplayMedia Constraints Now Supported

We’ve been exploring ways to provide more control over the video and audio recording quality directly from the embed code without having to create & host a custom XML file & configure CORS.

Starting today, a new update to the recording client makes it possible to pass custom audio and video constraints to getUserMedia() and screen recording constraints to getDisplayMedia() via two new embed code options:

• pipe-gumconstraints will enable you to pass custom getUserMedia() constraints as a JSON string.
• pipe-gdmconstraints will enable you to pass custom getDisplayMedia() constraints as a JSON string.

Benefits

Until this update, the only way to request a custom video resolution or a higher/lower frame rate was by creating and hosting a custom XML quality profile file, then referencing it using the pipe-qualityurl parameter.

Using these new embed code options has several benefits over the existing way to control video settings:

1. You can change the resolution, fps, etc., directly from the embed code, inline, without having to host and configure CORS for a separate .xml file just to make simple changes.
2. You have access to all possible audio, video, and screen capture constraints, including new ones, experimental ones, or constraints supported by only one browser.
3. You can overwrite browser defaults.
4. Making an HTTP request for an .xml video quality profile is overkill and expensive when it contains just three numbers (width, height, fps); For the standard video quality profiles, this request was eliminated by hardcoding the values in pipe.js.

Immediate Use Cases

Some of the use cases that will immediately benefit from custom constraints:

1. Audio recording with no processing on the audio (for recording instruments; by default, most browsers will apply noise suppression)
2. Video recording with specific aspect ratios (16:9, 4:3, portrait, etc.) in situations where the aspect ratio is more important than the resolution (TV broadcasts, mobile content).
3. Defaulting to the front or back facing camera on mobile devices using the facingMode constraint.
4. Access to the privacy-preserving screen sharing controls when screen recording.
5. Capturing 60fps or more from capable web cameras is now easy to set up.
6. Excluding monitor/fullscreen surfaces from screen recording use cases to protect companies from leakage of private information through employee-error (source).
7. Capturing specific devices on computers/kiosk set-ups with multiple devices using the deviceId constraint.

All these use cases are covered with examples in our documentation.

Here’s a quick example using pipe-gumconstraints to set a specific resolution and frame rate:

var pipeParams = {
  // ...
  gumconstraints: {"video": {"width": 1920, "height": 1080, "frameRate": 60}}
};

And here’s an example using pipe-gdmconstraints to configure screen capture options:

var pipeParams = {
  // ...
  gdmconstraints: { "video": { "displaySurface": "window" }, "audio": true }
};

Both parameters accept a JSON string and can be used to define custom constraints.

New JavaScript Methods To Update Constraints

To make things even more flexible, we’ve also introduced two new JavaScript Control API methods:

• updateGUMConstraints(newConstraints) – Update the getUserMedia() constraints.
• updateGDMConstraints(newConstraints) – Update the getDisplayMedia() constraints

These will just update the constraints. They will not apply them. They will be applied with the next function call, so in the case of getUserMedia, when changing between devices. They make sense when called before the user initializes the recorder. These will be useful for implementations where the recording settings may change based on user input (ability to select recording resolution) or device capabilities.

Beta Feature

The ability to specify custom constraints and to update them through the new JS Control API functions will remain in beta for some time. There's a risk that with exact constraints, we will see a bunch of OverconstrainedErrors in our recording client that might not be properly handled at the recording client or documentation level.

Live Demos

Our online voice recorder has been set up to disable any processing on the audio. Most browsers default to processing the audio and removing the noise, echo and controlling the audio level.

Our online video recorder has been set up to request 60 fps from the camera.

Updated Documentation

We've updated our documentation to reflect the new capabilities. The audio and video quality, screen recording, embed code options, and JS Control API docs have all ben updated.

Next Steps

Moving forward, we plan on allowing more control over the video codec used by the browser (recent versions of Safari and Chrome support HEVC and AV1) and the ability to apply new constraints right away.