Table of Contents

Using the Wwise Unity Integration

The Integration provides Wwise-specific components you can use directly on Unity Scene GameObjects. These components should cover most sound design scenarios. While the components are custom C# scripts, no coding is required to edit their public properties.

Adding Wwise components

To add Wwise components to Unity GameObjects:

  • Go to the Unity Inspector window (Ctrl+3) loaded with the GameObject selected in the scene.
  • Click Add Component to prompt the Component list.
    Unity_AddWwiseComponent.png
  • Select Wwise to open its sublist and choose the desired Wwise components.
    Tip.gif
    Tip: Type "ak" in the component search field to more quickly access a list containing all the Wwise components.

Wwise components straight from the Wwise Picker

You can add components to your game by dragging Wwise objects from the Wwise Picker to either the Inspector or onto game objects listed in the Hierarchy of your loaded scene.

See also:

The WwiseGlobal object

The WwiseGlobal object is a GameObject that contains the Initializing and Terminating scripts for the Wwise Sound Engine. In the Editor workflow, it is added to every scene, so that it can be properly previewed in the Editor. In the game, only one instance is created, in the first scene, and it is persisted throughout the game. There are a few customizable options in the initializer script.

If you want to disable this behavior, use Edit > Wwise Settings and disable Create WwiseGlobal GameObject. It then becomes your responsability to add the initializer script on an object that will persist throughout the game.

Listener in Main Camera

In order for positioning to work, the Ak Audio Listener script needs to be attached to the main camera in every scene. By default the listener is added automatically to the main camera. If you want to disable this behavior, go to Edit > Wwise Settings and disable Automatically add Listener to Main Camera.

Wwise Types

This integration also provides a few classes that can be used, with minimal code, for most remaining usage scenarios:

  • AK.Wwise.AuxBus

  • AK.Wwise.Bank

  • AK.Wwise.CallbackFlags

  • AK.Wwise.Event

  • AK.Wwise.RTPC

  • AK.Wwise.State

  • AK.Wwise.Switch

  • AK.Wwise.Trigger

  • AK.Wwise.AcousticTexture

See also:

Wwise Authoring API (WAAPI) client

A native WAAPI client with a C# API allows you to connect to WAAPI from within Unity. It currently is available for Windows and macOS. The Wwise Authoring API sends messages via JSON objects. In Unity, the client was implemented using strings. You may use your preferred method to construct valid JSON strings to then give to the WAAPI client.

See also:

How to add a Wwise sound to a game object

There are four ways to add sounds to your game:

  • Using the Wwise Picker. This is the simplest way to add a sound to an object. Drag an Event from the Wwise Picker window to an object in the Unity Viewer or the Inspector. This automatically creates an AkAmbient component on the target Game Object.
  • Using the Add Component menu. Add an AkAmbient or an AkEvent component to any Unity Game Object.
  • Using Wwise Types. Call AK.Wwise.Event.Post() at any time from a C# script.
  • Using scripts. Call AkSoundEngine.PostEvent() at any time from a C# script.

Using Wwise with Unity Timeline

For Unity's Timeline feature, there are custom Wwise tracks for triggering Wwise events and setting Wwise RTPC values.

See also:

Using the Unity WAAPI client

The Unity integration includes a simple WAAPI client that can be used to interface with the Wwise Authoring tool.

See also:

Using C# code to control the sound engine

Most Wwise SDK functions are available in Unity through the AkSoundEngine class. Think of it as the replacement of C++ namespaces AK::SoundEngine, AK::MusicEngine, and so on. See API Changes and Limitations for changes made in the API binding compared to the original SDK. For more complex situations, you'll need to call Wwise functions from code. In the API, the GameObjectID in all functions is replaced by the Unity flavor of the GameObject. At runtime, an AkGameObj component is automatically added to this GameObject, unless you have already manually added it before.

Using numeric IDs instead of strings for Events and Banks.

The native Wwise API allows you to use strings or IDs to trigger events and other named objects in the Wwise project. You can still do this in the C# world by converting the file Wwise_IDs.h to Wwise_IDs.cs. Click Assets > Wwise > Convert Wwise SoundBank IDs. You need to have Python installed to make this work.

Sending MIDI to Wwise.

MIDI can be sent to Wwise by filling the AkMIDIPost members of AkMIDIPostArray class and calling any of the following methods:

  • AkMIDIPostArray.PostOnEvent()
  • AkSoundEngine.PostMIDIOnEvent()
  • AK.Wwise.Event.PostMIDI()

The following is a basic script that sends MIDI messages to the sound engine:

public class MyMIDIBehaviour : UnityEngine.MonoBehaviour
{
    public AK.Wwise.Event SynthEvent;

    private void Start()
    {
        AkMIDIPostArray MIDIPostArrayBuffer = new AkMIDIPostArray(6);
        AkMIDIPost midiEvent = new AkMIDIPost();

        midiEvent.byType = AkMIDIEventTypes.NOTE_ON;
        midiEvent.byChan = 0;
        midiEvent.byOnOffNote = 56;
        midiEvent.byVelocity = 127;
        midiEvent.uOffset = 0;
        MIDIPostArrayBuffer[0] = midiEvent;

        midiEvent.byOnOffNote = 60;
        MIDIPostArrayBuffer[1] = midiEvent;

        midiEvent.byOnOffNote = 64;
        MIDIPostArrayBuffer[2] = midiEvent;

        midiEvent.byType = AkMIDIEventTypes.NOTE_OFF;
        midiEvent.byOnOffNote = 56;
        midiEvent.byVelocity = 0;
        midiEvent.uOffset = 48000 * 8;
        MIDIPostArrayBuffer[3] = midiEvent;

        midiEvent.byOnOffNote = 60;
        MIDIPostArrayBuffer[4] = midiEvent;

        midiEvent.byOnOffNote = 64;
        MIDIPostArrayBuffer[5] = midiEvent;

        SynthEvent.PostMIDI(gameObject, MIDIPostArrayBuffer);
    }
}

Using the Audio Input Source Plug-in in Unity.

The audio input source plug-in can be used via C# scripting. See Audio Input Source Plug-in from the Wwise SDK documentation.

The following is a basic script that sends a test tone to the audio input source plug-in:

public class MyAudioInputBehaviour : UnityEngine.MonoBehaviour
{
    public AK.Wwise.Event AudioInputEvent;
    public uint SampleRate = 48000;
    public uint NumberOfChannels = 1;
    public uint SampleIndex = 0;
    public uint Frequency = 880;
    private bool IsPlaying = true;

    // Callback that fills audio samples - This function is called each frame for every channel.
    bool AudioSamplesDelegate(uint playingID, uint channelIndex, float[] samples)
    {
        for (uint i = 0; i < samples.Length; ++i)
            samples[i] = UnityEngine.Mathf.Sin(Frequency * 2 * UnityEngine.Mathf.PI * (i + SampleIndex) / SampleRate);

        if (channelIndex == NumberOfChannels - 1)
            SampleIndex = (uint)(SampleIndex + samples.Length) % SampleRate;

        // Return false to indicate that there is no more data to provide. This will also stop the associated event.
        return IsPlaying;
    }

    // Callback that sets the audio format - This function is called once before samples are requested.
    void AudioFormatDelegate(uint playingID, AkAudioFormat audioFormat)
    {
        // Channel configuration and sample rate are the main parameters that need to be set.
        audioFormat.channelConfig.uNumChannels = NumberOfChannels;
        audioFormat.uSampleRate = SampleRate;
    }

    private void Start()
    {
        // The AudioInputEvent event, that is setup within Wwise to use the Audio Input plug-in, is posted on gameObject.
        // AudioFormatDelegate is called once, and AudioSamplesDelegate is called once per frame until it returns false.
        AkAudioInputManager.PostAudioInputEvent(AudioInputEvent, gameObject, AudioSamplesDelegate, AudioFormatDelegate);
    }

    // This method can be called by other scripts to stop the callback
    public void StopSound()
    {
        IsPlaying = false;
    }

    private void OnDestroy()
    {
        AudioInputEvent.Stop(gameObject);
    }
}

Apply Custom Positioning in Unity

By default, the AkGameObj component is attached to a specific Unity gameObject and uses its transform (with an optional offset) for full positioning. This is usually adequate for many games, such as first-person shooters. However, games with custom camera angles, such as many third-person games, may find it difficult to accommodate the two aspects of positioning (distance attenuation and spatialization) by simply attaching the audio listener to one game object, such as the main camera in Unity. Other games may want players to experience other custom positioning.

To this end, the AkGameObj component class provides overridable positioning to Unity users. Through the three virtual methods GetPosition(), GetForward(), and GetUpward(), users can derive a subclass from AkGameObj and use that subclass component to customize any number of Unity gameObjects' positioning.

Here is a simple example of how to use a custom component to override the default AkAudioListener behavior. With a third-person project integrated with Wwise, remove the existing AkAudioListener and its associated AkGameObj. Then attach the following script to the MainCamera object, attach AkAudioListener, and finally specify the target Unity gameObject (such as the player avatar) that the audio listener's position will follow. After this, the distance attenuation of all the emitters will rely on the selected target Unity gameObject's position as the listener position (an on-screen distance listener), while the orientation of all the emitters is still based on the main camera orientation as the listener orientation (an off-screen orientation listener).

#if ! (UNITY_DASHBOARD_WIDGET || UNITY_WEBPLAYER || UNITY_WII || UNITY_WIIU || UNITY_NACL || UNITY_FLASH || UNITY_BLACKBERRY) // Disable under unsupported platforms.

//
// Copyright (c) 2017 Audiokinetic Inc. / All Rights Reserved
//

using UnityEngine;
using System;
using System.Collections.Generic;


[AddComponentMenu ("Wwise/AkGameObj3rdPersonCam")]
[ExecuteInEditMode] //ExecuteInEditMode necessary to maintain proper state of isStaticObject.
public class AkGameObj3rdPersonCam : AkGameObj
{
    public Transform target;            // The position that this camera will be following. User can specify this to the player character's Unity gameObject in the Inspector.

    
    // Sets the camera position to the player's position to handle distance attenuation.
    public override Vector3 GetPosition ()
    {
        return target.GetComponent<AkGameObj> ().GetPosition ();
    }

}
#endif // #if ! (UNITY_DASHBOARD_WIDGET || UNITY_WEBPLAYER || UNITY_WII || UNITY_WIIU || UNITY_NACL || UNITY_FLASH || UNITY_BLACKBERRY) // Disable under unsupported platforms.
Generated on Wed Sep 18 17:38:57 2019 for Wwise Unity Integration by  doxygen 1.6.3