Unity Audio Syntax

Introduction

This project was initially just a wrapper for FMOD, but I realised that the FMOD-Syntax workflow would also be useful for projects using Unity's native audio system.

Because of that, the FMOD-Syntax package is superceded by an Audio-Syntax package, which supports both FMOD Syntax and Unity Audio Syntax solutions.

Here's more information on how Unity Audio Syntax works and how its workflow differs from FMOD Syntax.

Setup

There is one unified setup flow for Audio Syntax, and it will let you decide whether to use FMOD Syntax, Unity Audio Syntax, or both.

Access the Setup Wizard via the Audio Syntax > Setup Wizard menu.

All of the settings that are relevant to FMOD Syntax are relevant to Unity Audio Syntax as well and reside in a AudioSyntaxSettings Scriptable Object.

Unity Audio Syntax also has settings that unique to that system, and some of them are serialized references that need to be accessed at runtime. Because of that, Unity Audio Syntax has its own settings file that must be accessible via the Resources folder. The Setup Wizard guides you through the process of setting this up.

Tip

If you are using Scriptable Object Collection (which I highly recommend) you can make the management of Timeline Events and Tags easier. For tags you can also enable the optional USE_COLLECTION_ITEM_PICKER_FOR_TAGS scripting define symbol and then you can use a nice picker for the tags instead of the regular serialized field.

General Workflow

• In Unity Audio Syntax, you define your Audio Events via Scriptable Objects. More info on that in Defining Audio Events

• It is up to you to decide how these audio event Scriptable Objects are supposed to be loaded. If this is a very small project, like a prototype for example, then it might be fine if all the audio is loaded up front and you can place all the Audio Event configs somewhere inside a Resources folder. If you know this is going to be a bigger project then you might want to load specific groups of Audio Event configs at specific times. More on that in Loading Audio Events via Addressables.

• You can reference Audio Events via an AudioReference serialized field and call the Play method on them, or you can generate code and play the Audio Event using strongly-typed code, such as AudioEvents.Player_Jump.Play(transform);. More on that in Generating code for accessing Audio Events.

• In the case of looping Audio Events, you are expected to cache the return value of a Play method (a Playback instance), and call Stop or FadeOut when you are done with it, and Cleanup in OnDestroy in case the MonoBehaviour that owns the loop is suddenly destroyed, such as when the scene is exited.

• You are expected to call AudioSyntaxSystem.Update from an Update function somewhere, and this will update the system and do things like automatically culling Playback instances that have finished.

Defining Audio Events

There are various types of Audio Events and ways to define them. Let's go over them:

One-Off Audio Events

Most Audio Events are supposed to only play once and are fire-and-forget. These are called One-Offs and you create them via Create > Audio > Event (One-Off).

They may be fired in quick succession so they offer some useful features for randomization such as selecting an Audio Clip randomly or randomizing the pitch / volume.

Looping Audio Events

Some Audio Events, like music, are expected to keep playing until you tell them to stop. These are called Loops and you create them via Create > Audio > Event (Looping).

When you play them, you should cache the Playback instance that is returned, and call Stop or FadeOut on it when you are done with it, and Cleanup in OnDestroy in case the MonoBehaviour that owns the loop is suddenly destroyed, such as when the scene is exited.

Note that you can also define Start and End audio. These are basically one-offs that happen automatically when the loop starts or ends, instead of having to define separate events for that.

Create Audio Events automatically from Audio Clips

Often you import a bunch of Audio Clips into your project, and then you want to create corresponding Audio Events for them. If you're consistent with your folder structure and naming conventions, then Audio Syntax can do a lot of this work automatically for you.

If your Audio Clips are located in a folder such as _Game/Audio/Player/Jump.wav then you might want to create a config in _Game/Configs/Audio/Events/Player/Jump.asset. If you make sure that Audio Clip Folders Mirror Event Folders is enabled in your Unity Audio Syntax Settings file and specify _Game/Audio as the root folder for audio clips, then it will be able to infer the correct path for newly created Audio Events.

Furthermore, if you name your Audio Clips that belong to the same event with the same name but a different number suffix, such as Jump_01 and Jump_02, then Audio Syntax can automatically infer that these two Audio Clips both belong to one Audio Event called Jump.

If you follow this convention, and then select one or more Audio Clips, you can select Create / Audio / Events From Selected Clips and Audio Events will be created for the selected Audio Clips, in the appropriate folder. If you do not have a mirrored folder structure, you can still use this feature, but the Audio Events will be created in the root Audio Event folder and you must move them manually.

Important

Audio Events must always be a child of the specified Audio Event Root Folder. This is necessary for Audio Syntax to be able to infer a Path for the event. For example: for an Audio Event specified in _Game/Configs/Audio/Events/Player/Jump we want the path to be Player/Jump, so we need to tell the system that the Audio Event Root Folder is _Game/Configs/Audio/Events.

Loading Audio Events via Addressables

Audio Syntax supports loading Audio Events via Addressables. This is a more scalable approach and is recommended for larger projects. The way Audio Event loading works is particularly relevant when playing Audio Events via code, because the Audio Event then needs to be loaded in some explicit way. Normally it would load this via Resources, but if you have the Addressables package in your project it will use that instead.

The system will automatically cache Audio Event addresses in the Unity Audio Syntax Settings asset whenever you build your Addressables. This allows the system to know which Audio Event paths correspond to which address, and lets them be loaded asynchronously at runtime. This system works automatically, you don't need to do anything other than commit the Unity Audio Syntax Settings asset to version control too if you rebuild your Addressables.

You can view the mapping from Audio Events to Addresses in your Unity Audio Syntax Settings asset (accessible via the Audio Syntax/Unity Audio Syntax Settings menu option).

Then, when you play an Audio Event and it was not loaded, it will be loaded asynchronously via its address and play as soon as it is done loading. Note that this will produce a noticeable delay. You should instead create a Group and load the entire group up front, before it is needed. You can use Labels for this.

Managing this is up to you. Please see the Addressables documentation for more information on how all this works.

Generating code for accessing Audio Events

Use the Audio Syntax > Generate Audio Code menu option and code will be generated in the specified folder / namespace that lets you access the Audio Events from code. See: How To Use on the main Read Me file.

Timeline Events

Tip

It's highly recommended that you use Scriptable Object Collection to manage your Scriptable Object assets.

If you use Scriptable Object Collection then you create a collection using ScriptableObject Collection/Collections/Audio Syntax/Create Audio Timeline Event ID Collection, and you can create the timeline event ID's from there.

Otherwise you create individual tags using Create > Audio > Timeline Event ID

---

You can now add the specified Timeline Event to Audio Events via their configs. You add them at a specific time in a specific Audio Clip, and then when the Audio Event is played, the Playback instance is notified when the event is reached, which you can subscribe to by calling AddTimelineEventHandler and specifying the ID of the timeline event you're interested in.

This is useful when you want to make certain things happen in synch with the audio.

Tags

Tip

It's highly recommended that you use Scriptable Object Collection to manage your Scriptable Object assets. For tags you can also enable the optional USE_COLLECTION_ITEM_PICKER_FOR_TAGS scripting define symbol and then you can use a nice picker for the tags instead of the regular serialized field. The Setup Wizard helps do this for you if Scriptable Object Collection was detected in your project.

If you use Scriptable Object Collection then you create a collection using ScriptableObject Collection/Collections/Audio Syntax/Create Unity Audio Tag Collection, and you can create the tags from there.

The benefit of this approach is that you can then access the tags from code as well.

Otherwise you create individual tags using Create > Audio > Tag

---

You can assign tags to Audio Events via their configs, and then you can access these at runtime. This can be useful for debugging, for instance if you're looking to visualize a specific subset of audio to find something that's going wrong.

How it wraps Unity's underlying system

When an Audio Event is played, a Playback instance is created which you can use to manipulate the playback of the audio (even a one-off may want to see some of its properties tweaked or to be stopped prematurely). This playback instance then requests an Audio Source from a pool, and its settings will be updated according to the specifications of the Playback instance. This means that you don't need to add a Game Object and an Audio Source component somewhere to your object's hierarchy every time you want to play a new kind of audio, because that's very cumbersome.

The prefab that is used for pooled Audio Sources is specified in the Unity Audio Syntax Settings asset. You can make a copy of this prefab and tweak its spatialization settings to make sense for your game, as side-scrolling platformers, first person shooters and top down RPG's will all have very different expectations in terms of from how far you are expected to be able to hear sounds. If you specify a Transform from which the sound should come when playing an Audio Event, then the audio will be spatialized from that position. If you do not specify an origin then it is played back globally. Note that

Playback instances are automatically registered at the Audio Syntax System, and when you call AudioSyntaxSystem.Update, it checks if any playback instances are marked as not being necessary any more and then their resources are released and the playback instance is removed from the system.

Feature wishlist

• More fine-grained control over spatialization (if you need this feature, please suggest how to approach it)
• Support 'Parameters' that you can use to drive certain Audio Event properties
• Better audio preview that also takes pitch and volume into consideration (would probably have to circumvent Unity entirely for audio playback)