Version

menu_open

Managing Media Asset IDs

Like many other game engines, Wwise manages a project's assets using numerical identifiers (IDs). Wwise assigns two types of IDs to a project's assets: one used by the Wwise Authoring application (wa) and one for the Wwise Sound Engine (wse). Wwise assigns and/or updates these IDs while a project is being edited. This happens in the background, and typically your team doesn't need to be exposed to this. However, knowing how Wwise assigns and uses asset IDs can be much more important when your project involves a game with subsequent updates, whether they be game fixes and/or expansions. In all cases, it is preferable that your game update be as small as possible. Given that the largest part of any Wwise project's assets is the audio assets (.wem files), it's preferable to limit the number of audio files in your update. To that end, it's essential that the IDs of your project's audio assets not change so they may be re-used, removing the need to re-publish assets.

Wwise ID Assignment

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

  • One audio asset, Hello.wav;

  • A Sound object Hello which refers to the audio asset;

  • An Event object Play_Hello with a play action, used by the game to trigger the playback of the audio asset.

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.

Wwise Authoring ID

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:

  • Manage the many operations that editing software must perform;

  • Manage a project that may have contributions by more than one team member;

  • Have object references between work units.

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.

Wwise Sound Engine IDs

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:

  • Actor-Mixer and Interactive Music objects (Sounds, Containers)

  • Bus objects (Busses, Aux Busses)

  • Effects

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:

  • No two named objects may have the same name.

  • No two named objects may have the same ShortID.

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

  • Events

  • Switches

  • States

  • RTPCs

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.

ShortIDs in Action

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:

  • Your project has an object A, with ShortID 12345678.

  • One of your team members has created a separate Work Unit.

  • The new Work Unit was created before your project had object A.

  • The new Work Unit includes an object B, with the same ShortID.

  • The new Work Unit is copied over to the project.

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.

More on Media Asset IDs

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:

  1. The two instances are identical before conversion:

    • Media assets are modified before conversion via the Source Editor;

    • Examples of file modifications are trimming the file, adding fades, etc.;

    • In our example, both Sound Objects do not modify the file.

  2. The two instances are identical after conversion:

    • Conversion Settings can be edited via the Conversion Settings Editor;

    • In our example, both Sound Objects use the same Conversion Settings.

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.

Loading Work Units

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:

  1. Team member 1 introduces NewWorkUnit1, with media Example.wav;

  2. Team member 2 introduces NewWorkUnit2, also with media Example.wav;

  3. The entire project, including the two new Work Units, is loaded into Wwise.

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

  1. Example.wav is a new asset. This case has no impact on the rest of the project. Wwise simply keeps the MediaID of one of the new Work Units.

  2. Example.wav is an existing asset. Wwise will have taken the MediaID from the existing Work Unit, assuming the Work Unit was loaded by both team members.

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:

  1. Example.wav already exists in the project, in Work Unit OldWorkUnit;

  2. Both team members 1 and 2 create their new work units, introducing Example.wav, with OldWorkUnit unloaded.

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:

Managing MediaIDs Using a Single File

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:

  • MediaIDs are no longer stored in the Work Units.

  • MediaIDs for the entire project are stored in a separate file, named "project-name.mediaid", and located next to the project's main file, "project-name.wproj".

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

  • move-media-ids-to-single-file: Change from the traditional "MediaIDs in Work Units" workflow to the single file workflow. This operation will load the entire project from the command-line, generate the .mediaid file and remove MediaID entries from Work Unit files.

  • move-media-ids-to-work-units: Change from the single file workflow to the traditional "MediaIDs in Work Units" workflow. This operation will load the entire project from the command-line, move MediaIDs from the .mediaid file to the appropriate Work Unit files, and delete the .mediaid file.

  • update-media-ids-in-single-file: Update the contents of the .mediaid file. This operation will load the entire project from the command-line, then write the updated MediaIDs to the .mediaid file.

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 instance has its entry indexed by the audio source's GUID (Authoring ID).

  • The instance has the MediaID assigned to it.

  • The instance has a hash value representing the Conversion Settings used by the instance at the time the MediaID was assigned.

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.

Conclusion

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.


Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise