Linking Modules

The Wwise Unreal Integration is separated into multiple modules and multiple plug-ins. In order to use Wwise's functionality within a C++ project, you must link these modules within your project's build file (.Build.cs). You can disable a module by removing it from the build file.

In the following example, the project includes the following modules as public: Core, CoreUOBject, Engine, InputCore, AkAudio, and WwiseSoundEngine. AkAudio and WwiseSoundEngine are Wwise modules.

In this case, the functionality of the WwiseSoundEngine module and AkAudio module are available. Modules can be in the PublicDependencyModulesNames or PrivateDependencyModulesNames. For more information about modules, see Unreal Engine Modules.

For more information about Wwise plug-ins and modules, see Understanding the Wwise Unreal Integration Plug-ins.

Overriding the Wwise Unreal Integration

The modules in the Integration, aside from WwiseSoundEngine, AudiokineticTools, and AkAudio, are designed to be extensible through inheritance. Most functions in these modules are virtual to allow developers to override them and modify their behavior to best suit their project. To override a module, create a new module and make sure it inherits the module you want to override. Then, override the desired functions. To use your new module, make sure it is included in the Build.cs of your game and added to the DefaultEngine.ini like this:

The WwiseSimpleExternalSource module is an example of overriding a module. It overrides the WwiseFileHandler module to handle external sources with Data tables.

Creating AkComponents Using C++

When creating a new AkComponent using C++, you must attach it to a parent component. The AkComponent is necessary for the API to work as intended. The following sections provide examples of how to add an AkComponent.

Using the Wwise API in your Unreal Projects

It's possible to use the Wwise API through the Wwise Unreal Integration. You can call most functions through the WwiseSoundEngine module or the AkAudio module.

WwiseSoundEngine Plug-in

The WwiseSoundEngine plug-in and module provides low-level access to most SoundEngine API operations. With the WwiseSoundEngine module, you can access API functions directly and securely, as shown in the following example:

This code posts an Event on a given actor. You must add the UAkComponent on the actor to register it with Wwise. The Event must be loaded as well since loading an Event isn't automatically performed in the WwiseSoundEngine module.

Note: Prior to version 2022.1 of the Integration, it was impossible to access code outside the AkAudio module because the API needed to be accessed in the same dynamic library.

AkAudio Module

The AkAudio module is the root module for most of the Integration’s user-facing features. It can accomplish most of what the WwiseSoundEngine module can using Unreal Components. It contains classes for the asset types and components used by the Integration. As an alternative to calling the SoundEngine directly, the AkAudioDevice provides many helper functions to wrap common uses of the WwiseSoundEngine API. These helper functions also check that the necessary resources required to use the API are loaded, and they provide more informative logging.

The following code, just like the previous example, posts an Event on a given actor, but also takes care of attaching the AkComponent and loading the Event:

More examples of code can be found in the WwiseDemoGame under WwiseDemoGame/WwiseCodeExample and can be experimented with in the WwiseDemoCodeExampleMap.

Debug Features

Logging

Each module in the Integration has an independent log verbosity level. This helps to debug efficiently. If an error occurs, you can find which module produced the error, and then you can set the verbosity of that module's logs to Verbose or VeryVerbose to better understand why the error occurred. You can change the verbosity level of each module in the Core.Log section of the DefaultEngine.ini file. There's also a special logging category called LogWwiseHints enabled by default across all modules, which warns about using deprecated functions and other bad habits.

The following verbosity levels are possible:

• Fatal: Causes a crash when program execution cannot or should not continue. For example, if required plug-in modules are not loaded.
• Error: Prevents packaging the game if the audio is not in a functional state.
• Warning: Indicates when non-critical features might have unpredictable behavior. It can also prevent packaging if desired.
• Display: Logs information regarding the initialization of modules and provides Commandlet information.
• Log: Logs various important operations.
• Verbose: Logs all operations that a module is performing.
• VeryVerbose: Logs every step of each operation a module is performing.

In the following example, you can see the verbosity level associated with each module:

For more information about verbosity levels, see ELogVerbosity::Type.

Stats

The Integration includes the following Stats that might help with debugging:

• AkAudioDevice: Logs information about Post Event Async calls.
• AkSoundBankGenerationSource: Logs WAAPI calls related to SoundBank generation.
• WwiseConcurrency: Logs information about memory used to manage multi-threading.
• WwiseFileHandler: Logs information about loaded media, SoundBanks, and external sources.
• WwiseFileHandlerLowLevelIO: Logs information about streaming sounds.
• WwiseMemory: Logs information about memory usage.
• WwiseObstructionOcclusion: Logs information about obstruction and occlusion calculations.
• WwiseProjectDatabase: Logs information about memory used by the WwiseProjectDatabase module.
• WwiseResourceLoader: Logs information about referenced AkTypes.
• WwiseSoundEngine: Logs information about API calls.

To access this information, select the Stats that interest you in the Unreal Viewport options.

For more information about Stats, see Stat Commands.

Packaging Requirements

When you package your Unreal project, the assets are "tree-shaken." In other words, Unreal assets that represent Wwise objects are automatically included if they are referenced either by another packaged asset or by a packaged map. If they are, any associated SoundBanks and media files are copied into the built package. Any Wwise Unreal assets that do not satisfy one of these conditions are not included.

This packaging approach is efficient, but in certain cases some Wwise Unreal assets might be improperly excluded, which can cause errors. The following scenarios can cause this type of problem:

• The project uses Wwise Unreal assets that are not directly referenced by packaged maps.
• The project uses Events that are posted by string or from code.

If one of these scenarios applies to your project, you must therefore ensure that either the asset is directly referenced by a map, or ensure that the required assets are manually loaded. To manually add assets, add the containing directory to the project's Additional Asset Directories to Cook in the Project Settings. See the Project section of the Unreal Project Settings documentation for more information.