Table of Contents

Target Platform(s):

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.

Configuring an Audio App with Wwise

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

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.gif
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.gif
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.
  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.

Note.gif
Note: Refer to the iOS Integration Demo IntegrationDemoAppDelegate.mm source code for examples on all the above mentioned steps.
Caution.gif
Caution: Make sure all the above steps are done before initializing the sound engine with AK::SoundEngine::Init( &in_initSettings, &in_platformInitSettings ).
Note.gif
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 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 a 'begin' source change notification, which will resume the audio processing.
      • The Wwise SDK will call 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 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 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.
      • 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.