Publisher Max Bitrate

This topic includes details on setting the maximum video bitrate using the Vonage Video Linux client SDK:

For an overview of the publisher maximum bitrate API, see this topic.

Setting and retrieving a preset

The otc_video_bitrate_preset enum, in the publisher.h header, includes preset values:

OTC_VIDEO_BITRATE_PRESET_DEFAULT
OTC_VIDEO_BITRATE_PRESET_BW_SAVER
OTC_VIDEO_BITRATE_PRESET_EXTRA_BW_SAVER
OTC_VIDEO_BITRATE_PRESET_CUSTOM

See Video bitrate presets for details on these presets.

To retrieve the currently configured video bitrate preset for a given publisher, call the otc_publisher_get_video_bitrate_preset() function:

enum otc_video_bitrate_preset preset = otc_publisher_get_video_bitrate_preset(publisher);
if (preset == OTC_VIDEO_BITRATE_PRESET_BW_SAVER) {
    printf("The publisher is using the BW_SAVER preset.\n");
}

To set a preset, call the otc_publisher_set_video_bitrate_preset() function. This function includes two parameters:

publisher — A pointer to the otc_publisher instance.
preset — A value from otc_video_bitrate_preset. Do not use OTC_VIDEO_BITRATE_PRESET_CUSTOM.

The function returns one of these values:

OTC_SUCCESS — The preset was successfully applied.
OTC_ERROR_INVALID_PARAMETER — The provided publisher is NULL or the preset is invalid.

Example:

otc_status status = otc_publisher_set_video_bitrate_preset(publisher, OTC_VIDEO_BITRATE_PRESET_BW_SAVER);
if (status == OTC_SUCCESS) {
    printf("Bitrate preset successfully set to BW_SAVER.\n");
} else {
    printf("Failed to set bitrate preset.\n");
}

Setting and retrieving a raw bitrate value

If the predefined presets are not suitable, you can manually set a custom raw bitrate value.

To get the maximum video bitrate currently set for a publisher, call the otc_publisher_get_max_video_bitrate() function. This returns the currently set maximum bitrate (in bits per second). If no custom value is set, the function returns 0.

Example:

int max_bitrate = otc_publisher_get_max_video_bitrate(publisher);
printf("Current max video bitrate: %d bps\n", max_bitrate);

To set a custom maximum bitrate value (instead of a preset), use the otc_publisher_set_max_video_bitrate() function. This function has the following parameters:

publisher — A pointer to an existing otc_publisher instance.
bitrate_bps — The desired maximum bitrate (in bits per second). Must be between 5,000 and 10,000,000.

The function returns one of the following values:

OTC_SUCCESS — The bitrate was successfully applied.
OTC_ERROR_INVALID_PARAMETER — The publisher pointer is NULL, or bitrate_bps is out of range.

Example:

int new_bitrate = 300000; // 300 kbps
otc_status status = otc_publisher_set_max_video_bitrate(publisher, new_bitrate);
if (status == OTC_SUCCESS) {
    printf("Successfully set max video bitrate to %d bps.\n", new_bitrate);
} else {
    printf("Failed to set max video bitrate.\n");
}

See Setting raw bitrate values for more details.

Special cases

Setting the raw bitrate value to 0 removes any previously set bitrate limitation, reverting to the default behavior.

const int zero_bitrate = 0;  // no limitations
const int new_bitrate = 300000; // 300 kbps
otc_status status = otc_publisher_set_max_video_bitrate(publisher, new_bitrate);

if (status == OTC_SUCCESS) {
  assert(otc_publisher_get_max_video_bitrate(publisher) == new_bitrate);
}

status = otc_publisher_set_max_video_bitrate(publisher, zero_bitrate);
if (status == OTC_SUCCESS) {
  assert(otc_publisher_get_max_video_bitrate(publisher) == zero_bitrate);
}

Calling the (otc_publisher_get_video_bitrate_preset()) function after setting a custom bitrate returns OTC_VIDEO_BITRATE_PRESET_CUSTOM.

const int new_bitrate = 1000000; // 1 mbps
otc_status status = otc_publisher_set_max_video_bitrate(publisher, new_bitrate);

if (status == OTC_SUCCESS) {
  assert(otc_publisher_get_video_bitrate_preset(publisher) == OTC_VIDEO_BITRATE_PRESET_CUSTOM);
}

status = otc_publisher_set_max_video_bitrate(publisher, zero_bitrate);
if (status == OTC_SUCCESS) {
  assert(otc_publisher_get_video_bitrate_preset(publisher) == OTC_VIDEO_BITRATE_PRESET_DEFAULT);
}

The raw bitrate getter returns 0 when the publisher is using a preset.

// Assume all the statuses are OTC_SUCCESS

int bitrate_bps = otc_publisher_get_max_video_bitrate(publisher);
assert(bitrate_bps == 0);

otc_publisher_set_video_bitrate_preset(publisher, OTC_VIDEO_BITRATE_PRESET_BW_SAVER);
bitrate_bps = otc_publisher_get_max_video_bitrate(publisher);
assert(bitrate_bps == 0);

otc_publisher_set_video_bitrate_preset(publisher, OTC_VIDEO_BITRATE_PRESET_EXTRA_BW_SAVER);
bitrate_bps = otc_publisher_get_max_video_bitrate(publisher);
assert(bitrate_bps == 0);

otc_publisher_set_max_video_bitrate(publisher, 200000);
bitrate_bps = otc_publisher_get_max_video_bitrate(publisher);
assert(bitrate_bps == 200000);

otc_publisher_set_video_bitrate_preset(publisher, OTC_VIDEO_BITRATE_PRESET_DEFAULT);
bitrate_bps = otc_publisher_get_max_video_bitrate(publisher);
assert(bitrate_bps == 0);