Wwise Unity Integration Documentation

As of version 2018.1, support for the Wwise Authoring API (WAAPI) is built into the Unity integration (for more information, refer to Using the Wwise Authoring API (WAAPI)). In version 2021.1, the Wwise Authoring API (WAAPI) was redesigned for better integration with the Wwise Picker and overall ease of use. More information about how WAAPI is used with Wwise Picker is found on its documentation page: Wwise Picker.

WAAPI Settings

WAAPI settings are found in Project Settings > Wwise Integration > Wwise Authoring API .

If the Connect to Wwise checkbox is unchecked, WAAPI functionalities will be disabled. By default, the WAAPI client will connect to port 8080 on the localhost (127.0.0.1). Changing these settings while WAAPI is connected will close the current connection and attempt to connect to the new target address.

Troubleshooting

Here are some potential solutions if you are having issues connecting to a project:

Check that you have opened the correct project in Wwise Authoring.
Check that the Wwise Project Path in Project Settings > Wwise Integration > Wwise Project is correct.
If you have multiple Wwise Authoring instances open, one of them might block the WAAPI port of the other.
Check that WAAPI is enabled in Wwise Authoring and that your allowed connections and port are correct
- WAAPI settings are found in User Preferences.

Using WAAPI in Unity

The AKWaapiClient class uses a websocket connection to send and receive messages with Wwise Authoring. WAAPI messages are JSON objects. WAAPI calls are asynchronous, and because calls to WAAPI may come from threads such as the GUI thread, we cannot wait for their response. The websocket implementation can also only wait for one response at a time, so the WAAPI client is wrapped by the AkWaapiUtilities class. This class provides a set of functions to create and enqueue WAAPI requests and then calls them sequentially during its update loop. WAAPI requests are encapsulated in a WaapiCommand, which simply contains an asynchronous function pointer payload. When a command is consumed, its payload is executed.

The functions provided in AkWaapiUtilities should address most of your needs, but if you have a specific use for WAAPI that is not built in, you can still implement it yourself. Refer to Other WAAPI Commands for details.

Caution: Most of the provided WAAPI calls use the Wwise Authoring Query Language (WAQL). For more information about WAQL, refer to the WAQL introduction and reference pages.

Fetching Wwise Objects Using Waapi

AkWaapiUtilities already contains built-in WAAPI calls for fetching Wwise objects:

These will return a list of objects that contain the properties specified in the return options. A complete list of return options is found in the WAAPI documentation.

The Wwise Picker uses the WwiseObjectInfoJsonObject as the template type for these functions. These objects are then cast to WwiseObjectInfo by AkWaapiUtilities.ParseObjectInfo.

If you want to fetch object properties not contained in WwiseObjectInfo, you will need a custom class for the properties you wish to access. For example, if you are only interested in the Notes field you could create a class as follows:

public class WwiseObjectNotes 
{
    public string notes;
}

Then we can call AkWaapiUtilities.GetWwiseObject<T> (or any of the other functions listed previously) with a ReturnOptions object listing only the notes field and a callback accepting a list of WwiseObjectNotes.

{
    var callback = ( List<WwiseObjectNotes> notes ) => { 
        // do something 
        };
    var options = new ReturnOptions(new string[] { "notes" });
    var objectGuid =  System.Guid.Empty(); //Put an actual guid from your project here
    AkWaapiUtilities.GetWwiseObject<WwiseObjectNotes>( objectGuid, options, callback);
}

The AkWwiseTreeWAAPIDataSource class contains many examples of using WAAPI to fetch Wwise objects to populate the Wwise Picker.

Subscribing to Topics

Use AkWaapiUtilities.Subscribe to subscribe to a WAAPI topic. The URI identifies the topic being subscribed to. The callback argument is the function accepting a JSON string argument to be called when the topic is published. The handshakeCallback is called when the subscription is successfully registered. It receives a AkWaapiUtilities.SubscriptionInfo object which contains the subscription identifier. The class that requested the subscription should store this information.

Caution: The class calling AkWaapiUtilities.Subscribe is responsible for cleaning up its subscriptions at the end of its lifetime. This is done by calling AkWaapiUtilities.Unsubscribe.

For an example of subscriptions used in the integration, see the AkWwiseTreeWAAPIDataSource class.

AkWwiseTreeWAAPIDataSource.SubscribeTopics
AkWwiseTreeWAAPIDataSource.UnsubscribeTopics

More information on the available topics is found in the >Wwise Authoring API Reference.

Most topic URIs are found in Uri.cs

Disconnection

When the WAAPI connection is about the be closed (or has been abruptly closed), the AkWaapiUtilities.Disconnection delegate is called. The boolean parameter of the delegate indicates whether the connection is still alive.

Note:

Classes that subscribe to WAAPI topics should bind to this delegate so that they can unsubscribe before the connection is lost.

Other WAAPI Commands

The AkWaapiUtilities class contains the following additional functions that allow you to interact with your WAAPI project from within Unity:

You can find examples of these commands being used in AkWwisePicker and AkWwiseTreeView .

If the WAAPI command you want to execute is not already implemented in AkWaapiUtilities, you are still able to create your own commands. In order to make WAAPI calls and receive responses, JSON arguments must be constructed and parsed.

For commands with nothing to parse from their response, use AkWaapiUtilities.QueueCommand

For commands with values to parse from their response, use AkWaapiUtilities.QueueCommandWithReturnType<T>

The Unity JsonUtility class makes it easy to translate between C# classes and JSON strings. Use JsonSerializable as a base class for arguments and options that must be converted to a JSON string.

public class JsonSerializable
{
    public static implicit operator string(JsonSerializable o) => UnityEngine.JsonUtility.ToJson(o);
}

This class can then be extended to provide C# wrappers for specific WAAPI schemas. For examples of how these can be used, see how we created the necessary schema classes to play Events and subscribe to transports using WAAPI:

Arguments and options schemas

Returned object schemas

You can see how they are used in AkWaapiUtilities.TogglePlayWwiseEventAsync and AkWaapiUtilities.CreateTransport.

JsonSerializable

Base class for Json serializable objects. Implements implicit cast to string using UnityEngine....

Definition: AkWaapiHelper.cs:27

ReturnOptions

WAAPI options to specify the names of fields to return in a WAAPI request returning WwiseObjects.

Definition: AkWaapiHelper.cs:150

AkWaapiUtilities

This class wraps the client that communicates with the Wwise Authoring application via WAAPI....

Definition: AkWaapiUtilities.cs:34

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.

Get started with Wwise

Wwise Unity Integration

WAAPI Utilities