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 2023.1.5
Handling User Music (BGM) and DVR

On many consoles it is possible to replace the game music with the user's own music from their personal library. This feature is almost automatic in Wwise. However, there are some differences in implementation and behavior for some platforms.

On all platforms, the initial setup is the same: the sound designer must tag the busses that will be muted when the user starts their music. This is done with the "Mute for Background Music" check box. On the code side, some additional details are needed depending on the platform.

BGM details for Android

Make sure to fill the jActivity member of the AkPlatformInitSettings. The Mute/Unmute action will occur only when the user switches from the music player app to the game. This means that there is no "Unmute" if the user music finishes by itself.

BGM details for iOS

Replacing the game music with an external music application is only possible if the application is using a "mixable" audio session configuration. There are two ways to have a mixable audio session:

  • Using the Ambient audio session category.
  • Using the PlayAndRecord or Playback audio session categories, coupled with the MixWithOthers category option.

Any other configuration stops the user's music application when the game is in the foreground.

Background Music on the DVR-enabled platforms (Xbox One, Xbox Series X, PlayStation 4, and PlayStation 5).

Some platforms have a DVR function that allows the gamer to record their gameplay and publish it. This raises a few legal issues regarding copyrighted music that might be part of the game audio, or user-replaceable music. While the game studio has the rights to use the music in their game, the end-user may not have the rights to distribute it in any form. Thus, the platform requirements usually state that user background music should not be recorded.

The cost-effective solution (CPU-wise) for this problem is to mix the music separately from the rest of the game. This is done using the Secondary Output feature.

Setting up Background Music in the Authoring tool

In the authoring tool, you will need to route your music objects to a separate master Audio Bus than the default or primary one. In most projects, this means creating a brand new master Audio Bus (right click on the Master Mixer Hierarchy's Work Unit and select Add > Child). By default, all busses are routed to the System output. Change the Audio Device ShareSet to point to the DVR output.

Don't forget that not all platforms support a DVR. You will need to Unlink the Audio Device property to point to the System output for those platforms. Alternatively, unlink the Output Bus property of the music objects.

Setting up the DVR Output in the Game Code

The DVR output must be added manually, if used in the game. This is done with AK::SoundEngine::AddOutput(), passing the Audio Device ShareSet name (or ID) along with other parameters in AkOutputSettings.

For an example, refer to <Wwise installation path>/SDK/samples/IntegrationDemo/DemoPages/DemoBGM.cpp.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise