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

For conceptual information, see the audio fallback overview.

Enabling and disabling audio-only fallback

When initializing the Publisher object, set the audioFallback property of the option you pass into the OT.initPublisher() method:

// Enable publisher audio fallback
const publisher = OT.initPublisher('target', {
  audioFallback: {
    publisher: true,
  }
});

// Enable publisher audio fallback and disable subscriber audio fallback
const publisher = OT.initPublisher('target', {
  audioFallback: {
    publisher: true,
    subscriber: false,
  }
});

// Enable subscriber audio fallback and disable publisher audio fallback
const publisher = OT.initPublisher('target', {
  audioFallback: {
    publisher: false,
    subscriber: true,
  }
});

The audioFallback property of the options you pass into the OT.initPublisher() method includes two Boolean properties:

• publisher — Whether to enable (true) or disable (false) publisher audio fallback. The default is false (publisher audio fallback is disabled).

• subscriber — Whether to enable (true) or disable (false) subscriber audio fallback. This setting only applies in routed sessions (sessions that use the Media Router). Subscriber audio fallback is not supported in relayed sessions. The default is true (subscriber audio fallback is enabled). This setting replaces the audioFallbackEnabled property, which will be deprecated.

Audio fallback events and UI indications

When publisher audio fallback is enabled, the Publisher object dispatches these events in response to changing quality conditions:

• videoDisableWarning — Dispatched when the Publisher determines that the stream quality has degraded and the video will be disabled if the quality degrades more.

• videoDisableWarningLifted — Dispatched when the Publisher determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk.

• videoDisabled — Dispatched 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.

• videoEnabled — Dispatched with reason: 'quality' when the Publisher determines that the stream quality has improved and outgoing video transport has been re-enabled.

By default, the Publisher displays icons when the videoDisableWarning and videoDisabled events occur.

The style property of the options parameter for OT.initPublisher() now includes a videoDisabledDisplayMode property. You can set the videoDisabledDisplayMode property to one of the following string values control how the default user interface elements are displayed:

• auto (the default) — The icons are automatically displayed when the video is disabled or in risk of being disabled due to poor stream quality.

• off — The icons are not displayed. You can display your own user interface notifications based on the events described above.

• on — The icons are automatically displayed when the video is disabled or in risk of being disabled due to poor stream quality.

For example the following code disables the default video disabled user interface elements, and handles the related events (so that you can provide your own user interface notifications):

// Enabled
const publisher = OT.initPublisher('target', {
  audioFallback: {
    publisher: true,
  },
  style: {
    videoDisabledDisplayMode: 'off',
  }
});

publisher.on({
  videoDisableWarning: () => {
    // Custom action — for example, add custom UI notification
  },
  videoDisableWarningLifted: () => {
    // Custom action — for example, remove custom UI notification
  },
  videoDisabled: () => {
    // Custom action — for example, add custom UI notification
  },
  videoEnabled: () => {
    // Custom action — for example, remove custom UI notification
  },
});

You can also set the videoDisabledDisplayMode style dynamically by calling the Publisher.setStyle() method:

publisher.setStyle('videoDisabledDisplayMode', 'off');

// Alternately:

publisher.setStyle({
  videoDisabledDisplayMode: 'off',
  // other styles ...
});

Subscriber audio fallback events and UI indicators

A Subscriber object dispatches the following events related to the video being enabled or disabled for the subscriber's stream:

• videoEnabled — Dispatched when the video has been enabled after it was previously disabled.

• videoDisabled — Dispatched when the video has been disabled. The reason property of the event object indicates why the video was disabled. (This event object is an VideoEnabledChangedEvent object.)

• videoDisableWarning — Dispatched when the Media Router determines that the stream quality has degraded and the video will be disabled if the quality degrades more. If the quality degrades further, the Subscriber disables the video and dispatches a videoDisabled event. This event may also be dispatched when using the beta publisher audio fallback feature if the publisher's stream quality if degraded.

• videoDisableWarningLifted — The video has been enabled after it was previously disabled.

The Subscriber videoDisableWarning and videoDisableWarningLifted events are only available in sessions that use the Media Router (sessions with the media mode set to routed).

By default, the Subscriber displays a video disabled warning indicator and a video disabled indicator when the videoDisableWarning and videoDisableWarningLifted events are dispatched. You can disable the default display of the indicator by setting the videoDisabledDisplayMode style setting of the Subscriber object.

The following example uses the videoDisabledDisplayMode style setting to have the video disabled warning indicator and a video disabled indicator blink every one second when the videoDisableWarning and videoDisableWarningLifted events are dispatched:

const indicatorBlinker = new IndicatorBlinker(subscriber);

const IndicatorBlinker = function(subscriber) {
  const timer;
  const indicatorOn = false;
  subscriber.on({
    videoDisabled: function(event) {
      start();
    },
    videoDisableWarning: function(event) {
      start();
    },
    videoDisableWarningLifted: function(event) {
      stop();
    },
    videoEnabled: function(event) {
      stop();
    }
  });
  const start = function() {
    subscriber.setStyle('videoDisabledDisplayMode', 'on');
    if (timer) {
      clearInterval(timer);
    }
    timer = setInterval(function() {
      if (indicatorOn) {
        subscriber.setStyle('videoDisabledDisplayMode', 'off');
      } else {
        subscriber.setStyle('videoDisabledDisplayMode', 'on');
      }
      indicatorOn = !indicatorOn;
    }, 1000);
    indicatorOn = true;
  };
  const stop = function() {
    if (timer) {
      clearInterval(timer);
    }
  };
}

You can also set the videoDisabledDisplayMode style to 'off' and add your own user interface elements based on the videoDisableWarning, videoDisabled, videoDisableWarningLifted, and videoEnabled events.