External Sources are a type of source that developers can associate with Wwise sound objects to provide sound data at runtime. You can use External Sources to load media dynamically, especially if there are many different media files associated with an Event, such as multiple lines of dialogue.

You can use the External Source Manager to implement your own system that determines which media to load, as well as when and how to load it. The External Source Manager provides a highly extensible base class that contains a basic implementation to track states of External Sources and their media, but you must extend it to define the actual loading behavior.

In the Wwise Unreal Integration, the External Source system consists of three parts:

• The External Source Manager, which contains interfaces necessary for calling operations.
• The External Source Manager Implementation, which provides low-level media management operations that respond to PostEvent calls. These operations identify which media to load, and indicate when to unload and load media.
• The Simple External Source Manager, a sample extension that supports basic External Source management and acts as a reference for developers. It provides the data that the implementation layer uses. For more information, see Using the Wwise Simple External Source Manager.

Setting up External Sources in Wwise Authoring

To use External Sources, you must first set the generation path in Wwise Authoring, in the External Sources tab in the Project Settings dialog. See 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 in and inform the sound engine about its contents.

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

When an Event that uses External Sources is posted to the sound engine, 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, see the following topics:

• Wwise External Source Overview
• Contents Editor: Wwise External Source
• AkExternalSourceInfo Struct Reference
• 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.

To manage the relationship between Events, External Sources, and media, the External Source Manager:

• tracks the state of External Sources used by loaded Events.
• provides AkExternalSourceInfo structures for calls to PostEvent.
• tracks the state of loaded media used by External Sources.
• tracks the mapping between loaded External Sources and media.
• triggers the loading and unloading of media used by External Sources.
• packages the media files used by External Sources in the game.

Implementing the Wwise External Source Manager

The default implementation of the Wwise External Source Manager attempts to answer PostEvent calls (PrepareExternalSourceInfos, BindPlayingIdToExternalSources, and OnEndOfEvent) as quickly as possible. It requests PrepareExternalSourceInfos in order to "use" the specified media until OnEndOfEvent indicates that the playing media is no longer needed. The Simple External Source Manager provides the cookies that identify the media to load. You can override the default implementation if desired.

To implement a custom Wwise External Source Manager, you must first create an 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 (see Wwise Unreal Assets) to the WwiseFileHandler, which then delegates resource loading to the Wwise External Source Manager Implementation. Subsequent behavior depends on the implementation.

Tracking External Source states

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 must be removed, UnloadExternalSourceMedia is called.

The default implementation answers PostEvent calls (Prepare, Bind) as quickly as possible.

Providing information to PostEvent calls

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.

Loading and unloading media

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 treats 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 sound engine to crash. The FWwiseExternalSourceFileState can handle this automatically through the BindPlayingIdToExternalSources and OnEndOfEvent methods to increment and decrement their play counts.

After you implement the desired functions, the most complex part of External Source manager development 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.

Packaging External Source media

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 the Wwise Resource Cooker calls for each External Source contained in cooked Wwise Assets.

The following functions, which you can override, 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 Simple 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 sound engine 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.