Playing FMOD Events in Unity

Playing FMOD Events in Unity isn’t particularly difficult, but we do have a number of methods available that might make more or less sense depending on our game or application. In this tutorial, we’ll take a closer look at how to play FMOD events in Unity.

Download the Unity & FMOD project for this tutorial. If you get any errors after opening the project, please delete the FMODStudioCache.asset file, as it will still contain the old path to the FMOD Studio Project.

Check out the video version of this tutorial:

How to play FMOD Events in Unity?

FMOD events in Unity can be played in three different ways:

1. Using the FMOD Studio Event Emitter Component
2. Using the PlayOneShot helper method in the code.
3. By manual declaration and start/stop of the event in the code.

All possibilities have practical advantages and disadvantages:

• The Event Emitter allows us to play events without code. In combination with the Studio Parameter Trigger component we can additionally change parameters.
• With PlayOneShot we can play a sound with one line of code. FMOD automatically takes care of the playback and stops or frees the sound instance from main memory. A disadvantage of this method is that no parameter changes are possible without modifying FMOD’s RuntimeManager source code. If the sound is to be changed by an in-game parameter, then PlayOneShot is not suitable. However it is very easy to overload the PlayOneShot method in code to make this possible. Read the tutorial about using PlayOneShot with FMOD Parameters if you wish to do so.
• The manual playback of sounds, on the other hand, requires more code, but is much more flexible to manipulate, since you can define exactly when a sound or loop should be played and stopped, and where parameter changes should be made.

Playing FMOD Events with the Studio Event Emitter Component

For an easy playback of events we create a new GameObject and insert the Studio Event Emitter Component:

Here we find various setting options that we change to influence the playback of events. Under Play Event and Stop Event we determine when the event should be played and stopped. In Event we select the event from a list of events that we have previously built. Go into Play Mode, activate and deactivate the created GameObject to hear the sound.

PlayOneShot

The PlayOneShot method immediately create, plays and releases an instance of an FMOD event. The PlayOneShotAttached method creates an instance of an event at a specific location. The event will play to the end and parameters cannot be set. If we need to set a parameter when using PlayOneShot, we can easily modify FMOD’s RuntimeManager code. Follow the tutorial about using PlayOneShot with FMOD Parameters if you need this behaviour. The code for PlayOneShot is:

FMODUnity.RuntimeManager.PlayOneShot("event:/Example");

event:/Example is a path that refers to an event we create in FMOD Studio. The paths follow the folder structure in the FMOD Studio event hierarchy. Alternatively, you can right-click on an event in FMOD Studio to copy its path.

We insert this code into the Update() method of the script. In the if statement, we check if the space bar is pressed. If this is the case, the sound will be played back:

if (Input.GetKeyDown(Keycode.Space))
{
FMODUnity.RuntimeManager.PlayOneShot("event:/Example");
}

The complete code looks like this:

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

public class PlayOneShotExample : MonoBehaviour
{

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            FMODUnity.RuntimeManager.PlayOneShot("event:/Example");
        }
    }
}

If you are now in Unity’s play mode and press the space bar, you will hear the sound you inserted in the sample event. In the upper left corner you will also see a small FMOD debug window showing the volume levels in RMS and the number of voices playing.

What is the difference between an FMOD Event and an instance?

An event is a sound unit that you create in FMOD Studio. It can have various tracks, parameters and automations. A copy or instance of the event is created in-game. You don’t start the event itself, but you create an instance from that event. This allows you to have multiple copies of an event playing at the same time.

Playing and controlling FMOD Events manually using C# code

Four steps are necessary to manually play and control an event in Unity:

1. We need to declare an instance.
2. Tell Unity when an instance of the FMOD event should be created and where the event is located.
3. Start or stop the instance.
4. Free the instance from memory.

Let us now go through these steps one by one.

Declaring an FMOD instance

We must declare all events that will be used in this script as an instance before proceeding. In our case, we enter this line in our code:

private FMOD.Studio.EventInstance instance;

Creating an FMOD instance

In the Start() method of the script we now create our instance:

void Start() 
{ 
instance = FMODUnity.RuntimeManager.CreateInstance("event:/Example");
}

Playing back the FMOD EventInstance

After that the sound can be played back by using the code line instance.start(). I also put the line in the Update() method under an if statement, so that the sound is only played when we press the spacebar:

if (Input.GetKeyDown(KeyCode.Space)) 
{
instance.start();
}

If you look again at the FMOD debug window in the upper left corner, you will probably notice that pressing the spacebar several times will only play just one instance of the event compared for example to PlayOneShot. The sound will be cut off each time. This happens because we created the instance in the Start() method. This method is executed once when the game starts. If we want to have a separate instance for each sound played, we must also move the instance creation code in the If-Statement block.

Attention: With this manual method, instances are not automatically freed from memory. This can cause problems. We add the code instance.release() after playing the instance, so that the instance is cleared.

The complete code for the script looks like this:

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

public class ManualExample : MonoBehaviour
{

    private FMOD.Studio.EventInstance instance;

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            instance = FMODUnity.RuntimeManager.CreateInstance("event:/Example");
            instance.start();
            instance.release();
        }
    }
}

How to play FMOD loops in Unity?

Loops can be played most safely using the manual method. But how do we create loops and how do we stop them?

Let’s go back to FMOD Studio and look at the LoopEvent in the project. A loop region can be created by right-clicking on the timeline and selecting the “Add Loop Region” entry:

Then we can move the loop region as much as we want, similar to some DAW’s. Move the loop region to include the whole audio file, save and build the project.

In the Unity project, start the loop scene and press the spacebar. You will notice that the sound is now looped.

How to stop FMOD loops in Unity?

With the code line:

instance.stop(FMOD.Studio.STOP_MODE.ALLOWFADEOUT);

the instance can be stopped. In our Update() method we insert an If-statement which stops our sound when pressing the left control key (CTRL):

if (Input.GetKeyDown(KeyCode.LeftControl))
{
instance.stop(FMOD.Studio.STOP_MODE.ALLOWFADEOUT);
instance.release();
}

STOP_MODE.ALLOWFADEOUT respects the release time in the ADSR modulation of the event (if any present). If we want an abrupt stop, we use STOP_MODE.IMMEDIATE instead.

The complete code for a loop looks like this:

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

public class LoopExample : MonoBehaviour
{
    private FMOD.Studio.EventInstance instance;

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            instance = FMODUnity.RuntimeManager.CreateInstance("event:/LoopEvent");
            instance.start();
        }

        if (Input.GetKeyDown(KeyCode.LeftControl))
        {
            instance.stop(FMOD.Studio.STOP_MODE.ALLOWFADEOUT);
            instance.release();
        }
    }
}

We can now start the loop alternately with the space bar and stop our sound with the left CTRL key. Try it out!

Playing 3D FMOD Events in Unity

3D Events differ from 2D Events in that they play a 3D sound with spatialization (Spatializer effect). The effects adds volume attenuation based on the distance from the instance to the listener, and a panning based on the position of the instance in the direction in which the listener is directed.

An event doesn’t necessarily need a spatialization effect to be a 3D event. It can also use built-in parameters (such as distance, direction, etc.) to automate properties such as volume and filters to give the impression of spatialization.

In FMOD Studio, a 2D event can be easily converted to a 3D event by adding the Spatializer effect to the master track of an event:

You can find in-depth information about the spatializer effect in the FMOD documentation. I will list the most important features here:

• Min & Max Distance and Distance Attenuation Curve: The Min and Max distance properties and the Distance Attenuation curve of the Spatializer determine together how much the signal is attenuated at different distances. The signal is not attenuated if the listener is within the minimum distance of the spatializer, is -oo dB if the listener is outside the maximum distance, and drops according to a linear quadratic curve as the listener moves from the minimum distance to the maximum distance. Depending on the curve, the signal drops off differently.
• Envelopment: Envelopment determines the extent of the event at any distance from the listener. The Auto mode sets the minimum expansion to 0 degrees and sets the Sound Size to twice the Min-Distance property of the Spatializer.
• The User mode allows us to manually set the sound size and minimum expansion of the Spatializer, and the Off Mode disables the sound size and minimum expansion.

In the code itself, we only need to make one minor change, namely to tell FMOD where the instance is located in 3D space. We also have two different options here. Either we do this directly in the Update() method of a script with this line of code:

instance.set3DAttributes(FMODUnity.RuntimeUtils.To3DAttributes(gameObject));

Or we append the information to the GameObject once after we have created the instance:

FMODUnity.RuntimeManager.AttachInstanceToGameObject(instance, GetComponent<Transform>(), GetComponent<Rigidbody>());

Depending on whether the GameObject has a RigidBody, we can use one or the other method. The second method uses the RigidBody to determine the velocity of the GameObject and to activate a doppler effect. The example code for a 3D event looks like this:

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

public class Event3DExample : MonoBehaviour
{
    private FMOD.Studio.EventInstance instance;

    void Start()
    {
        instance = FMODUnity.RuntimeManager.CreateInstance("event:/3DEvent");
        // FMODUnity.RuntimeManager.AttachInstanceToGameObject(instance, GetComponent<Transform>(), GetComponent<Rigidbody>()); 
        instance.start();
    }

    void Update()
    {        instance.set3DAttributes(FMODUnity.RuntimeUtils.To3DAttributes(gameObject));
    }
}

In the attached 3DEvent scene, use the WASD keys and the right mouse button to move into the room and listen to the changes in sound.