When you work with External Sources, it is important to remember that External Sources and their media are decoupled by default. The designer (or developer) must explicitly establish the mapping between an External Source Cookie, which is essentially a ShortID, and the media to play. External Source media can be generated alongside SoundBanks and streaming media, but the designer must also track the media files and their metadata.

The Simple External Source Manager provides features you can use to track External Source media and map them to External Sources. This is done through the use of Data Tables (.csv files) that describe the External Source media to use in the game as well as an API and Blueprint functions to assign media to External Sources.

Note: Example usage of this SubModule is available in the WwiseDemoGame.

Enabling the Simple External Source Manager

By default, the Simple External Source Manager module is disabled. To enable it, add the following lines to the DefaultEngine.ini file in your Unreal project:

This code overrides the WwiseFileHandlerModule with a module that uses the Wwise Simple External Source Manager submodule to handle loading External Sources.

Settings

There are two Data Tables and a Directory to set in the Wwise Simple External Source Manager Settings:

• Media Info Table contains the metadata necessary to load media files.
• External Source Default Media (optional) defines an initial mapping between External Sources and media in the Media Info Table. You can update or add to this mapping with the API or Blueprint functions described later in this document.
• External Source Staging Directory specifies where to copy the External Source media files relative to the "Game" folder in the packaged game.

Media Info Table

Entries in the media info table have the following properties:

• Name: Must match the ExternalSourceMediaInfoId. Used for lookup in the table.
• ExternalSourceMediaInfoId: Unique ID used to track media in the manager.
• MediaName: File name (with extension) used to find the file on disk. Also used by the manager to look up media IDs when setting media by name.
• CodecID: ID of the codec used to decode the media data. Refer to the AkCodecId enum in AkGameplayTypes.h.
• bIsStreamed: Determines whether to load the media as streaming or in-memory.
• bUseDeviceMemory: Determines whether to use device-specific memory. Only applies to in-memory media.
• MemoryAlignment: Memory alignment to use. Only applies to in-memory media.
• PrefetchSize: Amount of data to prefetch (in bytes). Only applies to streaming media.

External Source Default Media

Entries in the default media table have the following properties:

• Name: Must match the ExternalSourceCookie. Used for lookup in the table.
• ExternalSourceCookie: Unique ID of the External Source, found in Wwise Authoring or in SoundBank metadata.
• ExternalSourceName: Used for logging.
• MediaInfoId: Must match an ExternalSourceMediaInfoId in the Media Info Table.
• MediaName: Used for logging.

How the Simple External Source Manager Works

When the Simple External Source Manager is instantiated, it reads the Media Info Table to populate its list of media metadata. At the same time, a map of media names to media IDs is populated for use with the External Source Manager Blueprint Functions.

Next, the External Source Default Media is read, and External Source Cookie / media ID pairs are added to a map. This optional Data Table sets "default" media for External Sources to use in the game. This system reduces the number of Blueprint and function calls to the SetExternalSourceMedia methods: if the default media are already defined, it is only necessary to use these methods for External Sources that dynamically change their media.

When the External Source Manager loads an External Source (usually triggered by an AkAudioEvent being loaded), a state structure that tracks the number of assets that reference the External Source is created and this map is checked. If a media pairing exists in the map, a state structure for the media is created or updated if it already exist. Depending on the information read from the Media Info Table, the media is either loaded into memory from disk or, if it is streamed, the created state is registered to handle incoming streaming requests from the SoundEngine.

If an External Source Cookie / media ID pair is set during gameplay (for example, by the External Source Manager Blueprint Functions), and if the External Source is already loaded, the media is loaded immediately. If the Exteral Source was already mapped to a different media, the reference count of that media is decremented. If the reference count is 0, it is unloaded after it stops playing.

All PostEvent calls that pass through the AkAudioDevice, including PostEvent calls from the Integration's Blueprint functions, call the External Source Manager's PrepareExternalSourceInfos method. This method selects the media to post on the passed External Source cookies. After the operation succeeds (or fails), the BindPlayingIdToExternalSources method is called to bind all the selected media onto the posted event's Playing ID. Similarly, when Events finish playing, the OnEndOfEvent method is called, which informs the External Source Manager that the media are no longer used by that Playing ID.

Finally, the Cook method supports the packaging of External Source media. When any Event that uses External Sources is packaged, the Cook method is called for each External Source. When this method is called, the Simple External Source Manager stages every media file in its Media Info Table for packaging. Because this only needs to happen once, a flag is set and subsequent calls to Cook do nothing.

Note: If you post events with External Sources directly through the WwiseSoundEngine API, ensure that you implement the External Source Manager's PrepareExternalSourceInfos, BindPlayingIdToExternalSources, and OnEndOfEvent at the appropriate times. Otherwise, if you switch the media an External Source uses while it is playing, the previous media might be unloaded prematurely, which could cause the SoundEngine to crash. At a lower level, you can also override the I/O Hook and handle the file management yourself.

Updating the Data Tables

When the Data Tables on disk are modified and the Unreal Editor is open, their contents are re-parsed. Afterwards, all loaded Wwise Events Assets are unloaded, then reloaded. This brute force approach is the simplest way to ensure that the External Source Manager's state is properly updated.

External Source Manager Blueprint Functions

To update the mapping between External Sources and media, the module provides Blueprint functions to set external source media.

There are three Blueprint functions that take names or IDs, depending on your preference:

• SetExternalSourceMediaById: Use the External Source name to specify the External Source and the MediaID to specify the media.
• SetExternalSourceMediaByName: Use the External Source name to specify the External Source and the MediaName in the Media Info Table to specify the media.
• SetExternalSourceMediaWithIds: Use the External Source Cookie to specify the External Source and the MediaID to specify the media.

When you set an External Source media with strings, the Cookie is determined by a hash of the name string (as in Wwise Authoring). The MediaID is retrieved by looking up the the media name in a map that is populated when the Media Info Table is parsed.

Note: Blueprints can only use signed short integers. To circumvent this restriction, we use a FAkUniqueID variable to set the External Source cookie value.

External Source Manager API

Developers can set External Sources through code in two ways: they can call the Blueprint functions described in the previous section, or they can retrieve the External Source Manager instance and call its methods directly. Most methods in the Wwise Simple External Source Manager are virtual, so developers can extend this manager in a new module to use their own data structures and logic to track media and pair with External Sources.

Limitations of the Simple External Source Manager

The main limitation of the Simple External Source Manager design is the inflexibility of the Media Info Table with respect to multi-platform games. Different platforms use different codecs to decode media, but the structure of the Media Info Table does not support this. One potential solution in an extension of the manager is to create platform-specific Media Info Tables and package the correct one depending on the build target.

When streaming, External Sources have more limitations than internally packaged media. Zero Latency is not possible with External Sources, and the prefetched data is only provided to the SoundEngine when it is requested for playback. There is a playback delay between the initial PostEvent and the actual sample processing, as would occur with any media that do not have Zero Latency.