Set the audio route
Audio routing refers to selection of the audio output device used for playback by your app. This can include a variety of devices such as earpieces, headphones, speakers, and Bluetooth devices capable of playing audio.
This page shows you how to change audio routing in your app.
Understand the tech
Audio routing enables you to change the playback device from the default device to a selected device.
Default audio routing
The routing employed by the device itself, such as the speakers on a mobile device, is called the default audio routing of that device.
The SDK uses the following default audio routing in different scenarios:
- Voice call: Earpiece
- Video call: Speaker
- Live voice call: Speaker
- Live video streaming: Speaker
Change audio routing
Depending on your role, you can change audio routing in the following ways:
- Device user: Add or remove external devices, such as headphones or Bluetooth devices.
- App developer:
- Before joining a channel, call
setDefaultAudioRoutetoSpeakerphone
to change the default audio routing. - After joining a channel, call
setEnableSpeakerphone
to set the current audio routing.
- Before joining a channel, call
Regardless of the method used to make changes to audio routing, the priority for the changes to take effect follows these principles:
-
User behavior has the highest priority for audio routing changes. When a user connects an external device such as a wired headset, or a Bluetooth headset, audio routing automatically switches to the external device. If the user connects multiple external devices successively, audio routing will automatically switch to the last connected device.
-
When no external device is connected, the SDK uses the default audio routing. Call
setDefaultAudioRoutetoSpeakerphone
to change this default setting. If the current audio route is the device itself,setDefaultAudioRoutetoSpeakerphone
modifies the current audio route. -
Without system limitations, calling
setEnableSpeakerphone
switches the current audio routing regardless of whether the current audio routing is an external device, a speaker, or an earpiece. However, this method only works for the current channel, it does not change the default audio routing of the device. If the user leaves the current channel and joins a new channel, the SDK still uses the default audio route.
Any changes to the audio route trigger the onAudioRouteChanged
callback. Use this callback to get the current audio route.
Plug and unplug devices to change audio routing
Audio routing changes when the user connects an audio device. For example, when headphones are plugged in, audio routing automatically switches to headphones. When multiple devices are connected, audio routing switches to the last connected device.
Refer to the following example to see how plugging and unplugging a device changes the audio routing:
-
A user joins the channel. Audio is routed to speakers.
-
The user plugs in headphones. Audio routing changes to headphones.
-
The user connects the mobile device to a Bluetooth audio device without unplugging the headset. Audio routing changes to the Bluetooth audio device.
-
The user disconnects the Bluetooth audio device from the mobile device. Audio routing changes back to headphones.
Change the default audio routing
Before joining a channel, call the setDefaultAudioRoutetoSpeakerphone
method to switch the default audio routing to either the handset or the speakerphone. Set the defaultToSpeaker
parameter of this method to true
to set the default audio route to speakerphone, and to false
to set the default audio route to handset. The setting remains valid until you destroy the engine.
Refer to the following example to understand how to change the default audio routing:
-
The user plugs in the headset. Audio is routed to the headset.
-
The user unplugs the headset. Audio routing is changed to the default audio routing of the mobile device, depending on your usage scenario.
-
Call
setDefaultAudioRoutetoSpeakerphone(true)
in the app. Audio routing is changed to speakerphone. -
User plugs in headphones. Audio routing changes to headphones.
-
Call
setDefaultAudioRoutetoSpeakerphone(true)
. The audio is still routed to the headset becausesetDefaultAudioRoutetoSpeakerphone
only works for the audio routing of the device. -
The user unplugs the headphones. The audio routing is changed to speakerphone.
Changing the current audio routing
If the operating system allows it, call the setEnableSpeakerphone
method to change the current audio routing to speaker.
Refer to the following example to understand how to change the current audio routing:
-
Example 1:
- User joins a channel. Audio is routed to the speaker.
- User plugs in headphones. Audio routing is changed to headphones.
- App calls
setEnableSpeakerphone(true)
. Audio is still routed to headphones.
-
Example 2:
- A user joins a voice call channel. Audio is routed to the speakerphone.
- App calls
setEnableSpeakerphone(true)
. Audio routing is changed to speakerphone. - User plugs in headset. Audio routing changes to headset.
- User unplugs the headset. Audio routing changes to earpiece.
If the user uses an external audio playback device, such as a Bluetooth headset or a wired headset, setting setEnableSpeakerphone(true)
is invalid and the audio is played through the external device.
Reference
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.