Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalYou can dynamically control the maximum bitrate that a publisher can use for camera video streams.
This guide shows how to configure video bitrate settings, how to interact with different presets, how to set raw bitrates, and best practices for using the API effectively.
This topic includes the following sections:
You can dynamically set the maximum bitrate a publisher can use when encoding media. The video encoder then adjusts the bitrate dynamically, using a value within the allowed range, from a minimum threshold to the maximum bitrate set, based on network conditions and other constraints.
Setting the maximum bitrate can help to reduce bandwidth consumption when a user is connecting from a metered connection. Be sure to read the Limitations below.
There are some important limitations to be aware of:
Network conditions — The actual bitrate achieved on the network may be lower than the value set, due to real-time network estimations, bandwidth fluctuations, and backend limitations.
Out-of-bounds values — If you provide a bitrate value outside the valid range, the SDK may ignore the request or return an error.
The API offers video bitrate presets that simplify reducing video quality without needing to worry about codec and session settings. These presets are designed for common use cases like video conferencing and are tailored to 480p, 540p, 720p, and 1080p resolutions.
The available presets are:
DEFAULT — The default SDK bitrate setting that offers a balanced visual experience for video streams.
BW_SAVER — A medium-quality setting for video conferencing that reduces the bitrate to save bandwidth.
EXTRA_BW_SAVER — The lowest bitrate for essential video communication, offering low video quality but minimal bandwidth usage.
Please note that the exact bitrate values used when dealing with presets is implementation-specific, and depends on the negotiated codec and the media mode (relayed or routed). The Video API client SDKs include methods to set and get the bitrate preset.
If the predefined bitrate presets do not meet your needs, you can set a custom raw bitrate value. This allows you to define specific bitrate limits within a range, from 5,000 bps to 10,000,000 bps. Please note that the value only applies to the encoder bitrate, so network overhead still applies on top of the chosen value.
The Vonage Video API client SDKs include methods to set the raw bitrate value and to retrieve it. Until a raw bitrate is set, or until only presets are set, the getter returns 0 (except for the JS SDK, in which the returned value is undefined). Once a raw bitrate is set, the bitrate preset getter returns 'custom', indicating that a custom value has been applied. However, do not use the preset 'custom' in the setter -- just set the specific bitrate number to use as a maximum value.
Changing the maximum bitrate when scalable VP8 is used, triggers additional efficiency -- the client SDK dynamically activates or deactivates the encoding layers based on the available bitrate to ensure the video stream is as efficient as possible. This process adapts the resolution at which the publisher is publishing.
The following notes apply to the preset when using VP8:
DEFAULT — This preset utilizes all available encoding layers. For a typical stream, this includes up to three layers (low, medium, and high).
BW_SAVER — This preset only uses the first two encoding layers (low and medium quality). This is designed to save bandwidth, making it suitable for scenarios like video conferencing where high video quality might not be as critical.
EXTRA_BW_SAVER — This preset further reduces the bitrate, using only the base (lowest) encoding layer. This is the most bandwidth-efficient mode, providing the bare minimum quality for meaningful video communication.
When you set a raw bitrate value, if the provided bitrate is insufficient to maintain certain encoding layers, the SDK automatically turns off the higher layers. For example, if the bitrate is too low for the medium or high-quality layers, those layers are discarded, and only the base layer is transmitted.
If a new provided bitrate is high enough to maintain more encoding layers, the SDK reactivates the higher encoding layers, progressively restoring the video quality by adding back the medium and high layers.
This mechanism ensures that the video stream remains as efficient as possible, maximizing the use of the available bandwidth without compromising the user experience.
At the start of a session, a publisher uses the DEFAULT preset, which provides full video quality. At this particular stage of the session, let's assume it negotiated the VP8 non-scalable codec. However, after a network change to a metered connection (for example, cellular), you may lower the publishing bandwidth using the BW_SAVER preset. When using a preset for the publisher's maximum bitrate, the client SDK makes sure that the quality level stays the same regardless of any event. When the network switches back to an unlimited connection, you can restore the default by setting the DEFAULT preset.
You can also set the raw bitrate value to set a bandwidth upper threshold.
For details for each client SDK, see the following:
To ensure the best performance and optimal bandwidth usage, follow these best practices:
Use predefined bitrate presets — When possible, use the predefined bitrate presets (DEFAULT, BW_SAVER, EXTRA_BW_SAVER) to manage video quality. These presets are tailored for common scenarios like video conferencing, ensuring that video quality is balanced with bandwidth efficiency. More importantly, they abstract codec details and media modes.
Be cautious with custom bitrate settings — While custom bitrate settings give you more control, their usage is tied to codec details that may change during the WebRTC negotiation phase. We recomment to use them sparingly, and only when an hard threshold on the bitrate is needed.
Don't apply custom bitrates or presets to screen-sharing streams — Screen-sharing stream encoding differs from camera stream encoding. Using the maximum bitrate API to limit a screen-sharing stream may degrade the quality without offering any bandwidth improvement.
