Skip to main content

Vivox: How to: Configure iOS for audio and Bluetooth use (Vivox 5.15.4 and later)

Updated

For Vivox SDK versions previous to 5.15.4, see How to Configure iOS for audio and Bluetooth use (Vivox SDK versions previous to 5.15.4)

 

iOS needs to know the category of the audio that your application is using. It is recommended that you change the AVAudioSession category before standard audio playback of your application because changing the AVAudioSession while audio is playing can cause unexpected audio volume shifts for your users. For more information, see Why does audio volume shift on iOS when using Vivox?.

In Vivox SDK versions previous to 5.15.4, it was recommended that you configure AVAudioSession with the PlayAndRecord category. In Vivox 5.15.4 and later, it is recommended that you set the audio category to Playback. For both the PlayAndRecord and Playback category, Audio ignores the Silent switch set to silent, and audio continues even if the screen is locked when the UIBackgroundModes audio key is added to the app’s info.plist file. For more information, see Why does audio continue on iOS with the Ring/Silent switch set to silent? Also see the Apple developer documentation on AVAudioSessionCategoryPlayback and UIBackgroundModes.

For Vivox on iOS, the AVAudioSession category must be set to AVAudioSessionCategoryPlayback as part of your iOS application code on app startup. When the Vivox SDK is using the microphone (such as when a user joins a channel or starts local capture), the AVAudioSession category is set to AVAudioSessionCategoryPlayAndRecord, which is automatically configured in the code. For more information, see iOS app development in the Vivox developer documentation. Also see the Apple developer documentation on AVAudioSessionCategoryPlayback and AVAudioSessionCategoryPlayAndRecord.

Bluetooth

When using a Bluetooth device on iOS, the AVAudioSession category option must be set as indicated in the Basic audio setup described below for Core and Unity. The system automatically routes to A2DP ports (AVAudioSessionCategoryOptionAllowBluetoothA2DP, which is only available in iOS 10+) if you configure an app’s audio session to use AVAudioSessionCategoryPlayback. When using the Playback category, the system automatically routes to A2DP ports when not accessing the microphone. For more information, see the Apple developer documentation on AVAudioSessionCategoryOptionAllowBluetoothA2DP and AVAudioSessionCategoryPlayback.

Because the Bluetooth settings for A2DP are automatic, there are no required changes to your audio setup.

Core

The following code details an example of how to set the AVAudioSession category.

void PrepareForVivox() {
    // Important: must set Playback category for
    // simultaneous input/output
    // Default to speaker will play from speakers instead
    // of the receiver (ear speaker) when headphones are not used.

    [AVAudioSession.sharedInstance
     setCategory:AVAudioSessionCategoryPlayback
     mode:AVAudioSessionModeDefault
     options:0
     error:nil];
}

Unity

Basic audio setup

The Unity SDK includes built-in logic that sets the AVAudioSession category to AVAudioSessionCategoryPlayback (similar to the following code snippet).

Note: This update occurs automatically during VivoxUnity Start().

[AVAudioSession.sharedInstance
   setCategory:AVAudioSessionCategoryPlayback
   mode:AVAudioSessionModeDefault
   options:0
   error:nil];

For more information, see the Apple developer documentation on AVAudioSessionCategoryPlayback.

Skip built-in PrepareForVivox

In your code where you initialize the Vivox client object, you need to create a VivoxConfig object and set the SkipPrepareForVivox value as true. You use this VivoxConfig during the initialization process, as detailed in the following code snippet. This prevents the built-in AVAudioSession update from occurring.

VivoxConfig config;
config.SkipPrepareForVivox = true;
_client.Initialize(config);

Note: PrepareForVivox() is already included in the Vivox Unity and Unreal plugin.

Unreal

Refer to the Core instructions.

Related to

Related articles