Suggestions

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 prop of the OTPublisher component will be deprecated. Please use the audioFallback.subscriber setting instead.

This topic includes the following sections:

• Enabling audio fallback
• Publisher audio fallback Publisher events
• Subscriber audio fallback Subscriber events

Enabling and disabling audio-only fallback

Set the audioFallback property of the properties prop you pass into the OTPublisher component:

// Enable subscriber audio fallback (the default)
// and publisher audio fallback:
<OTPublisher
  properties={{
    audioFallback={
      publisher: true,
    },
  }}
/>
});

// Enable publisher audio fallback and disable subscriber audio fallback:
<OTPublisher
  properties={{
    audioFallback: {
      publisher: true,
      subscriber: false,
    },
  }}
/>

// Enable subscriber audio fallback and disable publisher audio fallback:
<OTPublisher
  properties={{
    audioFallback: {
      publisher: false,
      subscriber: true,
    },
  }}
/>

// Disable both publisher audio fallback (the default)
// and subscriber audio fallback:
<OTPublisher
  properties={{
    audioFallback: {
      subscriber: false,
    },
  }}
/>

The audioFallback object includes two Boolean properties:

• publisher — Whether to enable (true) or disable (false) publisher audio fallback. With publisher audio fallback enabled, when the stream's quality has degraded significantly (for example, because of network conditions), the publisher disables video in order to preserve audio quality. 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 OpenTok Media Router). Subscriber audio fallback is not supported in relayed session. With subscriber audio fallback enabled, when the OpenTok Media Router determines that a stream's quality has degraded significantly for a specific subscriber, it disables the video in that subscriber in order to preserve audio quality. The default is true (subscriber audio fallback is enabled). This setting replaces the the audioFallbackEnabled property, which will be deprecated.

Publisher audio fallback events

When publisher audio fallback is enabled, callback methods of the OTPublisher component are invoked in response to changing quality conditions:

• videoDisableWarning() — Called when the Publisher determines that the stream quality has degraded and the video will be disabled if the quality degrades more.
• videoDisableWarningLifted() — 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.
• videoDisabled() — 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.
• videoEnabled() — Called with the reason property set to 'quality' when the Publisher determines that the stream quality has improved and outgoing video transport has been re-enabled.

For example the following code adds event listeners for audio fallback-related events (so that you can provide user interface notifications):

<OTPublisher
  properties={{
    audioFallback: {
      publisher: true,
    }
  }}

  eventHandlers={{
    videoDisableWarning: () => {
      // Add UI notification
    },
    videoDisableWarningLifted: () => {
      // Adjust UI notification
    },
    videoDisabled: () => {
      // Add UI notification
    },
    videoEnabled: () => {
      // Remove UI notification
    },
  }}
/>

Subscriber audio fallback events

The OTSubscriber component includes callback methods that are invoked based on events related to the video being enabled or disabled for the subscriber's stream:

• videoEnabled() — Called when the video has been enabled after it was previously disabled.
• videoDisabled() — Called 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() — Called when the OpenTok 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 calls the videoDisabled() callback. This event may also be dispatched when using the publisher audio fallback feature if the publisher's stream quality if degraded.
• videoDisableWarningLifted() — Called when video has been enabled after it was previously disabled.

The OTSubscriber videoDisableWarning() and videoDisableWarningLifted() callback methods are only invoked in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).

For example the following code adds event listeners for audio fallback-related events (so that you can provide user interface notifications):

<OTSubscriber
  eventHandlers={{
    videoDisableWarning: () => {
      // Add UI notification
    },
    videoDisableWarningLifted: () => {
      // Adjust UI notification
    },
    videoDisabled: () => {
      // Add UI notification
    },
    videoEnabled: () => {
      // Remove UI notification
    },
  }}
/>