Suggestions

close search

Searching ...

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

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 Vonage Video Media Router). Subscriber audio fallback is not supported in relayed session. The default is true (subscriber audio fallback is enabled). This setting replaces the the audioFallbackEnabled property, which will be deprecated.

Audio fallback events and UI indicators

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 at 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 at 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 ...
});

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.

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 it is determined 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.

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.