Audio Route Change Principles and Best Practices

The audio route is the pathway audio data takes through different audio hardware components during playback. For example, earpieces, headphones, speakerphone, and Bluetooth devices that output sound all work as an audio route.

This page explains what audio routes are and shows you how to change the audio route from one device to another.

The default audio route

The default audio route is the route audio data takes within a device, such as the speakerphone on a mobile device.

Depending on the use cases, the SDK uses different default audio routes:

• Voice call: Earpiece
• Video call: Speakerphone
• Interactive live audio streaming: Speakerphone
• Interactive live video streaming: Speakerphone

Change the audio route

Change principles

The audio route can be changed using any of the following approaches:

• Device user: Add or remove an external device, such as headphones or a Bluetooth audio device.
• App developer:
  • Call the steady API setDefaultAudioRoutetoSpeakerphone to change the default audio route.
  • Call the transient API setEnableSpeakerphone to set the audio route temporarily.

Regardless of the approach used to change the audio route, the priority of changes taking effect follows these principles:

1. Users' behavior has the highest priority to change the audio route. When a user connects an external device such as a wired headset or Bluetooth headset, the audio route automatically changes to the external device. If the user connects multiple external devices in sequence, the audio route automatically changes to the last connected device.
2. When the user does not connect an external device, the SDK uses the default audio route. Calling setDefaultAudioRoutetoSpeakerphone can change the default setting. If the current audio route is the mobile device itself, setDefaultAudioRoutetoSpeakerphone can change the current audio route.
3. Without any system restrictions, calling setEnableSpeakerphone can temporarily set the audio route to speakerphone or earpiece, regardless of whether the current audio roure is an external device, speakerphone, or earpiece. Because setEnableSpeakerphone is a transient API, any user behavior or audio-related API call might change the transient setting of setEnableSpeakerphone to an audio route that follows principles 1 and 2.

Any change to the audio route triggers the onAudioRouteChanged (Android) or didAudioRouteChanged (iOS) callback. You can use this callback to get the current audio route.

The following sections explain how these approaches affect the audio route.

Audio route changes when the user plugs or unplugs a device

When a user plugs in an audio device such as headphones, the audio route automatically changes to the headphones. When multiple devices are connected, the last device connected gets the audio route.

See how the audio route changes in the following example:

1. A user joins an interactive live streaming channel.
   The audio route is the speakerphone.
2. The user plugs in headphones.
   The audio route changes to the headphones.
3. The user connects the mobile device to a Bluetooth audio device without unplugging the headphones.
   The audio route changes to the Bluetooth audio device.
4. The user disconnects the Bluetooth audio device from the mobile device.
   The audio route changes back to the headphones

The default audio route can be changed

Call the setDefaultAudioRoutetoSpeakerphone method before, during, or after a call to change the defaut audio route between the earpiece and the speakerphone. The setting of this method takes effect until you call destroy to destroy the engine.

See how the audio route changes in the following example:

1. A user plugs in headphones.
   The audio route is the headphones.
2. The user unplugs the headphones.
   The audio route changes to the default audio route of the mobile deivce, depending on your use case.
3. The app calls setDefaultAudioRoutetoSpeakerphone(true).
   The audio route changes to the speakerphone.
4. The user plugs in headphones.
   The audio route changes to the headphones.
5. The app calls setDefaultAudioRoutetoSpeakerphone(true).
   The audio route remains the headphones, because setDefaultAudioRoutetoSpeakerphone works on the audio route of the device only.
6. The user unplugs the headphones.
   The audio route changes to the speakerphone.

The setEnableSpeakerphone method changes the audio route temporarily

You can call the setEnableSpeakerphone method to temporarily change the audio route to the speakerphone, if the operating system permits.

See how the audio route changes in the following examples:

• Example 1

  1. A user joins an interactive live streaming channel.
     The audio route is the speakerphone.
  2. The user plugs in headphones.
     The audio route changes to the headphones.
  3. The app calls setEnableSpeakerphone(true).
     On Android, the audio route changes to the speakerphone. On iOS, the audio route remains the headphones because on iOS, once the mobile deivce is connected to headphones or a Bluetooth audio device, you cannot change to audio route to the speakerphone.

• Example 2

  1. A user joins a voice call channel.
     The audio route is the earpiece.
  2. The app calls setEnableSpeakerphone(true).
     The audio route changes to the speakerphone.
  3. The user plugs in headphones.
     The audio route changes to the headphones.
  4. The user unplugs headphones.
     The audio route changes to the earpiece.