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

For conceptual information, see the audio fallback overview.

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 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 Media Router). Subscriber audio fallback is enabled by default (in routed sessions) for streams with a camera video source.

Publisher 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;

Subscriber audio fallback events

When subscriber audio fallback is enabled, 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 the Subscriber determines 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 the Subscriber determines 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 the Subscriber determines 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 the Subscriber 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_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;