Use the audio fallback API to dynamically prioritize audio in response to network quality.

Notes: The otc_publisher_set_audio_fallback_enabled() and otc_publisher_get_audio_fallback_enabled() functions will be deprecated. Please use the otc_publisher_settings_set_publisher_audio_fallback_enabled and otc_publisher_settings_set_subscriber_audio_fallback_enabled instead.

Enabling and disabling audio-only fallback

To enable publisher audio fallback, call the otc_publisher_settings_set_publisher_audio_fallback_enabled() function.

// Enable publisher audio fallback
otc_publisher_settings publisher_settings = otc_publisher_settings_new();
otc_publisher_settings_set_publisher_audio_fallback_enabled(publisher_settings, OTC_TRUE);
otc_publisher_callbacks publisher_callbacks = {0};
struct otc_publisher* publisher = otc_publisher_new_with_settings(&publisher_callbacks, publisher_settings);

// Enable publisher audio fallback and disable subscriber audio fallback
otc_publisher_settings publisher_settings = otc_publisher_settings_new();
otc_publisher_settings_set_publisher_audio_fallback_enabled(publisher_settings, OTC_TRUE);
otc_publisher_settings_set_subscriber_audio_fallback_enabled(publisher_settings, OTC_FALSE);
otc_publisher_callbacks publisher_callbacks = {0};
struct otc_publisher* publisher = otc_publisher_new_with_settings(&publisher_callbacks, publisher_settings);

// Enable subscriber audio fallback and disable publisher audio fallback
otc_publisher_settings publisher_settings = otc_publisher_settings_new();
otc_publisher_settings_set_publisher_audio_fallback_enabled(publisher_settings, OTC_FALSE);
otc_publisher_settings_set_subscriber_audio_fallback_enabled(publisher_settings, OTC_TRUE);
otc_publisher_callbacks publisher_callbacks = {0};
struct otc_publisher* publisher = otc_publisher_new_with_settings(&publisher_callbacks, publisher_settings);

To enable and disable subscriber audio fallback (for all subscribers to the stream), call the otc_publisher_settings_set_subscriber_audio_fallback_enabled() function. Subscriber audio fallback is only supported in routed sessions (sessions that use the Vonage Video Media Router). Subscriber audio fallback is enabled by default (in routed sessions) for streams with a camera video source.

Audio fallback events

When publisher audio fallback is enabled, callback functions in the otc_publisher_callbacks struct are invoked for publisher audio fallback-related events:

  • otc_publisher_callbacks.on_video_disable_warning() — Called when the Publisher determines that the stream quality has degraded and the video will be disabled if the quality degrades more.

  • otc_publisher_callbacks.on_video_disable_warning_lifted() — Called when the Publisher determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk.

  • otc_publisher_callbacks.on_video_disabled() — Called when the Publisher determines that the stream quality has degraded and the outgoing video transport has been disabled. Note: while the video is disabled, the Publisher still displays the publisher video (such as the camera image) in the publishing client's UI.

  • otc_publisher_callbacks.on_video_enabled() — Called with reason "quality" when the Publisher determines that the stream quality has improved and outgoing video transport has been re-enabled. For example the following code handles the related events (so that you can provide your own user interface notifications):

static void on_video_disable_warning(otc_publisher* publisher,
                                     void* user_data) {
  // Custom action — for example, add custom UI notification
}

static void on_video_disable_warning_lifted(otc_publisher* publisher,
                                            void* user_data) {
  // Custom action — for example, remove custom UI notification
}

static void on_video_disabled(otc_publisher* publisher,
                              void* user_data,
                              enum otc_video_reason reason) {
  // Custom action — for example, add custom UI notification
}

static void on_video_enabled(otc_publisher* publisher,
                             void* user_data,
                             enum otc_video_reason reason) {
  // Custom action — for example, remove custom UI notification
}


struct otc_publisher_callbacks publisher_callbacks = {0};
publisher_callbacks.on_video_disable_warning = on_video_disable_warning;
publisher_callbacks.on_video_disable_warning_lifted = on_video_disable_warning_lifted;
publisher_callbacks.on_video_disabled = on_video_disabled;
publisher_callbacks.on_video_enabled = on_video_enabled;

From the subscriber’s perspective, the following events indicate that audio fallback has occurred. Although these events are tied to the subscriber, they can occur both due to subscriber audio fallback and as a consequence of publisher audio fallback. In other words, the difference between publisher and subscriber audio fallback is that, in the publisher case, the publishing client may trigger the audio fallback based on its own stream degradation, which is why additional publisher-side events are dispatched. For subscriber audio fallback, the Vonage Video Media Router assesses network degradation affecting the subscriber. In both cases, upon publisher or subscriber audio fallback, subscriber events are always dispatched to indicate that audio fallback has occurred for the receiver.

When audio fallback occurs, the callback functions in the otc_subscriber_callbacks struct are invoked for subscriber audio fallback-related events:

  • otc_subscriber_callbacks.on_video_disable_warning() — Called when it is determined that the stream quality has degraded and the video will be disabled if the quality degrades more.
  • otc_subscriber_callbacks.on_video_disable_warning_lifted() — Called when it is determined that the stream quality has improved to the point at which the video being disabled is not an immediate risk.
  • otc_subscriber_callbacks.on_video_disabled() — Called when it is determined that the stream quality has degraded and the outgoing video transport has been disabled. Note: while the video is disabled, the Subscriber still displays the subscriber video (such as the camera image) in the publishing client's UI.
  • otc_subscriber_callbacks.on_video_enabled() — Called with reason "quality" when it is determined that the stream quality has improved and outgoing video transport has been re-enabled.

For example the following code handles the related events (so that you can provide your own user interface notifications):

static void on_video_disable_warning(otc_subscriber* subscriber,
                                     void* user_data) {
  // Custom action — for example, add custom UI notification
}

static void on_video_disable_warning_lifted(otc_subscriber* subscriber,
                                            void* user_data) {
  // Custom action — for example, remove custom UI notification
}

static void on_video_disabled(otc_subscriber* subscriber,
                              void* user_data,
                              enum otc_video_reason reason) {
  // Custom action — for example, add custom UI notification
}

static void on_video_enabled(otc_subscriber* subscriber,
                             void* user_data,
                             enum otc_video_reason reason) {
  // Custom action — for example, remove custom UI notification
}

struct otc_subscriber_callbacks subscriber_callbacks = {0};
subscriber_callbacks.on_video_disable_warning = on_video_disable_warning;
subscriber_callbacks.on_video_disable_warning_lifted = on_video_disable_warning_lifted;
subscriber_callbacks.on_video_disabled = on_video_disabled;
subscriber_callbacks.on_video_enabled = on_video_enabled;