Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Audio Fallback — Web

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

For conceptual information, see the audio fallback overview.

Note: The audioFallbackEnabled property of the options passed into the OT.initPublisher() method will be deprecated. Please use the audioFallback.subscriber property of the options object instead.

This topic includes the following sections:

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 audio fallback events and UI indicators

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

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:

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:

The Subscriber videoDisableWarning and videoDisableWarningLifted events are only available in sessions that use the OpenTok 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.