In order for your audio app to easily and correctly manage audio session using the Wwise SDK, a certain number of simple steps are required. Wwise handles a lot of the iOS audio session complexities behind the scene in order to let the user focus on the app essentials. All audio interruption and route change mechanics are already taken care of internally by Wwise and their associated callbacks are completely optional for the end user. Suspending and resuming the sound engine in those cases is also handled by the SDK.

Configuring an Audio App with Wwise

To configure the app audio session and the different available callbacks use:

• struct AkInitSettings
• struct AkPlatformInitSettings

Use struct AkPlatformInitSettings::AkAudioSessionProperties member to set eCategory, eCategoryOptions, and eMode to the desired audio session category with optional override options and modes for the app.

Note: The enum AkAudioSessionCategoryOptions member is a bitmask that can be configured to carry multiple category options. In the Integration Demo IntegrationDemoAppDelegate.mm, the method GetAudioSessionCategoryOptionBitMask() shows an example of how this mask can be set using a set of input bool types to set/unset the desired options.

Here are the simple steps required by any Wwise SDK user app in order to easily create a working audio app that is fully iOS audio session compliant:

1. Set up the audio session category.
   • Set the struct AkPlatformInitSettings.audioSession.eCategory with desired value.
   • Set the struct AkPlatformInitSettings.audioSession.eCategoryOptions with desired value (optional).
     
     
2. Register the interruption callback (optional).
   • Set the struct AkPlatformInitSettings.audioCallbacks.interruptionCallback to the user defined callback method.
   • Depending on the audio application type or game genre, the user interruption callback can be used to achieve many goals:
     • For an audio dependent application such as a rhythmic based game, it can be used to pause the entire game.
     • For an audio playback application, the callback can be used to visually reflect the interruption.
     • When a 'begin' audio interruption occurs, Wwise internally suspends the sound engine with the rendering option set to true, so if a complete audio engine disabling is required by your app, it can be done in the user interruption callback.
3. Register for a route change notification (optional).
   • Register to iOS NotificationCenter for the AVAudioSessionRouteChangeNotification and provide a selector for it (callback)
   • See the Integration Demo source code for a simple example.
     
     

Note: Refer to the iOS Integration Demo IntegrationDemoAppDelegate.mm source code for examples on all the above mentioned steps.

Caution: Make sure all the above steps are done before initializing the sound engine with AK::SoundEngine::Init( &in_initSettings, &in_platformInitSettings ).

Note: Only audio session category AkAudioSessionCategoryPlayAndRecord allows for audio to be played and/or recorded in an app background state. If this behavior is required, the app info plist must also be modified in Xcode to add the 'Required background modes' key with the 'App plays audio or streams audio/video using Airplay' value.

Changing the Audio Session Configuration at Runtime

To reconfigure the audio session after the sound engine has been initialized, use the AK::SoundEngine::iOS::ChangeAudioSessionProperties() API call. This is useful if, for example, your app needs microphone input temporarily and needs to switch to the Play and Record category for the duration of the recording.

Note: Changing audio session properties during runtime causes the sink to reset. Any audio playback will glitch for a fraction of a second at this time. Therefore, it is better to call this API while the app is silent.

Refer to the iOS Integration Demo DemoAppLifecycle.cpp source code for a demonstration of how this is done.

Typical Audio Session Sharing Scenarios

To have a better understanding of the overall call flow that happens in diverse audio session sharing scenarios, we present some cases here to illustrate how inter-app audio is handled using Wwise and the iOS audio session.

1. When receiving a phone call while your app is playing/recording audio and no app switching occurs while the call is active:
   • At the moment the phone rings, your app audio session is deactivated by the system (Phone always has a higher session priority than other tasks) and the phone app is brought to the foreground.
   • The Wwise SDK will receive a 'begin' interruption notification from iOS and suspend the audio processing.
   • The Wwise SDK will call your app interruption callback with the appropriate parameter if it has been registered.
     
   • If registered, audio route change notifications are also received to let the app know that the audio session category has changed.
   • If the user discards the call or when the call ends:
     • Your app audio session is resumed.
       
     • The Wwise SDK receives the 'end' interruption notification from iOS and resumes processing audio.
       
     • Following this, your app receives the 'end' interruption callback with the appropriate parameter if it has been registered.
       
       
2. When receiving a phone call while your app is playing/recording audio and app switching occurs while the call is active:
   • At the moment the phone rings, your app audio session is deactivated by the system (Phone always has a higher session priority than other tasks) and the phone app is brought to the foreground.
   • The Wwise SDK received a 'begin' interruption notification and suspends audio processing.
   • The Wwise SDK calls your app interruption callback with the appropriate parameter if it has been registered.
     
   • If registered, audio route change notifications are also received to let the app know that the audio session category has changed.
   • During the call, if the user presses the Home button to switch back to your app:
     • Your app audio session is resumed.
       
     • The Wwise SDK receives an AppDidBecomeActive notification, which will resume the audio processing.
     • If your app is using a mixable session category (Ambient or PlayAndRecord with the 'mixable' option), the Wwise SDK will mute the background music bus.
     • Sound from the phone app is mixed with your app audio while the latter is in the foreground, no matter what session category your app uses.
   • If the user switches back to the phone call:
     • The Wwise SDK will suspend the audio processing.
3. Impact of earbud as remote control on the different session categories
   • If your app is configured using the AkAudioSessionCategoryAmbient category:
     • Pressing the remote control (play/stop) button on the earbud will (start/pause) user music from the Music app in the background.
     • The Wwise SDK will mute and unmute the background music bus accordingly.
     • Since the audio session category is a mixable one, sound will be mixed between the Music app and your app.
   • If your app is configured using the AkAudioSessionCategorySoloAmbient category:
     • Pressing the remote control play button on the earbud will start user music from the Music app in background.
     • Since the category is not mixable, your app audio session will be deactivated and the Wwise SDK will receive a 'begin' audio interruption notification, which will call the user interruption callback if registered.
     • The Wwise SDK sound engine will be suspended internally.
     • When pressing the remote control to stop the user music, your app audio session is restored.
     • The Wwise SDK will receive an 'end' source change notification, which will internally resume the audio engine.
   • If your app is configured using the AkAudioSessionCategoryPlayAndRecord category:
     • By default, behavior is similar to the AkAudioSessionCategorySoloAmbient category.
     • With AkAudioSessionCategoryOptionMixWithOthers enabled, the behavior is similar to the AkAudioSessionCategoryAmbient category.