Warning : Some protected information on this page is not displayed.
Ensure you are logged in if you are a licensed user for specific platforms.
Wwise SDK 2019.2.15
Handling System-Specific Events

Almost all operating systems have callbacks or notifications for the following events:

  • Pressing Home button
  • Putting application in background/foreground
  • Starting/stopping user music

These events are not handled automatically by Wwise. The main reason is that some of the OS APIs don't allow multiple callbacks or notification receivers. Therefore, the Wwise SDK needs to be told of those events to avoid "eating" those events instead of the game.

For information on how to handle user-music replacements, please read Handling User Music (BGM) and DVR.

Application in Background/Foreground

In general, all game systems can put the application in the background for a time. Wwise can have three possible behaviors, depending on your preferences or the platform's requirements:

  • Suspend all audio rendering: Call AK::SoundEngine::Suspend(false) to do so.
  • Partially suspend (keep processing events, but don't render audio): Call AK::SoundEngine::Suspend(true). This is useful if your game still runs and sends calls to the sound engine.
  • Continue to play audio: There's nothing to do.

In general, when the application is put in the background and Suspend(false) is used, the game should not call any of the sound engine APIs. Posting events and such would work, but would accumulate and be played all at the same time when the system would be awoken. To resume the audio processing, call AK::SoundEngine::WakeupFromSuspend() followed by a call to RenderAudio() when receiving the proper notification from the system. You may queue up other events before calling RenderAudio().

You should read about each platform's requirements in the manufacturer's documentation to choose the right behavior.

Android

On Android, it is important to handle the App Lost/Gain Focus and the App Pause/Resume events. Google's requirements state that an app that is not in the foreground should use as little CPU as possible (preferably none). This can be achieved by calling Suspend(false). See also BGM details for Android.

iOS

Apple requires that as little CPU as possible is used when the application is in the background. This is handled automatically by Wwise. See also BGM details for iOS.

macOS

There are no official guidelines for macOS, but it would be coherent with other platforms to cut the sound with Suspend() when the application process is not active. Whether this is a hard suspend (false parameter) or an active suspend (true parameter) depends on the game implementation.

Linux

There are no official guidelines for Linux, but it would be coherent with other platforms to cut the sound with Suspend() when the application process is not active. Whether this is a hard suspend (false parameter) or an active suspend (true parameter) depends on the game implementation.

Windows

While there are no explicit requirements for Windows, muting the audio while the application is not in the foreground is usually desirable. To do so, you should provide the hWnd of your main window to the AkPlatformInitSettings structure when calling Ak::SoundEngine::Init(). The audio thread will keep running in this case (equivalent to Suspend(true)). This is handled by the OS.

Alternatively, you could also handle the WM_SHOWWINDOW message and do something more specific when minimizing, like fading out the audio or calling Suspend() directly.

UWP

While there are no explicit requirements for UWP, muting the audio while the application is not in the foreground is usually desirable. You can do so by calling Suspend() and WakeupFromSuspend() in your CoreApplication.EnteredBackground and CoreApplication.LeavingBackground event handlers, respectively.