Wwise Help

To explain how Wwise assigns IDs to the project assets, we'll use the simple project shown below. The project consists of:

Image: Play_Hello event and target sound Hello.

Let's have a look at the contents of the Default Work Unit to see what Wwise assigned to the Sound object. Below is the Sound object's entry in its Work Unit file (.wwu). Items of the Sound object that are not relevant have been removed for clarity.

We can see that Wwise has assigned two IDs to the Sound object: an ID and a ShortID. Let's look at each one in more detail.

The ID is the Sound object's Wwise Authoring ID; a 128-bit globally unique identifier (GUID), guaranteed to be unique. For simplicity, we will refer to them simply as GUIDs. Wwise Authoring uses GUIDs because of their global uniqueness. As such, they make it easier to:

If we look at the Event object Play_Hello's Work Unit, we can see it has a reference to the Sound object Hello.

However, GUIDs are somewhat impractical to use in the Wwise Sound Engine because of their size, given the number of assets in a project.

The other ID given to certain objects in the Work Units is a ShortID; a 32-bit integer. These are the only identifiers stored in your project's SoundBanks and used by the Wwise Sound Engine. For simplicity, we will refer to them simply as ShortIDs. Contrary to GUIDs, which uniquely identify an object throughout the entire project, a ShortID uniquely identifies an object within its ShortID scope. That is, an object's ShortID is unique only among other objects of the same ShortID scope. There are three ShortID scopes:

1. Explicit IDs - objects that are not accessible via the Sound Engine's SDK functions

These are objects that cannot be referred to by user code (e.g. Actor-Mixer objects). This scope is further divided by object types. An object's ShortID is unique only within its object type. Examples of object types are:

The ShortIDs are random numbers assigned at object creation. Because the values are random, each object's ShortID is explicitly tracked by its respective Work Unit entry.

2. Implicit IDs - objects that are accessible via the Sound Engine's SDK functions (e.g. Event, State, Switch).

Because these objects may be referred to by SDK functions by name, these objects are assigned specific ShortID values. The ShortIDs are generated from a hash of the object's name. Because of this:

As with the explicit ShortIDs (above), objects in this scope are grouped by type. Examples of object types are:

Because the ShortIDs are not random but rather implicitly determined by the object's name, they are not tracked in the project's Work Units. If we look back at the event Play_Hello's Work Unit entry above, we see that the Event Play_Hello does not have a ShortID entry.

3. Media Assets (.wem files)

All media assets are given a unique explicit ShortID. As such, they are random numbers and must be tracked in the Work Units. In the example above, the Sound's media is tracked via the AudioFileSource object, and the ID assigned to it is tracked via the MediaID entry.

Wwise Authoring assigns ShortIDs to objects as they are created, ensuring they are unique. However, there is a risk of overlapping ShortIDs, when there are many team members contributing new assets. Consider the following scenario:

In this scenario, there's a ShortID conflict, as we have two objects with the same ShortID. Wwise resolves the conflict by assigning a new, unique ShortID to one of the objects. Wwise assigns the new ShortID to the object causing the conflict. That is, the first loaded object keeps its ShortID and subsequent conflicting objects have their ShortIDs changed.

That being said, as long as new objects are introduced in Wwise while all other assets are loaded, there is no risk. In the case of a game with DLCs, it is absolutely necessary that the shipped assets (i.e. project Work Units) are always present and loaded when introducing new assets into the project. This ensures that new assets never conflict with existing / shipped assets. If new assets conflict with other new assets, Wwise fixes the conflicts when the new assets are merged.

Note: When Wwise resolves a ShortID conflict, by changing the ShortID of the conflicting objects, this also changes the ShortIDs in your SoundBanks. When this happens, a log message will inform you that you must regenerate your SoundBanks.

We've seen how Wwise assigns ShortIDs to objects to uniquely identify an object. We've seen that the same concept applies to media assets. However, media assets have one very important difference compared to all other objects: they may be re-used. Let's look at an updated version of our simple project, in which we've created a second Sound object that uses Hello.wav as well. Below is the pertinent content of the Default Work Unit for both Sound objects. For simplicity, we will refer to a media asset ShortID as a MediaID.

We can see how both Sound objects have been given the same MediaID. That's because both Sound objects use the exact same media asset. After all, there is no sense in shipping your game with multiple copies of the same media asset. Two instances of the same audio asset are considered identical only if they lead to identical .wem files. This means:

Recall the audio asset Hello.wav in our example above where both Sound objects have the same MediaID. Let's edit the project again and assign different conversion settings to HelloAgain. The updated Work Unit is below. Again, we've removed items that are not relevant to us.

Because HelloAgain uses different Conversion Settings, it leads to a different .wem file and is given another MediaID. Note also that it's HelloAgain that is given a new MediaID, and not Hello. That's because Hello did nothing to change its media asset.

Wwise always re-evaluates the MediaIDs when a media asset is created or edited. Wwise ensures that MediaIDs are kept the same if possible. If not, then only assets that have been created/edited are assigned a new MediaID.

As long as a project is fully loaded and edited in Wwise, Wwise makes sure that media assets that do not change keep their MediaIDs. But there are other considerations that a project team should be aware of to ensure the coherence of the project's MediaIDs.

Wwise assigns a MediaID by looking at all instances of the media asset and re-using a MediaID when two or more instances require the same converted media. To do this, Wwise must be aware of all the instances of a media asset. But what if some instances are not loaded in Wwise? This is the case if one asset instance is an unloaded Work Unit. When a Work Unit is loaded Wwise must re-evaluate all MediaIDs within the Work Unit to ensure there are no conflicts. That is, Wwise must ensure that each converted media only has one unique MediaID assigned to it. There are two scenarios to consider.

Loading the Project

Wwise evaluates all MediaIDs as soon as all Work Units are loaded. If there is a conflict, there is no way to predict which MediaID will be kept. This happens, for instance, when multiple team members introduce new Work Units into the project. For example:

This leads to a MediaID conflict, which Wwise can resolve. Again, there are two scenarios to consider:

Loading a Work Unit

Some of the project's Work Units may not be loaded in the project (see Loading/unloading Work Units from your project for more details). Using the same example as above with some slight changes:

The danger in this scenario is that the new Work Units have each been given a MediaID without knowledge of the MediaID of OldWorkUnit. This leads to a conflict when OldWorkUnit is loaded, and Wwise resolves the conflict by keeping the MediaID from either NewWorkUnit1 or NewWorkUnit2. But what if OldWorkUnit is included in previously shipped assets?

In either case, it is very easy for a team member to accidentally change a project's MediaID assignments. To avoid this, the following workflow can be beneficial:

To properly assign MediaIDs, Wwise requires the MediaID assignment of the entire project. As we saw in the previous section, this is not the case when one or more Work Units are unloaded. To that end, Wwise supports a way to manage a project's MediaID assignments, using a single file. With this single file MediaID management workflow:

You can select how Wwise manages MediaIDs (Work Units vs single file), using WwiseConsole.exe with the following arguments:

Continuing with our example project, WwiseIDs, let's move the MediaIDs to a single file by issuing the following command:

WwiseConsole move-media-ids-to-single-file WwiseIDs

Below is the contents of WwiseIDs.mediaid.

Again, our example project only has one media asset, Hello.wav, with two audio source instances. For each instance of Hello.wav:

The MediaID file is loaded during project load after the Work Units have been loaded. The MediaID file is loaded regardless of which Work Units are loaded. When loading the MediaID file, each instance of the audio file's Conversion Settings are hashed and compared to the hash from the file. If the hashes don't match, then the instance is assigned a new MediaID, if required, using the same rules listed in a previous section. Once the project is loaded, all instances from the loaded Work Units have a proper MediaID. However, if more Work Units are loaded afterwards, then the MediaIDs are re-evaluated.

The MediaID file can be used to synchronize your Wwise project with milestones. At each milestone, the Wwise project's MediaID file is updated via WwiseConsole.exe update-media-ids-in-single-file, with the MediaID file of the last milestone. With the updated MediaID file, the entire project is tagged for the new milestone.

How your team manages the Media asset IDs for its Wwise project is dependent on the size and scope of your team and your project.

For a small project with a small team, it's rather manageable that each team member works with the entire Wwise project loaded. Ensuring that there are no MediaID conflicts can be managed via the versioning software used for the project. The use of versioning software becomes necessary for projects that have expansions. For each release, locking the project under versioning software ensures that assets that have been shipped remain unchanged.

For large scale projects and teams with multiple members working and contributing new Work Units simultaneously, a more diligent approach is required. New Work Units may be developed on the side, but in such cases team members should develop with the entire Wwise project loaded, and new Work Units should be introduced into the project one at a time. In such cases, it may be beneficial to manage the project's MediaIDs using a single file.