Audio Toolkit – Introduction

What is the Audio Toolkit?

In a nutshell the ClockStone Audio Toolkit is a set of Unity tools to help you:

• Easily manage all audio assets of your project. Let your audio artist configure audio properties such as volume, random pitch, fading, etc. - all from within the Unity inspector.
• Play audio from script code in the simplest way possible – by calling a static function with a unique audio ID: AudioController.Play( "MySoundEffect1" );
• Alternatively you use the provided components in the ExampleBehaviour directory to trigger audio without any scripting (e.g. the PlayAudio component)
• Depending on the audio configuration set up by the audio artist in the inspector MySFX can either be a simple sound file or a more complex audio behaviour. Note that all necessary audio objects with the AudioSource component as required by Unity will get created automatically.

What it is NOT

The Audio Toolkit is not a separate audio engine. It is just a very convenient set of tools to play and manage audio using Unity’s internal audio engine (FMOD). It supports all features provided by Unity, but is also bound to the same restrictions.

Why you should never use Unity’s AudioSource directly to play audio

There are many good reasons you should not play audio by setting up prefabs with an AudioSource:

• Your audio artist will go crazy if he/she has to go through hundreds of object in many different places of your project's asset hierarchy just to adjust basic parameters like volume, or random variations.
• You don’t want your programmers to care about how an audio should sound like – they only have to trigger a certain audio ID and the audio artist defines what is actually played
• If many sounds are triggered frequently it can be bad for the performance especially on mobile platforms. The Audio Toolkit uses a method called “pooling” to quickly create and destroy audio objects which is avoiding memory issues at the same time.

The Audio Toolkit is a complete solution

The toolkit is designed to solve ALL problems related to playing sound and music (within the limits imposed by Unity’s underlying sound engine). There is no need to use objects with AudioSource components anymore. The Audio Toolkit is a complete replacement for the old system and does not restrict you in any way with your sound design. It just helps you get there much faster and easier!
The Toolkit supports all official Unity platforms (including PC, Mac, iOS, Android, etc.). It can be used with C# or Java scripts.

Audio Toolkit Features

Audio Categories

• Define audio assets in categories
• Set properties such as the volume for the entire category, adjustable at run-time and effecting all playing audios
• Categories can be parented to other categories forming a tree of subcategories
• Set special properties such as volume roll-off or Doppler effect per category
• Assign a Unity 5 Audio Mixer to a category to achieve e.g. audio ducking

Audio settings (per Audio Item)

• Specify volume, pitch, delay, pan, start offset, etc.
• Limit the number of simultaneously playing sound effects of the same type
• Define a time interval during which two almost simultaneously playing sounds will play only once. This prevents unwanted sound artefacts in such situations
• Set min/max distance for 3D sounds
• Automatic fade-in and fade-out
• random pitch or volume
• specify parameters like volume, pitch, etc. also on a sub-item level with the possibility to batch-change them on the audio item level
• copy/paste settings from one item to another

Audio playback

• Play ambient audio effects (without a specific position)
• Play audios at a specified 3D position
• Play audios parented to moving objects
• Pause / Unpause with optional fade-in/out
• Play gapless chains of multiple custom sound effect
• Scheduled stopping of sound effect (with optional fade-out)
• Schedule playing gapless chains of audio effects

Audio behaviour

• assign multiple audio files to one Audio Item and choose between several modes which one is played
• Randomly
• Randomly but not the same twice
• Sequence
• Two or all sound effects simultaneously
• Loop a sequence of sound effects with optional cross-fade
• Looped sequences can be random
• Intro/Loop sequence
• Intro/Loop/Outro sequence
• Play sequences of audio files with optional overlap, random delay, or without gap

Music

• Special functions to play music that automatically cross-fade between different tracks
• Music track playlist management with shuffle, loop, etc.

Ambience Sound

• Separate ambience sound channel with automatic cross-fade similar to the music functions

Management

• Audio event log to keep track of which audio items were triggered at what point of time
• Audio overview window with a list of all available audio items, with search function (very useful for large projects)
• Use several AudioControllers in one scene to separate scene specific from globally used assets
• Memory management: Automatically unload scene specific audio from memory

Scripting Interface

• Play functions return a reference of the (poolable) AudioObject playing the respective sound effect. This reference can be used to manipulate the specific audio effect. (e.g. stop or fade-out)
• Delegates to get notified if a sound finished playing
• Dynamically add or remove new Audio Items or Categories at runtime
• Support for streaming audio and loading from asset bundles

Performance

• Optimized performance especially for mobile platforms
• Object Pooling to avoid memory overheads
• Use of scene-specific AudioControllers to control the amount of audio assets to be loaded for each scene.

Who uses the Audio Toolkit?

The Toolkit is considered to be THE professional standard solution used in countless commercial products, including famous AAA titles by renowned game studios (that can unfortunately not all get named here for legal reasons)

Here is a statement from Codemasters:
“Codemasters use Clockstone’s Audio Toolkit in our mobile game development because it adds to Unity3D many of the advanced features we’ve come to rely upon in our AAA console games like DiRT, F1 and RaceDriver: GRID. Things like chromatic pitch controls, dynamic voice management, mix categories with group properties, pitch, volume and sample randomisation, automated fading, gapless chaining and event logging combine with Unity3D’s fast-turn-around to enable small teams to keep pace with the giants; Clockstone’s prompt and expert support makes Audio Toolkit even more of a bargain.
- Simon N Goodwin, Principal Programmer, Codemasters”

How to use:

• create a unique GameObject named "AudioController" with the AudioController script component added
• Create an AudioObject prefab containing the following components: Unity's AudioSource, the AudioObject script, and the PoolableObject script (if pooling is wanted).
  
• Then set your custom AudioSource parameters in this prefab. Next, specify your custom prefab in the AudioController as the "audio object".
  
• create your audio categories in the AudioController using the Inspector, e.g. "Music", "SFX", etc.
  
• for each audio to be played by a script create an 'audio item' with a unique name in the respective category.
  You can also select a list of audio clips in the Unity Project View and push the “Add selected audio clips” button. This will create an audio item for each clip.
  
• Create as many audio subitems for each audio item as you wish. A subitem represents the actual audio file (the Unity AudioClip). If more than one subitem is specified, the Audo Toolkit will select the audio clip either by random or in a certain order, depending on the audio item settings.
  You can also select a list of audio clips in the Unity Project View and push the “Add selected audio clips” button. This will create a sub item for each clip.
  

To play an audio item call the static function

AudioController.Play( "MyUniqueAudioItemName" )

Use

AudioController.PlayMusic( "MusicAudioItemName" )

to play music. This function assures that only one music file is played at a time and handles cross fading automatically according to the configuration in the AudioController instance.

 

Further examples:

AudioController.Play( "MySoundEffect1" );
AudioController.Play( "MySoundEffect2", new Vector3( posX, posY, posZ ) );
AudioController.PlayMusic( "MusicTrack1" );
AudioController.SetCategoryVolume( "Music", 0.5f );
AudioController.PauseMusic();