If you’ve never used the Wwise Authoring API (WAAPI) before, I’m hoping I can convince you to give it a shot with the rest of this article.

Yes, I know if you’re not a programmer WAAPI looks a little crazy and seems hard to understand, but stick with me.  Together (me writing and you reading), we’re about to create a sea change in the way you work.

I promise it’ll be worth your time.

What is the Wwise Authoring API?

Before I jump into the thick of why I love WAAPI and how it’s about to get easier for you, let's give you a refresher on what it is.

The Wwise Authoring API was released alongside Wwise 2017.1.  As its name suggests, it’s an API (application programming interface), meaning it is code that allows you to affect another program.  In our case, that program is the Wwise Authoring tool.

WAAPI allows for communication with Wwise over a network, sending packets of information back and forth.  To achieve this, it uses a method of communication called “WAMP” (Web Application Messaging Protocol), which is programming language agnostic.  That’s all a fancy way of saying you can use numerous different languages to write WAAPI code, and you can communicate with Wwise locally or over a network.

With WAAPI, you can do things like automating audio file imports, Event creation, large property changes, generating SoundBanks, and even creating your own custom GUIs (like your own mixer).  If you’re super crazy, you can even get multiple instances of Wwise to talk to each other (if you need to compare an older version of your project to a newer one, for instance—yes, I’ve done this).

Sounds pretty intriguing, right?

I agree; but, sadly, it’s not without its shortcomings.

Barriers of Entry

When I first saw WAAPI being introduced to Wwise users, I was a little taken aback.  The potential of this API blew my mind, and it still does! The amount of potential applications and workflow improvements is tremendous if you think only a bit outside the box.

But, I quickly saw that others didn’t quite… get it.

Audiokinetic has done an amazing job of showing how versatile WAAPI is—it can do a bunch of stuff! But, for many non-programmers, I’ve seen confusion over what exactly it is.  Where you might be expecting it to be “a new Wwise feature”, it’s actually a feature that gives you the ability to create your own custom features.

Once you wrap your brain around that, and start combing through the API documentation, two things happen:

• You get really excited about the possibilities.
• If you’re a novice programmer, it looks daunting and impossible to use.

That second one kills me.

Consider this scenario:

First, you learn about and understand what WAAPI can do and you get super excited about creating a new, useful feature—let’s say a tool that automatically generates your SoundBanks on a schedule.

Second, you jump into the API documentation.  At first, it seems straightforward enough—you understand the names of each function at least. But, when you get to the sample WAMP code, you get lost really quickly.

Third, because you’re a bit overwhelmed you think “This is a job for a programmer!” and you task a programmer with helping you create this new, wonderful idea you have.

Oh, wait…maybe you don’t have an available programmer.  Oops.

Or perhaps you have a programmer, but they’re too busy fixing important engine bugs or building new in-game user facing features.

And then, as cool as it all seems, WAAPI goes on the backburner super-fast.  You become one of the many people who should use this tech, who totally would use this tech, but the barrier of entry is slightly too high.

That is what I’ve set out to fix.

Overcoming these Barriers

With the help of people smarter than me, I set out with an initial goal of simply making WAAPI easier to use with C#.

That meant the following:

• Remove WAMP and JSON from the equation, and abstract (or “hide”) it away from the end-user.
• Lower the difficulty of using WAAPI, so that a technical sound designer or audio implementer can use it with ease and without much (if any) help from a programmer.
• Keep it similar enough to the existing WAAPI syntax so that a user can reference the WAAPI documentation for things like object properties (there is an exhaustive list of them).

I’ve spent a few weeks creating a “wrapper” (a layer of code that interacts with WAAPI directly so you don’t’ have to) called WaapiCS to accomplish all of the things above.  It’s available free under the MIT License (this means you can use it commercially, distribute it, and change it—you just need to attribute me as the original author) for you to use, right now.  You'll find the link to download the source at the bottom of this article.

To give you an idea of what this means for you practically, let’s compare some code side by side.

Calling ak.wwise.core.getInfo

Let’s take a look at the function call to “ak.wwise.core.getInfo”.  Sending this to Wwise returns general data about Wwise, such as what version you’re running and the path to the Wwise .exe.

The sample project code initially provided to you in the documentation looks something like this:

Using WaapiCS, all of that code now looks like this:

That’s it.  Calling “ak.wwise.core.GetInfo” gives you back a Dictionary that you can iterate through in a loop.  If you know a little bit about C# programming, you can handle this.

Programming Terminology

Before you go jump right in, I do want to explain exactly what I did and how it works.  Chances are if you’re planning on doing something even remotely extensive, you still might want to have a bit of assistance from a programmer.  If you’re not planning on editing the framework at all, you can probably skip this part.

Two Layers

WaapiCS is built with two layers in mind.  The lower layer “WaapiCS.Communication” handles the WAMP/JSON communication to and from Wwise.  It is built with a few simple objects:

• Connection – establishes the connection to Wwise if using a one-off call.
• Subscription – subscribes to a specific Wwise call and waits for a callback.
• Packet – is the object containing all the user’s arguments. This is sent and converted to JSON in the WAMP process.
• Results ­– is a general C# object that contains the results of any callback. Because Wwise may hand back various types of JSON, this is cast to a specific type when translating from JSON after the callback.

The “higher” layer (within namespace “ak”) is where the actual user-facing API calls live.  Every method is static in order to closely resemble the WAAPI syntax (this was my choice, and WaapiCS is built as such that this can be stripped out or changed).  The lower layer’s packet object is built from the arguments given by the user.  If Wwise gives back any return results, they’re returned back to the user at the end of the function call.  Here’s an example of what this looks like:

Above you’re looking at the call to “ak.wwise.core.remote.Connect”.  It takes a string argument, which is the host IP of the game you wish to remotely connect to. The rest of the code cleans out the packet object’s results (in case it has already been used), sets the procedure to use with WAAPI, adds the host IP to the packet, declares what function Wwise should call us back with, and then sends the packet to Wwise via “connection.Execute”.  When all of that is finished, the packet object gets cleared again for another use. This pattern is repeated similarly through each function in the API.

Understandably, this system of user-facing static calls may not—and likely will not—work for all teams. It’s for this reason that WaapiCS is built using multiple layers. The “lower” layer is robust enough in its communication with WAAPI via WAMP/JSON that it likely won’t need to be edited.  However, if your team has a different idea for how user-facing code works, you can completely strip away and/or rewrite the top layer as you please without affecting the WAMP communication layer.

What Can You Use This For?

In general, you can use WAAPI and WaapiCS to automate, batch, or recreate functions of the Wwise authoring tool, such as:

• Mass audio file import, and Event and SoundBank creation
• Large-scale project changes to parameters, bussing, etc.
• Automating or scheduling SoundBank generation
• Communicating between Wwise and various programs
• Creating custom control interfaces for the Wwise Authoring tool
• Batch creation of TTS VO and auto-import to Wwise

…among many, many other things.

As a proof of concept for WaapiCS, I’ve created a simple custom mix interface.

The above GUI is written in C# and could control the volume of any bus or object node within Wwise. Imagine having the “page” feature of today’s latest digital mixing consoles and being able to dive deep into your Wwise hierarchy and tweak a single object or a high level mix bus, all within a few clicks, in real time as Wwise is connected to your game. You could conceivably save custom “desk snapshots” to bring you back to specific sets of faders, sliders for specific properties or aux sends—the ideas are only limited to your imagination!

I realize the image doesn’t look like much (it’s a prototype), but this is super neat right? You can easily build your own custom mixer GUI outside of Wwise to look exactly like you want it to.

But, it doesn’t just have to be a prototype C# GUI. This can easily be built right into your game engine, be it Unity, Unreal, proprietary, or whatever. It could even be mapped to OSC, and you could be mixing Wwise right on your iPad or control surface!

Take Advantage

If you or your team haven’t thought about taking advantage of WAAPI yet, I hope you can see that you definitely should.  I’ve made WaapiCS available to you for free, and though it’s still a work in progress, you can download it right now and tweak it as you like. There are no commercial limitations and no fees.

If you find yourself in the spot like I described above, where you’d love to create these tools but don’t have the time or resources, please get in touch with me!  I’m taking on clients and I’d love to help you and make the Wwise platform even easier for you to use.