For Vivox 5.15.4 and later, see How to Configure iOS for audio and Bluetooth use (Vivox 5.15.4 and later)
When using Vivox on iOS, the AVAudioSession category must be set to AVAudioSessionCategoryPlayAndRecord to allow access to the microphone. For more information, see the Apple developer documentation on AVAudioSessionCategoryPlayAndRecord.
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?
Important: Changing to AVAudioSessionCategoryPlayAndRecord prevents an application from muting the audio render. For more information, see Why does audio continue on iOS with the Ring/Silent switch set to silent?
Core
When using Vivox on iOS, the AVAudioSession category must be set to AVAudioSessionCategoryPlayAndRecord as part of your Obj-C/C++ application code before you attempt to join a voice channel. It is recommended that you do this 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 the Apple developer documentation on AVAudioSessionCategoryPlayAndRecord.
Important: Changing to AVAudioSessionCategoryPlayAndRecord prevents an application from muting the audio render. For more information, see Why does audio continue on iOS with the Ring/Silent switch set to silent?
Basic audio setup
The following code is an example of setting the AVAudioSession category and preferred sample rate.
void PrepareGameForVivox() {
// Important: must set PlayAndRecord 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:AVAudioSessionCategoryPlayAndRecord
withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker
error:nil];
// 44,100 sample rate must be used for iOS
[AVAudioSession.sharedInstance setPreferredSampleRate:44100
error:nil];
}
Bluetooth
When using Bluetooth devices on iOS, the AVAudioSession category option must be set as indicated in the preceding section, and must also include either HFP (AVAudioSessionCategoryOptionAllowBluetooth) and/or A2DP (AVAudioSessionCategoryOptionAllowBluetoothA2DP, which is only available in iOS 10+). If HFP and A2DP options are both set and the connected device supports both options, then HFP is given a higher priority for routing. For more information, see the Apple developer documentation on AVAudioSessionCategoryOptionAllowBluetooth and AVAudioSessionCategoryOptionAllowBluetoothA2DP.
The following code is an example of setting the AVAudioSession category, default to speaker and both Bluetooth device type options, and preferred sample rate.
void PrepareForVivox() {
// Important: must set PlayAndRecord category for
// simultaneous input/output
// Using HFP will result in a lower fidelity for game audio, but
// is required for capture using the Bluetooth device microphone.
[AVAudioSession.sharedInstance
setCategory:AVAudioSessionCategoryPlayAndRecord
withOptions:(AVAudioSessionCategoryOptionDefaultToSpeaker |
AVAudioSessionCategoryOptionAllowBluetooth |
AVAudioSessionCategoryOptionAllowBluetoothA2DP)
error:nil];
// 44,100 sample rate must be used for iOS
[AVAudioSession.sharedInstance setPreferredSampleRate:44100
error:nil];
}
Unity
When using Vivox on iOS, the AVAudioSession category must be set to AVAudioSessionCategoryPlayAndRecord before attempting to join a voice channel. It is recommended that you do this 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 the Apple developer documentation on AVAudioSessionCategoryPlayAndRecord.
Important: Changing to AVAudioSessionCategoryPlayAndRecord prevents an application from muting the audio render. For more information, see Why does audio continue on iOS with the Ring/Silent switch set to silent?
Basic audio setup
The Unity SDK includes built-in logic that sets the AVAudioSession category to AVAudioSessionCategoryPlayAndRecord, the default to speaker option, and preferred sample rate (similar to the following code snippet). For more information, see the Apple developer documentation on AVAudioSessionCategoryPlayAndRecord.
Note: This update occurs automatically during VivoxUnity Initialize().
[AVAudioSession.sharedInstance
setCategory:AVAudioSessionCategoryPlayAndRecord
withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker
error:nil];
[AVAudioSession.sharedInstance
setPreferredSampleRate:44100
error:nil];
Bluetooth
When using Bluetooth devices on iOS, the AVAudioSession category option must be set as indicated in the preceding section, and must also include either HFP (AVAudioSessionCategoryOptionAllowBluetooth) and/or A2DP (AVAudioSessionCategoryOptionAllowBluetoothA2DP, which is only available in iOS 10+). If HFP and A2DP options are both set and the connected device supports both options, HFP is given a higher priority for routing. For more information, see the Apple developer documentation on AVAudioSessionCategoryOptionAllowBluetooth and AVAudioSessionCategoryOptionAllowBluetoothA2DP.
Note: If Bluetooth options are required for Unity, the built-in configuration update must be disabled and the new category and options must be set by your code.
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);
Add PrepareGameForVivox Files
Find the PrepareGameForVivox.zip file at the end of this article. Unzip this file and add the PrepareGameForVivox.m and PrepareGameForVivox.cs files to your Unity project's Assets/Plugins/iOS folder. If this folder does not exist, create it.
Add Bluetooth options
Modify the PrepareGameForVivox.m to include your required Bluetooth options in the setCategory:withOptions:error call. The following example supports default to speaker (the recommended option), Bluetooth HFP (a Bluetooth device with microphone), and Bluetooth A2DP (a Bluetooth device with no microphone).
[AVAudioSession.sharedInstance
setCategory:AVAudioSessionCategoryPlayAndRecord
withOptions:(AVAudioSessionCategoryOptionDefaultToSpeaker |
AVAudioSessionCategoryOptionAllowBluetooth |
AVAudioSessionCategoryOptionAllowBluetoothA2DP)
error:nil];
Unreal
Refer to the Core instructions sections for Basic audio setup and Bluetooth.