Wwise 2023.1 includes the largest Wwise Authoring API (WAAPI) update since the introduction of the API in 2017. If you haven't seen What's New in Wwise 2023.1 already, I welcome you to take a look. The list of changes related to WAAPI is huge. In this blog, we will take a closer look at some of the changes we made.

But What Is WAAPI?

WAAPI is used to communicate with the Wwise Authoring application from an external application, like a Python script or a C++ program. If you want to learn more about it, check out this page: https://www.audiokinetic.com/en/library/edge/?source=sdk&id=waapi.html.

Common tasks that you can do with WAAPI are:

• Import audio files
• Create object structures
• Generate SoundBanks
• Query a project (with WAQL)
• and so much more!

In fact, you might have used WAAPI already without knowing it. WAAPI is used under the hood in the following places:

• REAPER to Wwise transfer:
• Audiokinetic ReaWwise (https://github.com/audiokinetic/ReaWwise) 
• LKC GRIM SYNC (https://www.lkctools.com/grimsync) 
• Game engine integrations:
• Wwise Unreal Integration
• Wwise Unity Integration
• Audio file management:
• Basehead - Wwise Integration (https://baseheadinc.com/)
• Soundly - Wwise Integration (https://getsoundly.com/) 
• Soundminer - Wwise Integration (https://store.soundminer.com/)

Additionally, integrating WAAPI into a game development pipeline is a good way to automate certain tasks and improve data quality in your daily workflow.

Our Objectives for this Release

With every release of Wwise, we try to balance addressing customer feedback with our own roadmap. For this specific release, one of the top customer stories was about using WAAPI in a source control environment. The second story, which was also aligned with our roadmap, was to increase WAAPI coverage by refactoring some of our data models, including Interactive Music objects. We will talk more about music objects later in this blog, but let's start with source control!

Source Control Support

When we initially developed WAAPI in 2017, there were a few elements that we had to cut in order to deliver our minimum viable product (MVP). One of the elements was source control support. Now that WAAPI has become integrated with so many of our users' pipelines, we had to address this shortcoming.

Here is the list of things we wanted to address:

• Blocking pop-ups when importing audio files. A simple example is when using ReaWwise, you get source control pop-ups in Wwise everytime you render from REAPER, which blocks the REAPER user interface resulting in a bad user experience.
• Work Unit creation, deletion, moving and renaming. Anything involving file system operations has to be registered with source control. Many WAAPI functions can create Work Units.
• Source control at the command line. The entire source control was not available when using WwiseConsole.exe.
• Managing audio files. It wasn’t possible to automate re-organizing the Original audio files. File Manager was the only way to move or rename audio files without breaking the project. With large projects, automated asset organization is very important.

To achieve these objectives, we had to revisit how the source control plug-ins work. The main objective would be for all of our APIs to be silent and fully compatible with source control.

Testing Strategy

Before we could start any work, we had to think about a testing strategy. Testing source control is always a very tedious task, and it must not be overlooked. The scope of our changes was so large that we could have easily broken something without noticing. The good news is that the features that we added allow us to automate testing, which was not possible before.

So, for us, it was natural to support Perforce in our automated testing framework. And since all of our WAAPI functions were already covered in the test framework, we would take the same approach with the new source control features, and be more confident about the quality of our changes.

User Interface

First, we had to be in control of the user interface created by source control plug-ins. Those are the main blockers for automation. There were two kinds of pop-ups: 

• Custom pop-ups, like the Checkout Dialog (image below)
• Source control Log

Every time we removed a dialog, we had to provide an equivalent option in the WAAPI functions so that it automatically does a Check Out or a Mark for Add on the files. In the end, a total of 10 different WAAPI functions now support automatic source control operations:

• ak.wwise.console.project.open
• ak.wwise.ui.project.open
• ak.wwise.core.audio.import
• ak.wwise.core.audio.importTabDelimited
• ak.wwise.core.object.copy
• ak.wwise.core.object.create
• ak.wwise.core.object.delete
• ak.wwise.core.object.move
• ak.wwise.core.object.set
• ak.wwise.core.project.save

Adding source control support to all of those APIs wasn't an easy task. There were so many code paths to modify in the core of Wwise Authoring. At least we already had good test automation coverage, but it was a good opportunity to increase this coverage when manipulating Work Units.

Second, we had to find a replacement for the log dialogs. For that, we redirected all source control messages to our Logs view, and we created a new tab for it:

The good news is that the centralized log was already exposed in WAAPI. We simply added a new channel to the API.

Pushing Automation to the Limit

From this point, we had most of the indirect source control operations covered. For example, creating a Work Unit object with ak.wwise.core.object.set would trigger the Add operation on the associated WWU file. But what about doing direct source control operations on a WAV file, like renaming or moving a WAV file? We did not have a direct way to test the source control core; so far, we could only test it through non-source control operations.

So we decided to add the full source control API to WAAPI. The following functions, which map directly to source control features, were added:

• ak.wwise.core.sourceControl.add
• ak.wwise.core.sourceControl.checkOut
• ak.wwise.core.sourceControl.commit
• ak.wwise.core.sourceControl.delete
• ak.wwise.core.sourceControl.getSourceFiles
• ak.wwise.core.sourceControl.getStatus
• ak.wwise.core.sourceControl.move
• ak.wwise.core.sourceControl.revert
• ak.wwise.core.sourceControl.setProvider

And to go even further, we added support for source control directly in WwiseConsole when using waapi-server, generate-soundbank, and tab-delimited-import. With these, we could push the automation further, and really isolate the functionality.

Increasing WAAPI Coverage

OK, let's talk a bit more about our objective to increase coverage in WAAPI. For the last couple of years, we have been refactoring more and more of the data models in Wwise to make them generic and accessible through the existing WAAPI functions. For this release, we put our focus on the Interactive Music Hierarchy. For instance, it was previously not possible to configure certain music objects in WAAPI. Here is the list of what we exposed in 2023.1 related to music objects:

• Associations and Argument in Music Switch Containers
• Playlist Root in Music Sequence Containers
• Trigger and Segment Reference in Music Stingers
• Transition Root in music objects

In addition to the music elements listed above, we also exposed:

• Entries in Dialogue Events
• Markers in audio file sources
• Playlist in Random/Sequence Containers

Interactive Music Example

Now let's dig a bit into some code. We will create a playable Interactive Music structure with a Music Switch Container, Music Playlist Containers, Music Segments, Music Tracks, Music Cues, and Music Transitions. If you want to follow along with the code, you can download the entire example from GitHub:

https://gist.github.com/ak-brodrigue/b98d12e67167eb0e00291cd9c2c02164

The example uses ak.wwise.core.object.set to create the entire music structure in one unique WAAPI call. Note that we also import audio files during the structure creation. This wasn't possible in earlier versions of Wwise.

Let's start with the concept of an object definition. When calling ak.wwise.core.object.set, you pass object definitions to the function. The minimum object definition is the following fields:

• type: type of the object as found in https://www.audiokinetic.com/en/library/edge/?source=SDK&id=wobjects_index.html. 
• name: name of the object. (this can be empty for some object types.)

Then, the object definition can optionally include these fields:

• children: defines an array of other object definitions. 
• import: defines which audio files to import into the object. (NEW in 2023.1)
• property, reference or list values, like the Volume or OutputBus, prefixed with @.

To make things a bit easier, I wrote a generic utility function in Python that takes care of generating the necessary JSON code corresponding to the object definitions passed to ak.wwise.core.object.set. You don't actually need to understand this function to use it. There are examples below that use it.

def Object(type, name, *children, **properties):

    # Basic definition
    definition = {
        "type" : type,
        "name" : name
    }

    # Take any keyword argument, and convert it to a property
    for key, value in properties.items():
        definition['@'+key] = value

    # Children can either be other definitions or file import instructions
    if len(children) > 0 and isinstance(children[0], str):
        # When we find a string as the first argument, we consider a file path
        definition["import"] = {}
        definition["import"]["files"] = []
        for file in children:
            definition["import"]["files"].append({ 
                    "audioFile" : file,
                })
    else:
        # Else, we consider an array of children definitions
        definition["children"] = children

    return definition

Also note that this leverages the Python argument system, where the first two arguments are fixed, while the other arguments are automatically converted to children or audio file import definitions. Lastly, the function also uses keyword arguments to define properties.

Let's introduce a specialized function to create a Music Segment, which re-uses the function above:

def MusicSegment(name, *children, **properties):
    #  Create the definition for a Music Segment
    return Object("MusicSegment", name, *children, **properties)

Now, we could use this function to create the definition of a Music Segment like this:

MusicSegment("Segment1",  
    R"C:\MyAudio.wav",
    Volume = -3)

Or, if we also want to have multiple Music Tracks, we could use:

MusicSegment("Segment1", 
    MusicTrack("TrackA", 
        R"C:\TrackA.wav",
        Volume = -2
        ),
    MusicTrack("TrackB", 
        R"C:\TrackB.wav", 
        Volume = -2
        )  
    )

Creating a Music Playlist Container would not be much different. However, this time, we need to specify the playlist itself. Note in the example below, we are setting the PlaylistRoot on the container, which is a tree of Playlist Items. We are also setting the LoopCount and Segment on the different Music Playlist Items:

MusicPlaylistContainer(
    R"MPL1",
    MusicSegment("Segment1", R"C:\Segment1.wav"),
    MusicSegment("Segment2", R"C:\Segment2.wav"), 
    PlaylistRoot = 
        MusicPlaylistItem(
            MusicPlaylistItem( Segment = root + "\MSC\MPL1\Segment1"),
            MusicPlaylistItem( Segment = root + "\MSC\MPL1\Segment2"),
            LoopCount = 0 
            )
    )

Finally, to create the Music Switch Container, we need to associate the Switches with children. This is done through the first two arguments in the MusicSwitchContainer function. I encourage you to take a look at the implementation, which takes care of the details of associating the Switches with the children.

MusicSwitchContainer(root + R"\MSC",
    # The switch groups on which the music container is subscribed
    [
        R"\Switches\Default Work Unit\SWG_1", 
        R"\Switches\Default Work Unit\SWG_2"
    ],
    # The association entries
    {
        R"SW_1_1.SW_2_1": R"MPL1",
        R"SW_1_2.SW_2_1": R"MPL1",
        R"*.SW_2_2": R"MPL2",
    },
    # The children
    MusicPlaylistContainer("MPL1", ...),
    MusicPlaylistContainer("MPL2", ...),

Finally, all those definitions are passed to ak.wwise.core.object.set in WAAPI. The entire tree of definitions dictates how to create the music structure.

What’s Next?

The new WAAPI features in Wwise 2023.1 are there to explore. We would like to know what you think of them, and we hope they will be useful to you. What will you build from this? We are always interested to hear about what people are doing with our product.

Is there anything else you would like to see in WAAPI in the future? Please let us know in the Q&A with the Beta Feedback category.

If you are interested in learning WAAPI but you don't know where to start, you can refer to the following links:

• Getting started with WAAPI (https://www.audiokinetic.com/en/library/edge/?source=SDK&id=waapi_gettingstarted.html) - Overview and examples for the different programming languages we support.
• WAAPI Reference (https://www.audiokinetic.com/library/edge/?source=SDK&id=waapi_functions_index.html) - Learn the details of each WAAPI function.
• ak.wwise.core.object.set (https://www.audiokinetic.com/library/edge/?source=SDK&id=ak_wwise_core_object_set.html) - Learn more about ak.wwise.core.object.set.
• Importing Audio Files and Creating Structures (https://www.audiokinetic.com/library/edge/?source=SDK&id=waapi_import.html) - Learn how to create Wwise structures.
• Wwise Object Reference (https://www.audiokinetic.com/library/edge/?source=SDK&id=wobjects_index.html) - Learn about Wwise objects and their properties.