Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalOnce you have initialized a Publisher, you can control the preferred resolution and frame rate of the outgoing video track. This lets you optimize bandwidth and CPU usage for different UI sizes (thumbnails, tiles, full screen) and subscriber devices.
This topic includes the following sections:
The Publisher can advertise a preferred resolution and frame rate for its video track: the SDK applies constraints to the capture device and outbound track. Subscribers benefit from lower bandwidth and CPU when the publisher sets smaller sizes or lower frame rates for small UI targets. Note that delivered quality can be further adjusted by device capabilities and network conditions.
Call publisher.setPreferredResolution(preferredResolution) to set the preferred pixel dimensions:
await publisher.setPreferredResolution({ width: 640, height: 360 });
preferredResolution is an object: { width: number, height: number }.publishVideo: true).Throws an error if:
width or height is not a positive integer.try {
// If the initial publish was 640x480, this will throw:
await publisher.setPreferredResolution({ width: 1920, height: 1080 });
} catch (error) {
console.error('Failed to set preferred resolution:', error.message);
}
Call publisher.setPreferredFrameRate(frameRate) to set a preferred frames-per-second value:
await publisher.setPreferredFrameRate(15);
frameRate must be a positive integer (≥ 1).Throws an error if:
frameRate is not a valid integer ≥ 1.Preferred constraints influence the outbound video track for all subscribers to the stream. However, the final delivered resolution and frame rate may be lower due to:
OT.initPublisher() (for example via resolution and frameRate).
For subscribers, you can omit these settings or use preferredResolution: 'auto' when calling
Session.subscribe().
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.
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:
// Lower quality for mobile users
if (isMobileUser) {
publisher.setPreferredResolution({ width: 320, height: 180 });
publisher.setPreferredFrameRate(15);
}
// Higher quality for desktop
if (isDesktopUser) {
publisher.setPreferredResolution({ width: 1280, height: 720 });
publisher.setPreferredFrameRate(30);
}
// Error when using resolution above initial publish
try {
await publisher.setPreferredResolution({ width: 1920, height: 1080 }); // If initial was 640x480, throws error
} catch (error) {
console.error(error.message);
}
// Debugging: Current track settings
const videoTrack = publisher.getVideoSource().track;
const { width, height, frameRate } = videoTrack.getSettings();
console.log('Current resolution:', width, 'x', height);
console.log('Current frame rate:', frameRate);
Wrap calls in try/catch and surface user-friendly messages when constraints are invalid
or the environment cannot satisfy them.
async function setPublisherQuality(publisher, preferredResolution, preferredFrameRate) {
try {
await publisher.setPreferredResolution(preferredResolution);
await publisher.setPreferredFrameRate(preferredFrameRate);
} catch (err) {
showMessage('Unable to apply video constraints. Check your device and network.');
console.error(err);
}
}
If the network is constrained, the media pipeline may lower the delivered resolution or frame rate regardless of preferred settings. Consider implementing UI indicators for reduced quality modes.