External Sources are a type of source that developers can associate with a Wwise sound object to dynamically change the media associated with a source. External Sources provide sound data at runtime.

For this reason, developers will likely want to implement their own systems determining which media should be loaded and how (and when) this loading should occur. The External Source Manager was designed with this in mind, it provides a highly extensible base class which provides most of the boilerplate implementation for tracking the states of External Sources and their media, but requires extension to define the actual loading behavior.

Using the Wwise Simple External Source Manager

The integration includes a sample extension of the Wwise External Source Manager called the Wwise Simple External Source Manager. It supports basic External Source management and provides a reference for developers who want to implement their own manager. Refer to Using the Wwise Simple External Source Manager for more information.

Setting up External Sources in Wwise

The generation path for External Sources is set in Wwise Authoring, in the External Sources tab in the Project Settings dialog. Refer to Specifying the Input/Output Locations for External Sources for more information.

Understanding External Sources

An External Source is an empty container. The game has to fill it and inform the Sound Engine about what it contains.

An External Source uses a Cookie, similar to a ShortId, as an identifier. To obtain the Cookie, hash the name specified for the External Source plugin in the source's Contents Editor. Refer to Contents Editor: Wwise External Source for more information.

When an Event that uses External Sources is posted to the SoundEngine, an array of AkExternalSourceInfo structures that identify the media to use for each Cookie must be passed with it. This media can be in-memory or streamed, and the game must ensure that these resources are ready when the Event is posted.

For more information about External Sources, refer to the following topics:

• Wwise External Source Overview
• Contents Editor: Wwise External Source
• AkExternalSourceInfo Struct Reference

For more details about External Source conversion, refer to Integrating External Sources.

Understanding the Wwise External Source Manager

External Sources have several notable characteristics:

• Multiple Events can use the same External Source.
• Multiple External Sources can use the same Media.
• The media an External Source uses is not defined in a SoundBank and can be changed at any time by game logic.

Given the complex relationship between Events, External Sources, and Media, the Wwise External Source Manager has several responsibilities:

• Tracking the state of External Sources used by loaded Events.
• Providing AkExternalSourceInfo structures for calls to PostEvent.
• Tracking the state of loaded media used by External Sources.
• Tracking the mapping between loaded External Sources and media.
• Triggering the loading and unloading of media used by External Sources.
• Packaging the media files used by External Sources in the game.

Implementing the Wwise External Source Manager

To implement a custom Wwise External Source Manager, you must first create a new Unreal module. At a minimum, the module must contain two classes:

• A class that inherits FWwiseExternalSourceManager, which handles the responsibilities listed in the previous section.
  • FWwiseExternalSourceManager contains the pure virtual interface required to define External Sources. For special cases, a project can define this as its inheritance point and fully control the External Source pipeline.
  • FWwiseExternalSourceManagerImpl has all the functions necessary for the runtime to load and unload the media used by External Sources. It has a map of External Source cookies to media IDs, handles the I/O operations, and keeps track of the media lifetime. Inheriting this class simplifies the implementation of custom tracking operations and packaging. The FWwiseExternalSourceManagerImpl class handles complex I/O details itself.
  • You can also use FWwiseSimpleExtSrcModule as a parent class because it is extendable.
• A class that implements FWwiseFileHandlerModule, which overrides InstantiateExternalSourceManager in order to return an instance of the first class.

Afterwards, to enable the module you can set the WwiseFileHandlerModuleName to the name of the new module in the [Audio] section of the DefaultEngine.ini file. Refer to Enabling the Simple External Source Manager for more information.

The Wwise External Source Manager is an interface in the WwiseFileHandler module. When Wwise Event assets that use External Sources are loaded, the WwiseResourceLoader module passes the External Source information in the Event's CookedData (refer to Wwise Unreal Assets) to the WwiseFileHandler, which then delegates resource loading to the Wwise External Source Manager Implementation. What happens next depends on the implementation.

In the default implementation, the External Source Manager creates a FWwiseExternalSourceState structure that tracks the External Source. Depending on the implementation and the information available at the time, the media is either loaded or prepared for streaming. Similarly, when an Event asset is unloaded, the External Source Manager is notified and updates the state of the External Source accordingly. This behavior, which fulfills the External Source Manager's first responsibility (tracking the state of External Sources), is implemented in the following functions:

• PrepareExternalSourceInfos: Public method that selects and retrieves the media list to play depending on the requested External Source, and prepares the AkExternalSourceInfo necessary to play the External Sources.
• LoadExternalSource: Public method that prepares a call to LoadExternalSourceImpl in the manager's execution queue.
• UnloadExternalSource: Public method that prepares a call to UnloadExternalSourceImpl in the manager's execution queue.
• LoadExternalSourceImpl: (Virtual) Handles the creation of, or updates to, tracked External Source States. It then calls LoadExternalSourceMedia.
• UnloadExternalSourceImpl: (Virtual) Handles the removal of, or updates to, tracked External Source States. If the External Source State is to be removed, UnloadExternalSourceMedia is called.

The second responsibility (filling AkExternalSourceInfo structures) is handled by PrepareExternalSourceInfos, which returns the PostEvent External Source parameter. It retrieves the data in the CookieToMedia, uses that information to define the different file states, and provides the AkExternalSourceInfo structure necessary to post the event. You can override it if you want to use a more complex selection algorithm.

In the Wwise Simple External Source Manager extension, a fixed MediaInfo DataTable identifies all External Source media in the project as well as their relevant metadata. A more advanced system could dynamically update the list of known media. Because there are many different ways to implement such a system, all operations are virtualized. You can create code with random containers that change every single PostEvent, or structures that change based on external states, such as a language change.

In order to perform the next set of responsibilities (tracking the state of loaded media, tracking their mapping to External Sources, and loading them from disk), the FWwiseExternalSourceManagerImpl class tracks known External Source media and the information necessary to load them. This state tracking is done internally through the ExternalSourceStatesById map.

After you implement the system and structures mentioned above, we recommend that you implement the following virtual functions:

• LoadExternalSourceMedia: Find the media that an External Source uses and load it (or prepare it for streaming). We recommend that you use the methods inherited from FWwiseFileHandlerBase to track media loading states and FWwiseExternalSourceFileState structures to manage media resources.
• UnloadExternalSourceMedia: Find the media that an External Source uses and unload its resources.
• SetExternalSourceMediaById: Set the media ID of an External Source identified by its name.
• SetExternalSourceMediaByName: Set the media name of an External Source identified by its name.
• SetExternalSourceMediaWithIds: Set the media ID of an External Source identified by its Cookie.

The SetExternalSourceMedia functions assume that each External Source media has a unique ID and, in the case of SetExternalSourceMediaByName, that it is possible to retrieve a media ID from its name. We recommend that you use Simple Wwise External Source Manager as a reference for these functions, because it is likely that your implementation will only differ in how you store, update, and retrieve your External Source to media mapping. Remember that dynamic changes to the mapping between External Sources and media files can lead to resources being loaded and unloaded.

The current implementation treates these as blocking functions, which potentially run through the Game Thread. However, this is not a requirement.

Warning: Forcibly unloading External Source media while it is playing causes the SoundEngine to crash. The FWwiseExternalSourceFileState can handle this automatically through the BindPlayingIdToExternalSources and OnEndOfEvent methods to increment and decrement their play count.

After you finish the implementation of the various functions discussed so far, the most complex part of the External Source manager is complete. If everything works properly, loading an Event Asset (or however your system implements External Source preparation) loads the media used by its External Sources in memory or prepares it for streaming.

Finally, you must package the External Source media. A simple method consists of generating External Source media inside your Unreal project in a directory that is set to always cook. To implement more complex packaging logic, override the External Source Manager's Cook method, which is called by the Wwise Resource Cooker for each External Source contained in cooked Wwise Assets.

The following overridable functions are also available:

• BindPlayingIdToExternalSources: Override this to update your manager's internal state when Events that use External Sources are posted.
• OnEndOfEvent: Override this to update your manager's internal state when Events that use External Sources stop playing.
• SetGranularity: Set the granularity (minimum number of bytes to read) of the prefetch chunk of streaming media.

Wwise External Source Manager Blueprints

By default, three Blueprint functions are exposed in WwiseExternalSourceStatics :

• SetExternalSourceMediaById
• SetExternalSourceMediaByName
• SetExternalSourceMediaWithIds

These functions call the corresponding functions defined in the External Source Manager extension. Refer to External Source Manager Blueprint Functions for more information.

State Structures Used by the External Source Manager

FWwiseExternalSourceState

Structure used by default in WwiseExternalSourceManagerImpl to reference count loaded External Sources.

FWwiseExternalSourceFileState

State structure used by the Wwise Simple External Source Manager to handle media resources. The state tracks its reference count as well as whether it is currently being played. Unloading External Source media while it is playing causes the SoundEngine to crash. Two subclasses are available to handle in-memory or streaming media:

• FWwiseInMemoryExternalSourceFileState
  • Media Data is loaded into memory so it can be used to create an AkExternalSourceInfo struct to pass to the SoundEngine.
• FWwiseStreamedExternalSourceFileState
  • The FileState registers itself with the FWwiseFileHandlerBase base class of the External Source Manager. When requests to stream media are passed to the External Source Manager, the registered FileState is retrieved and it handles the subsequent I/O requests.