Guide: Output Format Selection

This guide explains how to support different output formats in your application, such as stereo, binaural, and 5.1, and how to let the end-user select between them at runtime.

Introduction

Some users play with headphones, some with a stereo speaker setup, and some even have a 5.1 surround system. To provide the best audio experience for all of them, you might want to support different output formats in your application, such as stereo, binaural, and 5.1.

Each of these output formats requires a different spatialization technique and different bus widths. For example, stereo output requires a stereo bus, while 5.1 output requires a 5.1 bus.

The Spatializer and Renderer support all output formats, and even allow for switching between them at runtime without any additional routing in FMOD, or complex scripting in the game engine. No need for separate banks or additional buses for each output format. You don't even need to restart your events when switching between output formats.

The basic idea is the following: Whenever the user decides to switch the output format, you call the Platform Format API letting all¹ Spatializer and Renderer instances know that the output format has changed. The Spatializer and Renderer will then notify the FMOD routing system and request the correct bus width.

Prerequisites

This guide assumes you have a basic understanding of FMOD Studio and Unity. It also assumes that you have installed the atmoky TrueSpatial plug-ins, and have downloded both the FMOD Unity Integration and the atmoky TrueSpatial FMOD Unity Integration.

FMOD Studio Project Setup

Let's begin with a simple FMOD Studio project that contains a single event we will spatialize using the Spatializer. We will also test our setup within FMOD Studio to make sure everything is working as expected.

In a fresh FMOD Studio project, create a new event and add a single audio file to it. Name the Event MyEvent and assign it to the Master bank. Add the Spatializer effect to the master track of the event.

Per default, the output is set to Binaural. You can see how the number of channels changes when you switch between the different output formats in the Spatializer effect.

As we want to switch between the different output formats at runtime, we need to set the output format of the Spatializer to Platform. This way, the Spatializer will use the current platform setting and update the bus width accordingly.

To test this within FMOD Studio, we need to add another platform to the project. In the FMOD Preferences, we a new platform called Stereo and set the Surround speaker mode to Headphones.

Now instead of changing the output format, we can change the Platform in the lower right corner of FMOD Studio. When you switch to the Stereo platform, you will see that the bus width changes accordingly.

While we are at stereo, let's use the 3D Preview to position the source left of the listener and see how the output changes when toggle the 2Ch to Binaural button.

Disabled, only the left output channel will hold signal, however with binaural enabled, the signal is distributed to both channels, creating a more realistic sound experience as the source's sound will also reach the right ear of the listener.

As both Stereo and Binaural use two channels, this button is needed to tell the plug-ins what spatialization technique to use. In order to later control this button from Unity, we need to expose it to the game engine. To do this, we right-click on the button and select Add Automation. In the Automation & Modulation tab we add a new Parameter by clicking Add Curve -> Browse -> New Parameter.

As we want it to control all instances of the event we set it to be global . We also name it Binaural and set the range to 0 and 1. The result should look something like this:

Note: You can also use a local parameter if you only want to control the binaural button for a single event instance.

When we now change the value of the Binaural parameter, we will see how the button changes its state and also hear and see how the output changes between stereo and binaural.

That's it! Let's build the project by running File -> Build All Platforms and save the project.

Next up: Unity Integration.

Unity Integration

Setup

Let's first create a new Unity project and setup both the FMOD Unity Integration ↗ (opens in a new tab) and the atmoky trueSpatial integration.

In the FMOD setup wizard, we select FMOD Studio Project and point it to the FMOD Studio project we've created earlier. After installing the atmoky integration, we import the runtimes by clicking atmoky -> Import Runtimes in the menu bar and add atmokyTrueSpatial to the Dynamic Plugins list in the FMOD settings (Platform Specific -> Editor/Default)

After setting up both integrations, we add a Sphere to the scene for a visual reference and attach an FMOD Studio Event Emitter to it. We assign the MyEvent to the emitter and select Object Start as the Play Event. Press play and you should hear the sound coming from the sphere.

Platform Switcher

Now let's add a platform switcher to the scene. We create a new empty GameObject and attach a new script called PlatformSwitcher to it. The script should look like this:

using UnityEngine;
using FMODUnity;
using Atmoky;
 
public class PlatformSwitcher : MonoBehaviour
{
    enum Format
    {
        Stereo,
        Binaural,
        FivePointOne
    }
 
    void Start()
    {
        SetPlatform(Format.Stereo);
    }
 
    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Alpha1))
        {
            SetPlatform(Format.Stereo);
        }
        else if (Input.GetKeyDown(KeyCode.Alpha2))
        {
            SetPlatform(Format.Binaural);
        }
        else if (Input.GetKeyDown(KeyCode.Alpha3))
        {
            SetPlatform(Format.FivePointOne);
        }
    }
 
    void SetPlatform(Format selection)
    {
        if (selection == Format.Stereo)
            Debug.Log("PlatformSwitcher: Setting Stereo");
        else if (selection == Format.Binaural)
            Debug.Log("PlatformSwitcher: Setting Binaural");
        else if (selection == Format.FivePointOne)
            Debug.Log("PlatformSwitcher: Setting Surround");
 
        if (selection == Format.FivePointOne)
            Atmoky.Platform.SetFormat(PlatformFormat.FivePointOne);
        else
            Atmoky.Platform.SetFormat(PlatformFormat.StereoOrBinaural);
 
        var binauralValue = selection == Format.Binaural ? 1 : 0;
        RuntimeManager.StudioSystem.setParameterByName("Binaural", binauralValue);
    }
}

On startup, the script sets the platform to Stereo. When pressing 1, 2, or 3, the platform is set to Stereo, Binaural, or 5.1 respectively. The Binaural parameter is set to 1 when the platform is set to Binaural, and 0 otherwise.

There's one important step left to do: We need to start the FMOD engine with the highest bus width we want to support. To do this, we go to the FMOD Settings and in the Platform Specific settings we set the Project Platform to Surround 5.1. The settings should look like this:

When we now hit play, we can switch between the different output formats by pressing 1, 2, or 3. You should see the log messages in the console and hear the output change accordingly.

Conclusion

That's it! You have successfully set up a project that supports different output formats and allows the end-user to switch between them at runtime.