The WwiseFileHandler module prepares and handles all External Sources, media, and SoundBank files. It preloads, loads, and streams files, but the module itself doesn't check for any dependencies in the relevant files.

Each file is handled as an individual object that is only opened once, and its usage is tracked independently through a File State. After a File State is made available to one of the three managers described below, the corresponding file is optionally made available to the Sound Engine I/O Hook and Sound Engine File Location Resolver.

The WwiseFileHandler requires the WwiseResourceLoader to register the file first alongside its options as a File State. Then, the file becomes accessible to the Sound Engine’s File Location Resolver.

Because of the metadata stored in the GeneratedSoundBanks folder and cooked with assets as packaging information, the WwiseResourceLoader Module can determine which resources are required, and the WwiseFileHandler provides all the File States prior to loading a resource that might require it.

File States

A File State declares a known file to the WwiseFileHandler module. Using the Load and Unload operations, a file is presented to the WwiseFileHandler, which determines whether it was already loaded and will be ref-counted. As long as there is a user for the file, its File State is kept alive.

Every new operation related to each File State is run in its respective Execution Queue, where the queued operations are run asynchronously, but sequentially. Due to the asynchronous nature of the File State, there are two levels for each File State: the public asynchronous methods and the protected synchronous methods. Each public method is merely a wrapper that pushes an operation to its Execution Queue.

Three main states are available: Closed, Opened, and Loaded. Although the definition of each state is somewhat arbitrary, they can be loosely defined as follows:

• Closed: The file can be safely deleted. It doesn’t have any resources in use by the system other than a small amount of memory.
• Opened: The defining file operation is done. The file was opened and potentially read in memory, either partially or fully. In the case of streamed media, the file is open and the required amount of preloaded data is cached. In the case of media residing in memory, the file was opened, fully read, and closed; the available pointer is its Opened state.
• Loaded: The defining Sound Engine operation is done. The Sound Engine is either aware of the file, or it has been made available. For example, in the case of streamed media, the file is available for the I/O Hook to read its contents. In the case of a media file loaded in memory, its data was sent to the Sound Engine through a SetMedia operation. Similarly, in the case of a SoundBank, its data was processed through the LoadBank method family.

There are also intermediate File States that indicate a transition towards one of the main File States.

Since the operations are asynchronous and can be lengthy, multiple operations might be waiting for the same file to load, in which case only one will make the forward trip, and all of the others will wait for the operation to be completed before returning the status. For example, in a User-Defined SoundBank containing 12 different Events, all 12 Events might request the same SoundBank to be loaded, in which case the Events only proceed when that SoundBank is loaded.

When Unloading, special care is taken in the case of lengthy audio operations. For example, an AK Convolution Reverb file with a long reverberation tail cannot be unloaded until the resonation is finished. Or an unstopped looped media might never stop. These operations might remain in a transient state for multiple seconds.

Additionally, while the reverb’s tail is being processed, there's a chance the same file is requested, for example, while gathering resources for a new map that coincidentally requires the same media. Instead of being stuck in the Unloading state, the state is changed to Reloading, the unloading operation is canceled as soon as possible, and then the state is returned to Loaded.

Sound Engine I/O Hook and Sound Engine File Location Resolver

The Sound Engine I/O Hook and Sound Engine File Location Resolver work together to handle the lifetime of a streamed asset. First, the File Location Resolver asks the WwiseFileHandler to open a file. Then, once it’s open, the I/O Hook requests that the WwiseFileHandler fulfills its asynchronous Read requests for the open file as needed.

Opening a file through the Resolver involves the following steps:

1. Look up the File State map based on the passed Short ID.
2. Ask the File State to acknowledge a new streaming request, which might change its state depending on the File State algorithm.
3. Return the result to the Sound Engine.

In a typical game, this can all be done in less than a millisecond, but it can be considered lengthy nonetheless. However, since the File States are already open and ready for use, additional system I/O operations might not be necessary.

After the file is opened for streaming, the I/O Hook’s asynchronous Read operations are processed through another dedicated Execution Queue, which handles those Read operations exclusively. The goal of that queue is to be efficient and reactive, and eventually batch the Read operations in an optimized manner. It also provides the Close operation for the streamed media, ensuring the Close operation is performed after any pending Read operations.

Like every Sound Engine callback, these are called in a thread that’s not owned by Unreal. They don’t have the same Unreal thread-local data, the stack size is different, and the priority might be different. Because of this, many Unreal operations will fail, such as Stats gathering.

Filename-Based Location Resolver

Most Open operations in the Location Resolver are performed based on a Short ID stored in the various maps.

Opening files based on a file pathname is not supported by the Integration. The Integration only opens files based on Short IDs. However, there are cases when a file could be opened by the Sound Engine based on a file pathname. For example, some algorithms, such as the XML Error Translator, ask for the "SoundBanks.xml" file. Another case is when the Sound Engine is writing files. This is usually done for logging purposes in debug and profile builds.

SoundBank and Media Managers

The SoundBank Manager provides the LoadSoundBank and UnloadSoundBank operations, while the Media Manager provides the LoadMedia and UnloadMedia operations. These two managers track which File States are created and send the information to the Location Resolver when a File State is requested for streaming purposes.

Both work asynchronously through the same Execution Queue pattern. Since the File State creation process is relatively efficient, there is generally little delay when executing several operations simultaneously. However, the callback might take more time to execute since the file must be in a state adequate for its usage, including its Sound Engine loading or unloading.

External Source Manager

The External Source Manager (refer to Using External Sources) manages File States for External Sources. It is designed to be overridden by a user-developed module that implements a data model to track External Source media dependencies. The Wwise Simple External Source Manager is an example that uses Data Tables (.csv files) to map the External Sources to their corresponding media.

The manager provides a supplemental, editor-only operation for cooking that the user can override to properly stage External Source files. With this approach, users don't have to override the WwiseResourceCooker Module only to support their External Source Manager implementations.

Because the posted Events must include the External Sources they use when they are posted, the Integration automatically queries the External Source Manager for this information at the appropriate time. Refer to Using the Wwise Simple External Source Manager for details.