Video Constraints: Setting Preferred Resolution and Frame Rate

Vonage Video API allows publishers to optimize video streams by setting preferred constraints on the video resolution and frame rate. These constraints help manage bandwidth usage, accommodate device capabilities, and deliver a tailored user experience to subscribers.

This guide covers how to use the preferredResolution and preferredFrameRate APIs for publishers.

Overview

When publishing a video stream, you may want to dynamically adjust the video quality for various reasons: bandwidth savings, aligning with UI requirements, or restricting resource consumption for certain subscriber roles (such as thumbnails or low-motion screens). Vonage's publisher API exposes methods that let you adjust the preferred resolution and frame rate for your video tracks. These constraints are enforced on the video input device using standard WebRTC APIs for optimal results, but they ultimately influence what all subscribers will receive.

Controlling Video Resolution and Frame Rate

The publisher can specify:

• Preferred resolution: The desired width and height (in pixels) for the video stream.
• Preferred frame rate: The desired number of frames per second (fps) for the video stream.

You can control these dynamically using the following methods after the publisher is initialized:

// Set preferred resolution (width x height)
await publisher.setPreferredResolution({ width: 640, height: 360 });

// Set preferred frame rate
await publisher.setPreferredFrameRate(15);

Setting Preferred Resolution

Method: publisher.setPreferredResolution(preferredResolution)

• preferredResolution is an object with width and height properties (both positive integers, in pixels).
• The resolution cannot be greater than the initial publishing resolution. For example, if you published at 640×480, you can't set a higher resolution than that.

Typical use:

publisher.setPreferredResolution({ width: 320, height: 240 });

Validations:

• Must be called on a publisher that is capturing video (publishVideo: true).
• Both width and height must be positive integers.
• The resolution cannot be greater than the initial publishing resolution.

Error Cases:

• Throws if called on an audio-only publisher or if input values are invalid.

Setting Preferred Frame Rate

Method: publisher.setPreferredFrameRate(frameRate)

• frameRate must be an integer greater than or equal to 1.

Typical use:

publisher.setPreferredFrameRate(15);

Validations:

• Must be called on a publisher with an active video track.
• Frame rate must be a valid integer ≥ 1.

Error Cases:

• Throws if called on an audio-only publisher or if frameRate is invalid.

Best Practices

• Set constraints according to both UI requirements and the experience you want to deliver to all subscribers. For example, a small video element may use lower resolution and frame rate, but consider how this affects each subscriber's view.
• Do not set a preferred resolution higher than the initial publishing resolution negotiated during publisher start.
• Choose frame rates appropriate for the content, for example:
  • 5 fps for static slides, dashboards, screens with very little motion, or minimal bandwidth usage.
  • 15 fps for low-motion screens or bandwidth-sensitive scenarios
  • 30 fps for full-motion video or high-quality requirements
• Bandwidth and network factors: Remember, what you set as constraints can be further limited by real-time network estimations and backend server capabilities. The actual properties of the video received by subscribers may be lower than what you requested.
• Preferred resolution and frame rate are currently only available in the JavaScript SDK. There is no timeline for adding this feature to other SDKs.

Additional Notes

• The constraints you set influence all subscribers to your stream, not just the local UI.
• The network and backend will ultimately determine the real video quality delivered, based on current connection health and available bandwidth.
• These APIs are only available using the JavaScript SDK; other SDKs do not support dynamic video constraint changes at this time.

Additional Resources

• Publishing streams
• Publisher reference docs
• WebRTC MediaTrack Constraints