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

• If you know the ideal resolution and frame rate in advance, set them when creating the Publisher using OT.initPublisher() (for example via resolution and frameRate). For subscribers, you can omit these settings or use preferredResolution: 'auto' when calling Session.subscribe().
• Use the Subscriber APIs (subscriber.setPreferredResolution() / subscriber.setPreferredFrameRate()) to change how a single subscriber receives/decodes/renders a stream. This only affects that subscriber, and does not change what the Publisher sends or what other subscribers receive.
• Use the Publisher APIs (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) to change what the Publisher sends. This affects all subscribers to that stream, which will automatically receive the updated settings. You may want to reduce the publisher resolution using the preferredResolution method in several cases, such as:
  • When you notice that the publisher device is struggling, whether due to CPU limitations or network issues, and you want to alleviate the strain more quickly than the WebRTC stack typically would.
  • If the device is running low on battery and you want to minimize power consumption to extend the call duration.
  • When you initiate screen sharing or start additional publishers from the same device and need to free up computational resources for those activities.
• Publisher preferred resolution/frame rate can never exceed the values specified when initializing the Publisher. Initialize the Publisher with the maximum resolution and frame rate you might need, then reduce or increase dynamically within those limits based on your use case.
• 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
• Network conditions may prevent the SDK from maintaining your preferred resolution and frame rate. Treat preferred values as targets: if bandwidth or CPU becomes constrained, the SDK may automatically reduce the published/subscribed video quality (for example, a 1080p preference may temporarily drop to a lower resolution during poor network conditions).
• 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