Working with Audio Session using the Wwise SDK

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, source change mechanic are already taken care of internally by Wwise and their associated callbacks are totally optional for the end user. Suspending and resuming the sound engine in those cases is also handled by the SDK.

The Integration Demo offers an excellent starting point to learn how to configure and initialize the different audio session parameters as well as the registration of the audio interrupt callback and audio route change. All these steps can be found in IntegrationDemoAppDelegate.mm source file.

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.

Note: The audio session is initialized at the iOS level during the sound engine init call, which itself is called during the IntegrationDemo::Instance.Init() call in the IntegrationDemo's IntegrationDemoAppDelegate.mm file. Although it is possible to change the audio session category after this step using the sharedInstance of the AVAudioSession from the AVFoundation framework, it is recommend to set the AkPlatformInitSettings accordingly at the beginning of the application life like in the Integration Demo didFinishLaunchingWithOptions delegate method.

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.
   • The callback method must respect the AkAudioSourceChangeCallbackFunc type, which is of the form AKRESULT callBackName(bool, void*).
   • 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.
     • When handling a phone call for example, it might be more CPU efficient to completely disable the sound engine during the interruption callback instead of keeping the audio engine running without output in the background.
       
       
3. Register the source change callback (optional).
   • Set struct AkInitSettings.sourceChangeCallback to the user defined callback method.
   • The callback method must respect the AkAudioSourceChangeCallbackFunc type which is of the form AKRESULT callBackName(bool, void*).
   • A source change callback is used when the user wants to know if another app is activating or disabling its audio session while your app is currently using its own audio session in the foreground.
   • This is useful when a user is controlling the Music app or any audio streaming app from the background using, for example, the earbud remote control and your app wants to react to this event by disabling a certain sound bus or, if your app audio is crucial, the whole application.
   • Internally, Wwise will disable/enable the background music bus when receiving a 'begin'/'end' source change notification. So, if your app music track is using the BGM bus, it will be muted when receiving a source change notification.
     
     
4. 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.
     
     
5. Manage the app foreground/background switch.
   • Suspend Wwise with a call to AK::SoundEngine::Suspend(false) in your app delegate - (void)applicationWillResignActive:(UIApplication *)application method.
   • Resume Wwise with a call to AK::SoundEngine::WakeupFromSuspend() in your app delegate - (void)applicationDidBecomeActive:(UIApplication *)application method.
   • If background audio in your app is required, don't suspend or resume the sound engine and use the AkAudioSessionCategoryPlayAndRecord category along with the modified app info plist as explained above.

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 (except the foreground/background switch handling) are done before initializing the sound engine with AK::SoundEngine::Init( &in_initSettings, &in_platformInitSettings ).

Managing app foreground/background switch

App state switch handling is usually done through the UIApplicationDelegate protocol that any app should implement. Any app can be in any of five states as presented in the Apple documentation:

• Not Running
• Inactive (foreground)
• Active (foreground)
• Background
• Suspended

When an app is switched from foreground to background either using the Home button or by the system when answering a phone call for example, the following delegate methods will be called in this order:

• (void)applicationWillResignActive:(UIApplication *)application
• (void)applicationDidEnterBackground:(UIApplication *)application

Reciprocally, when an app transitions from background to foreground using the Home buton or when terminating a phone call that previously interrupted your app, the following delegate methods get called in this order:

• (void)applicationWillEnterForeground:(UIApplication *)application
• (void)applicationDidBecomeActive:(UIApplication *)application

If an app has no specific background operations to do, it is transitioned to suspended state shortly after being in the background state. It can even be terminated without any notice from iOS if, for example, memory runs low on the sytem.

Because those delegates are tied to a running application, Wwise runtime is not aware of them and should not be in any case. If your app does not require playing or recording sound in the background, it is then strongly suggested to suspend the sound engine before leaving the active state in order to limit unncessary CPU processing and to prevent your app from crashing due to system audio ressource access limitations. Similarly, when your app is about to be moved from the background into the foreground active state, the sound engine must be resumed in order for your app to be able to resume its audio operations. These suspend/resume operations must, therefore, be done in your application (void)applicationWillResignActive:(UIApplication *)application and (void)applicationDidEnterBackground:(UIApplication *)application delegate methods respectively.

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.

Typical Audio Session sharing scenarios

To have a better understanding of the overall callflow 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 app delegate applicationWillResignActive() gets called and its up to the user app to suspend the AK::SoundEngine::Suspend(bool in_bRenderAnyway) call.
   • Because an incoming active phone call might suspend your app audio for some time, it is recommended to disable rendering of the sound engine by passing in_bRenderAnyway set to false.
   • The Wwise SDK will also receive a 'begin' interruption notification from iOS, which calls your app interruption callback with the appropriate parameter if it has been registered.
   • The sound engine is immediately suspended internally and all the AAC based nodes are virtualized to prevent issues during suspension.
   • 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 app delegate applicationDidBecomeActive() gets called and the user should resume the sound engine processing using an AK::SoundEngine::WakeupFromSuspend() call.
     • The Wwise SDK receives the 'end' interruption notification from iOS.
     • The sound engine is resumed internally along with the reactivation of the ACC nodes.
     • 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 app delegate applicationWillResignActive() gets called and its up to the user app to suspend the Wwise sound engine using the AK::SoundEngine::Suspend(bool in_bRenderAnyway) call.
   • The Wwise SDK received a 'begin' interruption notification, which calls your app interruption callback with the appropriate parameter if it has been registered.
   • The sound engine is immediately suspended internally and all the AAC based nodes are virtualized to prevent issues during suspension.
   • 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 app delegate applicationDidBecomeActive() gets called and the user should resume the sound engine processing using a AK::SoundEngine::WakeupFromSuspend() call.
     • The Wwise SDK might receive a 'begin' source change notification, which in return calls your source change callback if it is registered.
     • If your app is using a mixable session category (Ambient or PlayAndRecord with the 'mixable' option), the source change notification in the Wwise SDK will mute the background music bus as described in Audio Session categories and options.
     • 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 app delegate applicationWillResignActive() gets called and its up to the user app to suspend the Wwise sound engine using a AK::SoundEngine::Suspend(bool in_bRenderAnyway) call.
       
       
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 receive a 'begin' or 'end' source change notification if either 'play' or 'stop' is pressed, which in return will call your app source change callback if registered.
     • 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 and restore AAC based nodes.
     • Following this, Wwise will call your app source change callback if registered.
   • If your app is configured using the AkAudioSessionCategoryPlayAndRecord category:
     • Behavior is similar to the AkAudioSessionCategoryAmbient category.