Sonity 1.0.1 Documentation

Audio Middleware for Unity

Table of Contents

Table of Contents

1 Getting Started

1.1 What is Sonity?

1.2 Installation

1.3 Adding the SoundManager

1.4 Asset Creation

1.5 Asset Editing

1.6 Shortcuts

1.7 Playing and Stopping Sounds with SoundTrigger Basics

1.8 Playing and Stopping Sounds with C# Basics

1.9 Script Templates

1.8.1 TemplateAudioMixerWithLimiter.mixer

1.8.2 TemplateSoundMusicManager.cs

1.8.3 TemplateSoundPlayUI.cs

1.8.4 TemplateSoundVolumeManager.cs

2 Create Assets From Selection Reference

3 SoundContainer Reference

3.1 SoundContainer Presets

3.2 SoundContainer Preview

3.3 SoundContainer AudioClips

3.4 SoundContainer Settings

3.5 SoundContainer Volume

3.6 SoundContainer Pitch

3.7 SoundContainer Spatial Blend

3.8 SoundContainer Spatial Spread

3.9 SoundContainer Stereo Pan

3.10 SoundContainer Reverb Zone Mix

3.11 SoundContainer Distortion

3.12 SoundContainer Lowpass

3.13 SoundContainer Highpass

3.14 SoundContainer Find References

4 SoundEvent Reference

4.1 SoundEvent Mute, Solo, Disable

4.2 SoundEvent Preview

4.3 SoundEvent SoundContainers

4.4 SoundEvent Timeline

4.5 SoundEvent Modifiers

4.6 SoundEvent Settings

4.7 Intensity

4.8 SoundEvent Trigger On Play

4.9 SoundEvent Trigger On Stop

4.10 SoundEvent Trigger On Tail

4.11 SoundEvent SoundTag

4.12 SoundEvent Find References

5 SoundEvent Functions Reference

5.1 SoundEvent Play

5.2 SoundEvent PlayAtPosition

5.3 SoundEvent Stop

5.4 SoundEvent Play2D

5.5 SoundEvent Stop2D

5.6 SoundEvent PlayMusic

5.7 SoundEvent StopMusic

5.8 SoundEvent Get SoundEvent State

5.9 SoundEvent Get Length or Time

5.10 SoundEvent Load or Unload Audio Data

6 Modifiers

7 SoundParameter Reference

8 SoundParameterIntensity Reference

9 SoundTrigger Reference

10 SoundPhysics Reference

11 SoundPicker Reference

12 SoundMix Reference

13 SoundPolyGroup Reference

14 SoundTag Reference

15 SoundDataGroup Reference

16 SoundManager Component Reference

16.1 SoundManager Settings

16.2 SoundManager Performance

16.3 SoundManager Debug SoundEvents Live

16.4 SoundManager Global Statistics

16.5 SoundManager Instance Statistics

17 SoundManager Functions Reference

17.1 SoundManager.Instance Play

17.2 SoundManager.Instance PlayAtPosition

17.3 SoundManager.Instance Stop

17.4 SoundManager.Instance Play2D

17.5 SoundManager.Instance Stop2D

17.6 SoundManager.Instance PlayMusic

17.7 SoundManager.Instance StopMusic

17.8 SoundManager.Instance Get SoundEvent State

17.9 SoundManager.Instance Get Length or Time

17.10 SoundManager.Instance SoundTag

17.11 SoundManager.Instance Global Distance Scale

17.12 SoundManager.Instance Speed Of Sound

17.13 SoundManager.Instance Voice Limit

17.14 SoundManager.Instance Disable Playing Sounds

17.15 SoundManager.Instance Get Transform

1 Getting Started

1.1 What is Sonity?

Sonity is an audio middleware giving you full control of your sound, all within Unity.

Balancing ease of use with advanced features it will help you to quickly make your game sound good.

Helpful Links and Info

1.2 Installation

1.  After purchase, go to the Package Manager, show “My Assets” and search for “Sonity”.

2.  Then click on “Sonity” and press “Download”, then “Import”.

3.  It should be located at “Assets\Plugins\Sonity”

Tip:         If you’re upgrading from an earlier version you might need to remove the whole “Sonity” folder in the project.

And if you´re still having trouble, try removing the “.asmdef” files “Sonity.Runtime.asmdef” and “Sonity.Editor.asmdef”.

Then you can re-import those files again.

Supported Unity Versions

Tested, full functionality.

Tested, everything works except “Debug SoundEvents Live (In Scene View)”.

Minor GUI tweaks for compatibility.

Everything works except DSP (distortion/lowpass/highpass).

1.3 Adding the SoundManager

The SoundManager is used to play sounds and manage global settings.

An instance in the scene is required to play SoundEvents.

You can either add the pre-made prefab called “SoundManager” or add the “Sonity - Sound Manager” component to an empty GameObject in the scene.

Tip: Don’t forget to set up the Distance Scale to match the scale of your project.

More info at SoundManager Component Reference.

1.4 Asset Creation

The asset hierarchy for playing sounds is:

AudioClip > SoundContainer > SoundEvent

If you have a bunch of AudioClips in your project, just select them (or their folder).

Then right click to bring up the “Create” > “Sonity” > “Create Assets from Selection” menu and press the desired button.

More info at Create Assets From Selection Reference.

1.5 Asset Editing

The SoundContainers and SoundEvents contain the settings of how your sounds are played.

They are made of scriptable objects, so all changes you make in runtime are updated live and saved.

Tip: All Sonity scriptable objects and components are multi-editable.

SoundContainer Intro

SoundContainers are the building blocks of Sonity.

They contain AudioClips and options of how the sound should be played.

All SoundContainers are multi-object editable.

Overview:

Looping

Volume

Pitch

Spatial Blend

Spatial Spread

Stereo Pan

Reverb Zone Mix

Distortion

Lowpass Filter

Highpass Filter

Tip: Don’t forget to use the presets.

More info at SoundContainer Reference.

SoundEvent Intro

SoundEvents are what you play in Sonity.

They contain SoundContainers and options of how the sound should be played.

All SoundEvents are multi-object editable.

Overview:

Timeline

Modifier volume, pitch, fade in/out, etc.

Intensity.

Trigger another SoundEvent on Play, Stop, Tail, Tag.

More info at SoundEvent Reference.

1.6 Shortcuts

Create Assets From Selection Shortcuts

SC+SE from AudioClip Group Multiple SE: Ctrl+Shift+Q

SC+SE from AudioClip Group Single SE: Ctrl+Shift+W

SoundPolyGroup for SE Multiple: Ctrl+Alt+Shift+Q

SoundPolyGroup for SE Single: Ctrl+Alt+Shift+W

They are rebindable in the Shortcuts window.

Preview Shortcuts

Play: Ctrl+Q (Previews the selected SoundEvent or SoundContainer).

Stop: Ctrl+W (Stops any playing preview of SoundEvents and SoundContainers, press two times to skip fade out).

They are rebindable in the Shortcuts window.

Timeline Shortcuts & Controls

Zoom: Mousewheel scroll.

Pan: Mousewheel hold and drag (or left mouse button also if outside of item).

Volume: Hold and drag top of item up/down or click on the volume to write the decibel value.

Move item: Hold and drag on item left/right.

Focus on items: F

1.7 Playing and Stopping Sounds with SoundTrigger Basics

To play a SoundEvent, create a gameobject and add a SoundTrigger component to it.

Then select the SoundEvent you want to play and when you want it to play like in the example below:

More info at SoundTrigger Reference.

1.8 Playing and Stopping Sounds with C# Basics

To play a SoundEvent, create a C# script and include the “Sonity” namespace.

Then make a public “SoundEvent” property, select the desired SoundEvent in the inspector.

Use the functions of the SoundEvent to play and stop your SoundEvents like in the example below:

More info at SoundEvent Functions Reference and the SoundManager Functions Reference.

Example code:

using UnityEngine;
using Sonity;

public class PlayStopExample : MonoBehaviour {

   
public SoundEvent soundEvent;

   
void PlayExample() {
       
// Plays the SoundEvent at the position of the transform
       soundEvent.
Play(transform);
   }

    void StopExample() {
       
// Stops the SoundEvent playing at the transform
       soundEvent.
Stop(transform);
   }
}

1.9 Script Templates

Sonity contains script templates of advanced functionality which you can use in your game.

1.8.1 TemplateAudioMixerWithLimiter.mixer

Is an AudioMixer which has a limiter on the master so that loud sounds can’t clip over the volume threshold.

1.8.2 TemplateSoundMusicManager.cs

Template of a singleton music playback system.

Add to a GameObject in the scene and use like this:

SonityTemplate.TemplateSoundMusicManager.Instance.PlayMainMenu();

1.8.3 TemplateSoundPlayUI.cs

Template of a singleton used to play e.g. UI sounds.

Useful when you want to play SoundEvents in a lot of places through code.

Add to a GameObject in the scene and use like this:

SonityTemplate.TemplateSoundPlayUI.Instance.PlayButtonClick();

1.8.4 TemplateSoundVolumeManager.cs

Template of a singleton AudioMixer volume controller.

The default settings work with the provided "TemplateAudioMixerWithLimiter.mixer".

Add to a GameObject in the scene and use like this:

SonityTemplate.TemplateSoundVolumeManager.Instance.SetVolumeMaster(1f);

2 Create Assets From Selection Reference

Right-click in the project menu to bring up the “Create Assets from Selection” menu.

With this you can easily create all your sound assets quickly if your AudioClips are named right.

Shortcuts

SC+SE from AudioClip Group Multiple SE: Ctrl+Shift+Q

SC+SE from AudioClip Group Single SE: Ctrl+Shift+W

SoundPolyGroup for SE Multiple: Ctrl+Alt+Shift+Q

SoundPolyGroup for SE Single: Ctrl+Alt+Shift+W

They are rebindable in the Shortcuts window.

AudioClip Group

AudioClip groups are sounds with the same name, but different numbers in the end e.g 01, 02, 03 etc.

In the example below we select the bow and arrow sounds and run “SC+SE from AudioClip Group Multiple SE”.

This creates 2 SoundContainers and 2 SoundEvents, one per group.

Then we select the metal box impact sounds and run “SC+SE from AudioClip Group Single SE”

They contain 3 different groups which will create 3 SoundContainers, one per group and a single SoundEvent.

Single SoundEvent name from common denominator

If “SC+SE from AudioClip Group Single SE” is run, then it will try to find a common denominator of the names of the SoundContainers for naming the SoundEvent.

3 SoundContainer Reference

SoundContainers are the building blocks of Sonity.

They contain AudioClips and options of how the sound should be played.

All SoundContainers are multi-object editable.

Here is a description of controls shared by multiple fields.

Rolloff

The power of the rolloff.

0 is linear.

Curve

Curve of the value over distance or intensity.

Distance: From 0 (close) to 1 (distant).

Intensity: From 0 (soft) to 1 (hard).

Strength

How much effect the distance/intensity should have.

Increase

Increases the amount.

3.1 SoundContainer Presets

Presets for the SoundContainer. (The preset info also shows up on button hover)

SFX 3D

Enable Distance = true

Spatial Blend = 1

Never Steal Voice = false

Never Steal Voice Effects = false

Pitch Random = true

Priority = 0.5

SFX 2D

Enable Distance = false

Spatial Blend = 0

Never Steal Voice = false

Never Steal Voice Effects = false

Pitch Random = true

Priority = 0.5

Music

Enable Distance = false

Spatial Blend = 0

Never Steal Voice = true

Never Steal Voice Effects = true

Pitch Random = false

Volume Random = false

Priority = 1

Automatic Looping

If the name of the selected SoundContainers contains “loop” then it will automatically set it to loop.

Automatic Crossfades

If the names of the selected SoundContainers end in certain combinations it will automatically set up distance or intensity crossfades.

It works on multiple groups at the same time.

These are the combinations and their result:

Distance Crossfade:

Close + Distant + Far = 3 layers

Close + Distant = 2 layers

Close + Far” = 2 layers

Intensity Crossfade:

Soft + Medium + Hard = 3 layers

Soft + Hard = 2 layers

3.2 SoundContainer Preview

With the preview you can listen to the sounds in the editor.

The preview handle enables you to move the sound around.

Preview Shortcuts

Play: Ctrl+Q (Previews the selected SoundEvent or SoundContainer).

Stop: Ctrl+W (Stops any playing preview of SoundEvents and SoundContainers, press two times to skip fade out).

They are rebindable in the Shortcuts window.

Play

Previews the SoundContainer.

Does not work if Unity cannot build the project, or if the game is paused.

The default shortcut is Ctrl+Q.

Stop

Press two times to skip fade out.

The default shortcut is Ctrl+W.

Reset

Resets the preview settings.

Intensity

Controls the intensity value of the played SoundContainers.

AudioMixerGroup

Only used for preview.

3.3 SoundContainer AudioClips

This is where you assign the AudioClips which are going to be used when the SoundContainer is played.

Update AudioClips

Updating AudioClips can be used to automatically add/remove variations.

Can be used on multiple items at once (tip: search “t:soundContainer”).

Refresh AudioClip Group

Adds all AudioClips with the same name as the first AudioClip (disregarding numbers, e.g. 01 02).

Find AudioClip Group

Automatically finds all AudioClips containing the same name as this SoundContainer (disregarding _SC, numbers).

If no matching AudioClips are found, it will try and remove one character at the end of the name at a time until it finds a hit.

Drop AudioClips/Folders Here

Here you can drag and drop AudioClips or folders with AudioClips in them.

3.4 SoundContainer Settings

Tip: All the info is also available as tooltips if you hover over properties.

AudioMixerGroup

The AudioMixerGroup you want to output to.

The SoundEvents AudioMixerGroup overrides the SoundContainers AudioMixerGroup.

Changing AudioMixerGroup for the Voice often takes a lot of performance.

Use AudioMixerGroups when you want effects per group or e.g. ducking.

If you just want to control volume hierarchically look at SoundMix assets for a high performance solution.

Enable Distance

Otherwise the SoundContainer will not be affected by distance (disable for music etc).

Distance Scale

Range scale multiplier. It is multiplied by the Distance Scale of the SoundManager.

Loop

Makes the sound loop.

If you use "Create Assets from Selection" and the AudioClip contains the word "Loop" it will automatically be enabled.

Follow Position

If the SoundContainer should follow the given Transform position.

Stop if Transform is Null

Automatically stops the sound if the Transform it's played at is destroyed (either the owner or position Transform).

Useful safety precaution for loops.

Random Start Position

Starts the sound at a random position.

Overrides the Start Position setting.

Useful for loops.

Random Range

Min/max range within the sound can start at.

Start Position

0 is the start and 1 is the end.

Reverse

If enabled the AudioClip will be played backwards.

Make sure to set the start position to the end.

Reverse is only supported for AudioClips which are stored in an uncompressed format or will be decompressed at load time.

Lock Axis

Locks the selected axis to the selected position.

Useful for 2D games if you want to lock the sound to a position along an axis.

Axis

The axis to lock.

Position

The position to set the locked axis to.

Advanced

Play Order

Determines in which order the AudioClips will be played.

Global Random

All SoundEvents will share the same global random AudioClip pool, which ensures less repetition.

Uses a pseudo random function remembering half of the length of available AudioClips it last played to avoid repetition.

Local Random

Same as global random except its per SoundEvent owner.

If enabled all will share the same global random AudioClip pool, which ensures less repetition.

Otherwise random AudioClip per owner is used.

The randomizer either way uses a pseudo random function remembering which AudioClips it last played to avoid repetition.

Priority

The priority the Voice has when Voice stealing.

Also the priority the Voice Effects has when Voice Effects stealing.

1 is high priority, 0.5 is default priority and 0 is low priority.

It's multiplied with the volume of the Voice when evaluating final priority.

Prevent End Clicks

If enabled it will fade out the volume 0.1 seconds before the end of the AudioClip to prevent clicks.

If the AudioClips is shorter than 0.1 seconds or set to loop the fade will be skipped.

DC offsets and some settings in Unity make an AudioClip click at the end.

Tip: If you still experience sporadic clicks, try changing the Load Type of the AudioClips to e.g. "Compressed In Memory", it might help.

Never Steal Voice

The SoundManager will never steal this Voice if the Voice Limit is reached (use on music etc).

Never Steal Voice Effects

The SoundManager will never steal the Voice Effects on this Voice if the Voice Effect Limit is reached (use on music etc).

Doppler Amount

How much the pitch of the sound is changed by the relative velocity between the AudioListener and the AudioSource.

Bypass Reverb Zones

Bypasses any reverb zones

Bypass Voice Effects

Bypasses any effects on the AudioSource, e.g. Distortion and Filters.

Voice effects are automatically bypassed if you don't have distortion/lowpass/highpass enabled.

Bypass Listener Effects

Bypasses any effects on the listener

3.5 SoundContainer Volume

Controls the volume (in decibel).

Tip: If you want to be able to raise the volume and not just lower it, select all the SoundContainers and lower the volume to -12 dB.

Then to compensate you can increase the global volume with an Audio Mixer (which you then can set to +12 dB).

-1 dB

Lowers the relative volume of all the selected SoundContainers.

Useful for example if you want to raise the volume of one SoundContainer and keep the relative volume.

Because then you can lower all of them to get more headroom.

If multiple SoundContainers are selected it will show the lowest volume.

+1 dB

Raises the relative volume of all the selected SoundContainers.

Stops if any of the selected SoundContainer reaches 0 db.

Useful for example if you want to set the loudest volume to 0 dB but keep the relative volumes.

If multiple SoundContainers are selected it will show the highest volume.

Distance Crossfade

With distance crossfade you can easily crossfade between different sounds over distance.

For e.g. gunshots you could add sounds with close, distant and far perspectives.

You’d set the “Layers” setting to 3 for all the SoundContainers.

Then you’d set “This Is” of close to 1, distant to 2 and far to 3.

Layers

The number of layers the crossfade is based on. You must have at least 2 layers.

This is

Which layer this is. Set up with other SoundContainers for the other layers. Lower numbers are closer and higher are more distant.

Intensity

Changes the volume over intensity.

Use on for example physics sounds where you pass the velocity with a SoundParameterIntensity.

Intensity Crossfade

With intensity crossfade you can easily crossfade between different sounds over intensity.

For e.g. impacts you could add sounds with hard, medium and soft variations.

You’d set the “Layers” setting to 3 for all the SoundContainers.

Then you’d set “This Is” of hard to 3, medium to 2 and soft to 1.

Layers

The number of layers the crossfade is based on. You must have at least 2 layers.

This is

Which layer this is. Set up with other SoundContainers for the other layers. Higher numbers are harder and lower numbers are softer.

Intensity Crossfade example:

3.6 SoundContainer Pitch

Controls the pitch (in semitones).

Intensity

Changes the pitch over intensity.

Use on for example car sounds where you pass the speed with a SoundParameterIntensity.

Low st

The lowest intensity in semitones. Range -128 to 128.

High st

The highest intensity in semitones. Range -128 to 128.

3.7 SoundContainer Spatial Blend

Controls the spatial blend. 0 is 2D (not spatialized) and 1 is 3D (spatialized).

Intensity

Changes the spatial blend over intensity.

3.8 SoundContainer Spatial Spread

Controls the spatial spread (in degrees).

Only the 3D (spatialized) part of the sound is affected by the spatial spread.

Intensity

Changes the spatial spread over intensity.

3.9 SoundContainer Stereo Pan

Controls the stereo pan. -1 is left and 1 right.

Only the 2D part of the sound is affected by the stereo pan.

Angle To Stereo Pan

Pans the sound depending on the angle between the Voice and the AudioListener.

3.10 SoundContainer Reverb Zone Mix

Controls the reverb zone mix (in decibel).

Intensity

Changes the reverb zone mix over intensity.

3.11 SoundContainer Distortion

Waveshaper type distortion.

0 is clean, 1 is distorted.

SoundContainer Voice Effects are applied per Voice.

If distortion amount is 0 the effect is disabled internally for performance.

The number of active Voice Effects are limited by the “Voice Effect Limit” on the SoundManager.

DSP effects are not available in WebGL.

Intensity

Changes the distortion over intensity.

Use on for example explosion sounds where you pass the size of the explosion with a SoundParameterIntensity.

3.12 SoundContainer Lowpass

Lowpass filter with a variable amount.

Maximum of 6dB per octave.

SoundContainer Voice Effects are applied per Voice.

If frequency is 20,000 Hz or amount is 0 dB the effect is disabled internally for performance.

The number of active Voice Effects are limited by the “Voice Effect Limit” on the SoundManager.

DSP effects are not available in WebGL.

Intensity

Changes the lowpass over intensity.

Use on for example occluded sounds where you pass the amount of occlusion with SoundParameterIntensity.

3.13 SoundContainer Highpass

Highpass filter with a variable amount.

Maximum of 6dB per octave.

SoundContainer Voice Effects are applied per Voice.

If frequency is 20 Hz or amount is 0 dB the effect is disabled internally for performance.

The number of active Voice Effects are limited by the “Voice Effect Limit” on the SoundManager.

DSP effects are not available in WebGL.

Intensity

Changes the highpass over intensity.

Use on for example occluded sounds where you pass the amount of occlusion with SoundParameterIntensity

3.14 SoundContainer Find References

Find References

Finds all the references to the SoundContainer.

Select All

Selects all the assets with references to the SoundContainer.

Clear

Removes all the found references.

4 SoundEvent Reference

SoundEvents are what you play in Sonity.

They contain SoundContainers and options of how the sound should be played.

All SoundEvents are multi-object editable.

4.1 SoundEvent Mute, Solo, Disable

Mute

Mutes the SoundEvent.

Only affects the Unity Editor.

Solo

Mutes all other SoundEvents who don't have solo enabled.

The Solo property is not serialized (e.g. will be reset on start).

This is to prevent leaving a SoundEvent soloed by mistake which would make nothing else sound when the game runs.

Only affects the Unity Editor.

Disable

Disables the playing of the SoundEvent.

It is also disabled when building the project.

4.2 SoundEvent Preview

With the preview you can listen to the sounds in the editor.

The preview handle enables you to move the sound around.

Preview Shortcuts

Play: Ctrl+Q (Previews the selected SoundEvent or SoundContainer).

Stop: Ctrl+W (Stops any playing preview of SoundEvents and SoundContainers, press two times to skip fade out).

They are rebindable in the Shortcuts window.

Play

Previews the SoundEvent.

Does not work if Unity cannot build the project, or if the game is paused.

Preview doesn't play more than one level of TriggerOnPlay/Stop/Tail at the moment (there is full functionality ingame).

The default shortcut is Ctrl+Q.

Stop

Press two times to skip the fade out.

The default shortcut is Ctrl+W.

Reset

Resets the preview settings.

Intensity

Controls the intensity value of the played SoundContainers.

AudioMixerGroup

Only used for preview.

4.3 SoundEvent SoundContainers

This is where you assign the SoundContainers which are going to be used when the SoundEvent is played.

Find SoundContainers

Automatically finds all SoundContainers containing the same name as this SoundEvent (disregarding _SE, numbers).

Can be used on multiple items at once (tip: search "t:soundEvent").

If no matching SoundContainers are found, it will try and remove one character at the end of the name at a time until it finds a hit.";

Drop SoundContainers/Folders Here

Here you can drag and drop SoundContainers or folders with SoundContainers in them.

4.4 SoundEvent Timeline

In the timeline editor you can move the items in time and change the volume volume of individual SoundContainers.

The length of the item in the timeline is determined by the length of the longest AudioClip in the SoundContainer.

If you change the pitch, the length of the item will match the pitch.

Shortcuts and Controls

Zoom: Ctrl + mouse wheel scroll.

Pan: Mouse wheel hold and drag (or left mouse button hold and drag on the background).

Volume: Hold and drag top of item up/down or click on the volume to write the decibel value.

Move item: Hold and drag on item left/right.

Focus on items: F

4.5 SoundEvent Modifiers

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

See Modifiers for more info.

4.6 SoundEvent Settings

Polyphony Mode

Limited Per Owner:

Useful if you want to limit polyphony e.g per player.

You can use e.g SoundEvent.PlayAtPosition(); to play a SoundEvent at one position with another owner.

Limited Globally:

Useful if you want to limit the polyphony globally e.g for bullet impacts.

This setting will change the old owner to the new position and set the new owner as the Transform of the SoundManager.Instance.

Tip: If you want to limit the polyphony per owner and globally at the same time, you can use SoundPolyGroups.

AudioMixerGroup

The AudioMixerGroup you want to output to.

The SoundEvents AudioMixerGroup overrides the SoundContainers AudioMixerGroup.

Changing AudioMixerGroup for the Voice often takes a lot of performance.

Use AudioMixerGroups when you want effects per group or e.g. ducking.

If you just want to control volume hierarchically look at SoundMix assets for a high performance solution.

SoundMix

SoundMix enables hierarchical control of for example volume.

SoundPolyGroup

SoundPolyGroup gives polyphony control grouped over different SoundEvent types.

Priority

Lower priority SoundEvents will be stolen first.

If "Skip Lower Priority" is enabled on the SoundPolyGroup this will determine if this SoundEvent will play or not when the Polyphony Limit is reached.

Cooldown Time

How quick this SoundEvent can be retriggered in seconds.

Calculated using Time.realtimeSinceStartup.

Probability %

The probability that this SoundEvent should play.

4.7 Intensity

Intensity contain settings for how SoundParameterIntensity is scaled before it is applied to the enabled intensity options e.g Volume, Pitch etc.

In the example above the sound is played a few times with a SoundParameterIntensity.

The range of the recorded intensity is from 0.5 to 2.5.

When “Scale Values to 0 to 1 Range” is pressed the following happens:

  1. It first finds the lowest value which is 0.5 and sets Add to -0.5 so it is 0
  2. Then it finds the highest point which now is 2 and sets Multiplier to 0.5 so it is 1

This makes the range into 0 to 1.

The intensity debug log records all intensity values used when this SoundEvent is played.

It is used to scale the SoundParameterIntensity to a 0-1 range.

Add

Adds to the SoundParameterIntensity.

Multiplier

Multiplier of the SoundParameterIntensity.

Smoothing

The seek time of the SoundParameterIntensity in seconds.

Uses Time.realtimeSinceStartup.

Enable Threshold

If this SoundEvent is played with a SoundParameterIntensity and it is under the threshold when starting it won't be played.

Threshold

The threshold limit after scaling the intensity value.

Intensity Record

If enabled it will record all SoundParameterIntensity used when playing this SoundEvent.

Scale Values to 0 to 1 Range

First sets Intensity Add so the lowest value is 0.

Then sets Intensity Multiply so that the highest value is 1.

Debug Resolution

The resolution of the displayed values.

4.7 SoundEvent Trigger On Which to Play

Which to Play

If Play All is selected, then all assigned SoundEvents will be played.

If One Random is selected, then one random of the assigned SoundEvents will be played.

The randomizer uses a pseudo random function remembering which SoundEvents it last played to avoid repetition.

4.8 SoundEvent Trigger On Play

Triggers another SoundEvent when this SoundEvent is played.

4.9 SoundEvent Trigger On Stop

Triggers another SoundEvent when this SoundEvent is stopped.

4.10 SoundEvent Trigger On Tail

Triggers another SoundEvent "Tail Length" before the end.

It looks at the time of the last played voice on the first SoundContainer.

Useful for music, e.g. if you have an intro with a 2 second tail and a loop you want to play on the tail of the intro.

If you play with SoundManager.PlayMusic, you can stop the next SoundEvent with SoundManager.StopAllMusic without a reference.

If you want it to trigger itself, make sure to set the "Settings" polyphony to 2.

If the trigger timing is not tight enough, try setting the AudioClip "Compression Format" to PCM or ADPCM (Vorbis is less accurate).

Tail Length

How long in seconds before the end of the SoundEvent to trigger the next SoundEvent.

It looks at the time of the last played voice on the first SoundContainer.

It takes into account pitch when calculating time.

For example, if the tail length is 2 seconds and you pitch it +12 semitones (2x speed) the internal tail length will be 1 seconds.

This is because double the speed with half the duration and vice versa.

Set Tail Length from BPM & Beats

Calculates the Tail Length from the BPM and the Beats settings.

BPM

Beats per minute.

Beats

How long the tail is in beats.

4.11 SoundEvent SoundTag

Uses SoundTag to play other SoundEvents and/or change SoundEventModifier.

The SoundTag won't be passed to the SoundEvents of the SoundTag in order to avoid infinite repetitions.

Mode

If local SoundTag is selected you need to pass an SoundTag when playing the SoundEvent.

If global SoundTag is selected you need to set the SoundTag on the SoundManager.

SoundTag

If this SoundTag is selected the SoundEvents below will be played.

Modifiers

If enabled the selected modifiers will be applied to the base SoundEvent and the SoundEvents of the SoundTag.

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

See Modifiers for more info.

4.12 SoundEvent Find References

Find References

Finds all the references to the SoundEvent.

Select All

Selects all the assets with references to the SoundEvent.

Clear

Removes all the found references.

5 SoundEvent Functions Reference

The SoundEvent can be played directly from itself instead of playing via the SoundManager.

A SoundManager instance in the scene is required to play SoundEvents.

Example code:

using UnityEngine;
using Sonity;

public class PlayStopExample : MonoBehaviour {

   
public SoundEvent soundEvent;

   
void PlayExample() {
       
// Plays the SoundEvent at the position of the transform
       soundEvent.
Play(transform);
   }

    void StopExample() {
       
// Stops the SoundEvent playing at the transform
       soundEvent.
Stop(transform);
   }
}

5.1 SoundEvent Play

// Plays the SoundEvent at the position of the owner Transform

public void Play(Transform owner)
public void Play(Transform owner, SoundTag localSoundTag)
public void Play(Transform owner, params SoundParameterInternals[] soundParameterInternals)
public void Play(Transform owner, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

owner

The owner Transform

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

5.2 SoundEvent PlayAtPosition

// Plays the SoundEvent at the Vector3 position with another Transform as the owner

public void PlayAtPosition(Transform owner, Vector3 position)
public void PlayAtPosition(Transform owner, Vector3 position, SoundTag localSoundTag)
public void PlayAtPosition(Transform owner, Vector3 position, params SoundParameterInternals[] soundParameterInternals)
public void PlayAtPosition(Transform owner, Vector3 position, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

// Plays the SoundEvent at the Transform position with another Transform as the owner

public void PlayAtPosition(Transform owner, Transform position)
public void PlayAtPosition(Transform owner, Transform position, SoundTag localSoundTag)
public void PlayAtPosition(Transform owner, Transform position, params SoundParameterInternals[] soundParameterInternals)
public void PlayAtPosition(Transform owner, Transform position, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

owner

The owner Transform

position

The Transform or Vector3 where is should play at (Transform can follow position)

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

5.3 SoundEvent Stop

Tip: You really only need to use stop for looping or longer oneshot sounds (or the SoundContainer “Stop if Transform is Null” setting).

Use the polyphony setting in the SoundEvent to manage the number of instances playing.

// Stops the SoundEvent at the owner Transform

public void Stop(Transform owner, bool allowFadeOut = true)

// Stops the SoundEvent at the position Transform

public void StopAtPosition(Transform position, bool allowFadeOut = true)

// Stops all the SoundEvents at the owner Transform

public void StopAllAtOwner(Transform owner, bool allowFadeOut = true)

// Stops the SoundEvent everywhere

public void StopEverywhere(bool allowFadeOut = true)

// Stops all SoundEvents

public void StopEverything(bool allowFadeOut = true)

Parameters

owner

The owner Transform

position

The position Transform

allowFadeOut

If the SoundEvent should be allowed to fade out. Otherwise it is going to be stopped immediately

5.4 SoundEvent Play2D

Useful if you want to play SoundEvents without passing an owner.

// Plays the SoundEvent with the 2D Transform as owner

public void Play2D()
public void Play2D(SoundTag localSoundTag)
public void Play2D(params SoundParameterInternals[] soundParameterInternals)
public void Play2D(SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

5.5 SoundEvent Stop2D

// Stops the SoundEvent at the 2D Transform

public void Stop2D(bool allowFadeOut = true)

// Stops all SoundEvents at the 2D Transform

public void StopAllAt2D(bool allowFadeOut = true)

Parameters

allowFadeOut

If the SoundEvent should be allowed to fade out. Otherwise it is going to be stopped immediately

5.6 SoundEvent PlayMusic

Useful if you want to play music with automatic stopping of the old music when playing a new song.

// Plays the SoundEvent at the SoundManagers music Transform

public void PlayMusic(bool stopAllOtherMusic = true, bool allowFadeOut = true)

public void PlayMusic(bool stopAllOtherMusic = true, bool allowFadeOut = true, params SoundParameterInternals[] soundParameterInternals)

Parameters

stopAllOtherMusic

If all other SoundEvents played at the SoundManager music Transform should be stopped

allowFadeOut

If the other stopped SoundEvent should be allowed to fade out. Otherwise they are going to be stopped immediately

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

5.7 SoundEvent StopMusic

// Stops the SoundEvent playing at the SoundManagers music Transform

public void StopMusic(bool allowFadeOut = true)

// Stops the all SoundEvents playing at the SoundManagers music Transform

public void StopAllMusic(bool allowFadeOut = true)

Parameters

allowFadeOut

If the other stopped SoundEvent should be allowed to fade out. Otherwise they are going to be stopped immediately

5.8 SoundEvent Get SoundEvent State

// If playing it returns SoundEventState.Playing

// If not playing, but it is delayed it returns SoundEventState.Delayed

// If not playing, but it is delayed it returns SoundEventState.Delayed

// If not playing and it is not delayed it returns SoundEventState.NotPlaying

// If the SoundEvent or Transform is null it returns SoundEventState.NotPlaying

public SoundEventState GetSoundEventState()

5.9 SoundEvent Get Length or Time

// Returns the length (in seconds) of the AudioClip in the last played AudioSource

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

// pitchSpeed determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

public float GetLastPlayedClipLength(Transform owner, bool pitchSpeed)

// Returns the current time (in seconds) of the AudioClip in the last played AudioSource

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

// pitchSpeed determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

public float GetLastPlayedClipTime(Transform owner, bool pitchSpeed)

// Returns the max length (in seconds) of the SoundEvent (calculated from the longest audioClip)

// Is scaled by the pitch of the SoundEvent and SoundContainer

// Does not take into account random, intensity or parameter pitch

public float GetMaxLength()

// Returns the time (in seconds) since the SoundEvent was played

// Calculated using Time.realtimeSinceStartup

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

public float GetTimePlayed(Transform owner)

Parameters

owner

The owner Transform

pitchSpeed

Determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

forceUpdate

Force recheck the max length, otherwise will use cached length after first check

5.10 SoundEvent Load or Unload Audio Data

// Loads the audio data of any AudioClips assigned to the SoundContainers of this SoundEvent

public void LoadAudioData()

// Unloads the audio data of any AudioClips assigned to the SoundContainers of this SoundEvent

public void UnloadAudioData()

6 Modifiers

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

They are available on the SoundEvent, SoundTrigger, SoundPicker and SoundMix objects.

They have similar functionality as the SoundParameters, but with visual editing.

Some modifiers use priorities to determine what a final modifier value should be.

The modifier with the highest priority will determine the value.

1st: SoundParameter

2nd: SoundMix

3rd: SoundTrigger/SoundPicker

4th: SoundTag

5th: SoundEvent

Volume dB

Volume offset in decibel.

Pitch st

Pitch offset in semitones.

Delay

Increase the delay in seconds.

Start Position

Sets the start position, 0 is the start, 1 is the end.

The highest priority added modifier will determine the value.

Reverse

If enabled the AudioClip will be played backwards.

Make sure to set the start position to the end.

Reverse is only supported for AudioClips which are stored in an uncompressed format or will be decompressed at load time.

The highest priority added modifier will determine the value.

Distance Scale

Distance scale multiplier (how far it will be heard).

It is multiplied by the Distance Scale of the SoundManager.

Reverb Zone Mix dB

Reverb Zone Mix volume offset in decibel.

Fade In Length

The length of the fade in.

Uses Time.realtimeSinceStartup.

The highest priority added modifier will determine the value.

Fade In Shape

Shape of the fade in

Negative is exponential, 0 is linear, positive is logarithmic.

The highest priority added modifier will determine the value.

Fade Out Length

The length of the fade out.

Uses Time.realtimeSinceStartup.

The highest priority added modifier will determine the value.

Fade Out Shape

Shape of the fade out

Negative is exponential, 0 is linear, positive is logarithmic.

The highest priority added modifier will determine the value.

Increase 2D

Makes the SoundEvent more 2D (less spatialized).

Useful for first person sounds.

Stereo Pan

Stereo pan offset

-1 is left, 0 is centered, +1 is right.

Intensity

Multiplier of any used SoundParameterIntensity parameter.

Distortion Increase

Increases the distortion.

Distortion needs to be enabled on the SoundContainer for this to have any effect.

Polyphony

How many instances of the SoundEvent that can exist at the same transform.

The highest priority added modifier will determine the value.

Follow Position

If the SoundEvent should follow the given Transform position.

The highest priority added modifier will determine the value.

Bypass Reverb Zones

If enabled all reverb zones will be bypassed.

The highest priority added modifier will determine the value.

Bypass Voice Effects

If enabled all voice effects (lowpass/highpass/distortion) will be bypassed.

The highest priority added modifier will determine the value.

Bypass Listener Effects

If enabled all listener effects will be bypassed.

The highest priority added modifier will determine the value.

7 SoundParameter Reference

SoundParameters are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

They can be passed when playing a SoundEvent and set to update either once or continuously.

They have similar functionality as the Modifiers, but with scripting capabilities.

Example code:

using UnityEngine;
using Sonity;

public class ExampleSoundParameter : MonoBehaviour {

   
public SoundEvent soundEvent;

    SoundParameterVolumeDecibel volumeParameter = SoundParameterVolumeDecibel(0f, UpdateMode.Once);


   
void Start() {
       
// Sets the volume parameter to a random value between -12 dB and 0 dB
       volumeParameter.volumeDecibel =
Random.Range(-12f, 0f);

        // Plays the SoundEvent with the sound parameter

        soundEvent.Play(transform, volumeParameter);
   }
}

Update Modes

The UpdateMode enum determines if the SoundEvent will take the parameter into consideration only once at start or if it will be updated continuously.

// The SoundParameter will update only once

UpdateMode.Once

// The SoundParameter will update continuously

UpdateMode.Continuous

Parameter Types

The parameter type determines which parameter of the SoundEvent will be controlled.

See Modifiers for more detailed info on the individual parameters.

// Volume offset in decibel. Range -Infinity to 0

public class SoundParameterVolumeDecibel(float volumeDecibel = 0f, UpdateMode updateMode = UpdateMode.Once)

// Volume ratio multiplier. Range 0f to 1f

public class SoundParameterVolumeRatio(float volumeRatio = 1f, UpdateMode updateMode = UpdateMode.Once)

// Pitch offset in semitones

public class SoundParameterPitchSemitone(float pitchSemitone = 0f, UpdateMode updateMode = UpdateMode.Once)

// Pitch offset ratio multiplier. Range 0 to Infinity

public class SoundParameterPitchRatio(float pitchRatio = 1f, UpdateMode updateMode = UpdateMode.Once)

// Delay increase. Range 0 to Infinity

public class SoundParameterDelay(float delay = 0f)

// Makes the sound more 2D (less spatialized). Range 0 to 1

public class SoundParameterIncrease2D(float increase2D = 0f, UpdateMode updateMode = UpdateMode.Once)

// Controls the intensity of the SoundContainer

public class SoundParameterIntensity(float intensity = 1f, UpdateMode updateMode = UpdateMode.Once)

// Reverb zone mix offset in decibel. Range -Infinity to 0

public class SoundParameterReverbZoneMixDecibel(float reverbZoneMixDecibel = 0f, UpdateMode updateMode = UpdateMode.Once)

// Reverb zone mix ratio multiplier. Range 0 to 1

public class SoundParameterReverbZoneMixRatio(float reverbZoneMixRatio = 1f, UpdateMode updateMode = UpdateMode.Once)

// Reverb zone mix ratio multiplier. Range 0 to 1

public class SoundParameterReverbZoneMixRatio(float reverbZoneMixRatio = 1f, UpdateMode updateMode = UpdateMode.Once)

// Start position. Range 0 to 1

public class SoundParameterStartPosition(float reverbZoneMixRatio = 1f, UpdateMode updateMode = UpdateMode.Once)

// If the sound should be played backwards. If enabled, set the start position to the end.

// Reverse is only supported for AudioClips which are stored in an uncompressed format or will be decompressed at load time.

public class SoundParameterReverse(bool reverse = false)

// The polyphony of the SoundEvent. Range 1 to int.MaxValue

public class SoundParameterPolyphony(int polyphony = 1)

// Distance scale multiplier. Range 0 to Infinity

public class SoundParameterDistanceScale(float distanceScale = 1f)

// Distortion increase. Range 0 to 1

public class SoundParameterDistortionIncrease(float distortionIncrease = 1f, UpdateMode updateMode = UpdateMode.Once)

// Fade in length. Range 0 to Infinity

public class SoundParameterFadeInLength(float fadeInLength = 0f, UpdateMode updateMode = UpdateMode.Once)

// Fade in shape. Range -16 to 16 (negative is exponential, 0 is linear, positive is logarithmic)

public class SoundParameterFadeInShape(float fadeInShape = 2f, UpdateMode updateMode = UpdateMode.Once)

// Fade out length. Range 0 to Infinity

public class SoundParameterFadeOutLength(float fadeOutLength = 0f, UpdateMode updateMode = UpdateMode.Once)

// Fade out shape. Range -16 to 16 (negative is exponential, 0 is linear, positive is logarithmic)

public class SoundParameterFadeOutShape(float fadeOutShape = -2f, UpdateMode updateMode = UpdateMode.Once)

// If the SoundEvent should follow the Transform position

public class SoundParameterFollowPosition(bool followPosition = true, UpdateMode updateMode = UpdateMode.Once)

// If reverb zones should be bypassed

public class SoundParameterBypassReverbZones(bool bypassReverbZones = false, UpdateMode updateMode = UpdateMode.Once)

// If voice effects (distortion/lowpass/highpass) should be bypassed

public class SoundParameterBypassVoiceEffects(bool bypassEffects = false, UpdateMode updateMode = UpdateMode.Once)

// If listener effects should be bypassed

public class SoundParameterBypassListenerEffects(bool bypassListenerEffects = false, UpdateMode updateMode = UpdateMode.Once)

8 SoundParameterIntensity Reference

SoundParameterIntensity is used to pass an intensity value to a SoundContainer when playing a SoundEvent.

This value can be anything you want to affect your sound, e.g. velocity, the size of an explosion, the speed of a car, etc.

The SoundContainer can scale and use the intensity parameter to control intensity options e.g. volume, pitch, distortion etc.

Tip: You can record and debug the intensity at the Intensity in the SoundContainer.

Example code:

using UnityEngine;
using Sonity;

public class ExampleIntensityParameter: MonoBehaviour {

   
public SoundEvent soundEvent;

    SoundParameterIntensity intensityParameter = SoundParameterIntensity(1f, UpdateMode.Once);


   
void OnCollisionEnter(Collision collision) {
       
// Sets the intensity parameter to the velocity of the collision
       intensityParameter.intensity = collision.relativeVelocity.magnitude;

        // Plays the SoundEvent with the intensity parameter

        soundEvent.Play(transform, intensityParameter);
   }
}

Refer to the following examples:

Car motor example

The speed of the car is passed as an continuous intensity parameter which controls the intensity pitch and volume of the SoundContainer.

Physics impact example

The velocity of the impact is passed once as an intensity parameter which controls the intensity volume and intensity lowpass filter of the SoundContainer.

(Check out the SoundPhysics component for easily playing physics sounds)

For volume intensity you can crossfade between any number of layers (eg. hard/medium/soft) easily and accurately.

The default settings of the lowpass filter intensity settings make the sound more filtered the lower the intensity value is.

E.g. 0 intensity is maximum filter effect and 1 intensity is unfiltered.

9 SoundTrigger Reference

SoundTrigger is a component used for easily playing/stopping SoundEvents on callbacks built into Unity like Enable, Disable, OnCollisionEnter etc.

They contain SoundEvents with modifiers and triggers which decide when it should play or stop.

SoundTriggers also have a radius handle, which is visually editable in the scene viewport for easy adjustment of how far SoundEvents should be heard.

All SoundTrigger components are multi-object editable.

Distance Radius

Distance of the SoundEvent (how far it should be heard).

Modifiers

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

See Modifiers for more info.

Triggers

On each trigger type you can select either:

Basic

Trigger

Tag

If enabled, the SoundEvent will only play if the triggering object has a tag matching the selected tags.

Collision

Velocity to Intensity

If enabled, the velocity magnitude will be passed as an intensity parameter.

Tag

If enabled, the SoundEvent will only play if the collision object has a tag matching the selected tags.

Mouse

10 SoundPhysics Reference

SoundPhysics is a component used for easily playing SoundEvents on physics collisions and friction.

Use intensity record in the SoundEvent for easy scaling of the velocity into a 0 to 1 range.

All SoundPhysics components are multi-object editable.

Intensity

Example of how to record and debug intensity.

For how to debug playing sounds in the scene/game view check out SoundManager Debug SoundEvents Live.

Impact

Impacts are played per contact point.

SoundEvent

The SoundEvent which is played on impact.

Collision Tag

If enabled the SoundEvents will only play on matching tags.

Friction

Friction is played when touching another object.

SoundEvent

The SoundEvent which is played on friction.

Collision Tag

If enabled the SoundEvents will only play on matching tags.

11 SoundPicker Reference

SoundPicker is a serializable class for easily selecting multiple SoundEvents and modifiers.

Add a serialized or public SoundPicker to a C# script and edit it in the inspector.

SoundPickers are multi-object editable.

SoundEvent

The SoundEvent to play.

Modifiers

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

See Modifiers for more info.

Example code:

using UnityEngine;
using Sonity;

public class ExampleSoundPicker : MonoBehaviour {

   
public SoundPicker soundPicker;

   
void Start() {
       
// Plays the SoundPicker at the position of the transform
       soundPicker.
Play(transform);
   }
}

12 SoundMix Reference

SoundMix objects are used for grouped control of e.g. volume for multiple SoundEvents at the same time.

They contain a parent SoundMix and modifiers for the SoundEvents.

All SoundMix objects are multi-object editable.

SoundMix objects are a higher performance solution of hierarchical volume control compared to AudioMixerGroups.

Example use; set up a “Master_MIX” and a “SFX_MIX” where the Master_MIX is a parent of the SFX_MIX.

Modifiers

Modifiers are used to control how SoundEvents are played (e.g. volume, polyphony, fade in length etc).

See Modifiers for more info.

13 SoundPolyGroup Reference

SoundPolyGroup objects are used to create a polyphony limit shared by multiple different SoundEvents.

The priority for voice allocation is calculated by multiplying the priority set in the SoundEvent by the volume of the instance.

A perfect use case would be to have a SoundPolyGroup for all bullet impacts of all the different materials so that when combined, they don’t use too many voices.

If you want simple individual polyphony control, use the polyphony modifier on the SoundEvent.

All SoundPolyGroup objects are multi-object editable.

Polyphony Limit

The maximum number of SoundEvents which can be played at the same time in this SoundPolyGroup.

Used in a SoundEvent:

14 SoundTag Reference

SoundTag objects are passed to modify how a SoundEvent should be played.

You can either pass them when playing a SoundEvent for setting the local SoundTag.

Or you can set the global SoundTag in the SoundManager .

This is useful for e.g; weapon reverb zones.

You can set the SoundTag corresponding to the acoustic space which the listener is in.

And when you play the SoundEvent, your gun reflection layers can correspond to the acoustic space.

Used in a SoundEvent:

15 SoundDataGroup Reference

SoundDataGroup objects are used to easily load and unload the audio data of the SoundEvents.

All SoundDataGroup objects are multi-object editable.

Child SoundDataGroups

Nesting SoundDataGroups makes it easy to load/unload all audio data or just parts of it.

SoundEvents

The SoundEvent whoms audio data will be loaded or unloaded

Drop SoundEvents/Folders Here

Here you can drag and drop SoundEvents or folders with SoundEvents in them.

Functions Load/Unload

// Loads the audio data for the AudioClips of the assigned SoundEvents.

public void LoadAudioData(bool includeChildren)

// Unloads the audio data for the AudioClips of the assigned SoundEvents.

public void UnloadAudioData(bool includeChildren)

Parameters

includeChildren

If to load/unload all the audio data of all the child SoundDataGroups also.

16 SoundManager Component Reference

The SoundManager is the master object which is used to play sounds and manage global settings.

An instance of this object is required in the scene in order to play SoundEvents.

You can add the pre-made prefab called “SoundManager” found in “Assets\Plugins\Sonity\Prefabs” to the scene.

Or you can add the “Sonity - Sound Manager” component to an empty GameObject in the scene, it works just as well.

Tip: If you need to play SoundEvents on Awake() when starting your game you need to edit the Script Execution Order.

Go to "Settings" -> "Script Execution Order" and add "Sonity.SoundManager".

Then set it to a negative value (like -50) so it loads before the code which you want to use Awake() to play sounds when starting your game.

16.1 SoundManager Settings

Disable Playing Sounds

Disables all the Play/PlayAtPosition functionality.

Useful if you've for example implemented temp sounds and don't want everyone else to hear them.

Global SoundTag

The selected Global SoundTag.

SoundEvents using global SoundTag are affected by this.

Distance Scale

Global range scale multiplier for all the sounds in Sonity.

Distance is calculated by Unity units of distance.

E.g. if Distance Scale is set to 100, a SoundEvent with the distance multiplier of 1 will be heard up to 100 Unity units away.

Enable Speed of Sound

Speed of sound is a delay based on the distance between the Audio Listener and a SoundEvent.

Speed of Sound Scale

Global speed of sound delay scale multiplier.

1 equals 430 Unity units per second. Uses Time.realtimeSinceStartup.

Use DontDestroyOnLoad()

Calls DontDestroyOnLoad() at Start for Sonity objects.

Which makes them persistent when switching scenes.

Debug Warnings

Makes Sonity output Debug Warnings if anything is wrong.

Debug in Play Mode

Makes Sonity output Debug Warnings if anything is wrong in Play Mode.

GUI Warnings

Makes Sonity show GUI Warnings if anything is wrong in the editor.

16.2 SoundManager Performance

Voice Limit

Maximum number of Voices.

If the limit is reached it will steal the Voice with the lowest priority.

If you need extra performance, you could try lowering the real and virtual voices to a lower number.

Voice Limit cannot be lower than Voice Preload.

Max Real Voices:

The maximum number of real (heard) AudioSources that can be played at the same time.

"Real Voices" should be the same as the "Voice Limit", or more if you play other sounds outside of Sonity.

Max Virtual Voices:

The maximum number of virtual (not heard) AudioSources that can be played at the same time.

This should always be more than the number of real voices.

You can change these values manually in:

"Edit" > "Project Settings" > "Audio"

Apply to Project Audio Settings

Applies the Voice Limit to the Project Audio Settings.

Sets "Real Voices" to the "Voice Limit".

You can change these values manually in:

"Edit" > "Project Settings" > "Audio"

Voice Preload

How many Voices to preload on Awake().

Voice Limit cannot be lower than Voice Preload.

Voice Disable Time

How long in seconds (using Time.realtimeSinceStartup) to wait before disabling a Voice when they've stopped playing.

Retriggering a voice which is not disabled is more performant than retriggering a voice which is disabled.

But having a lot of voices enabled which aren't used is also not good for performance, so don't set this value too high.

Voice Effect Limit

Maximum number of Voice Effects which can be used at the same time.

A Voice with any combination of waveshaper/lowpass/highpass counts as one Voice Effect.

If the values of a Voice Effect doesn't have any effect it is disabled automatically (e.g. distortion amount is 0).

If the Voice Effect limit is reached, the Voice Effects are prioritized by the Voices with the highest volume * priority.

Watch out for high load on the audio thread if set too high.

Try setting the buffer size to "Best Performance" in "Edit" > "Project Settings" > "Audio" if you want to run more Voice Effects.

16.3 SoundManager Debug SoundEvents Live

Debug SoundEvents live draws the names of all currently playing SoundEvent in the scene and/or game view.

Useful for debugging when you want to see what is playing and where.

In Scene View

Draws debug names in the Unity scene view.

Doesn't work in Unity versions older than 2019.1.

Example:

In Game View

Draws debug names in the Unity game view.

Only applied in the Unity editor.

Example:

Font Size

The font size of the text.

Volume to Alpha

How much of the volume of the SoundEvent will be applied to the transparency of the text.

E.g lower volumes will be more transparent.

Lifetime to Alpha

How much the lifetime of the SoundEvent will affect the transparency of the text.

Lifetime Fade Length

How long the fade should be.

Uses Time.realtimeSinceStartup.

Lifetime Start Color

The color the text should have when it starts playing.

Lifetime Fade Color

Which color the text should fade to over the lifetime.

Outline Color

The color of the text outline.

16.4 SoundManager Global Statistics

SoundEvents

Statistics of SoundEvents.

Created

The number of instantiated SoundEvents.

Active

The number of active SoundEvents.

Disabled

The number of unused and disabled SoundEvents.

Voices

Statistics of Voices.

Played

The number of played Voices since start.

Stolen

The number of stolen Voices since start.

Max Simultaneous

The maximum number of simultaneously playing Voices since start.

Created

The number of Voices in the pool.

Active

The number of Voices playing audio.

Inactive

The number of inactive Voices in the pool.

Paused

The number of paused Voices in the pool.

Stopped

The number of stopped Voices in the pool.

Voice Effects

Statistics of Voice Effects.

A Voice with any combination of waveshaper/lowpass/highpass counts as one Voice Effect

Active

The number of active Voice Effects.

Available

How many Voice Effects are available.

16.5 SoundManager Instance Statistics

Real-time statistics per SoundEvent Instance.

Available in Playmode.

Sort By

Which method to sort the list of SoundEvent Instances.

Name

Sorts by alphabetical order

Voices

Sorts by voice count

Plays

Sorts by number of plays

Volume

Sorts by volume

Time

Sorts by last time played

Show

Toggle what information to show about the SoundEvent Instances.

Show Active

How many are currently active.

Show Disabled

How many are currently disabled.

        

Show Voices

How many voices are currently used.

Show Plays

The number of total plays.

Show Volume

The current average volume.

17 SoundManager Functions Reference

The SoundManager is the master object which is used to play sounds and manage global settings.

An instance in the scene is required to play SoundEvents.

You can either add the pre-made prefab called “SoundManager” or add the “Sonity - Sound Manager” component to an empty GameObject in the scene.

Example code:

using UnityEngine;
using Sonity;

public class PlayStopExample : MonoBehaviour {

   
public SoundEvent soundEvent;

   
void PlayExample() {
       
// Plays the SoundEvent at the position of the transform
       
SoundManager.Instance.Play(soundEvent, transform);
   }

    void StopExample() {
       
// Stops the SoundEvent playing at the transform
       
SoundManager.Instance.Stop(soundEvent, transform);
   }
}

17.1 SoundManager.Instance Play

// Plays the SoundEvent at the position of the owner Transform

public void Play(SoundEvent soundEvent, Transform owner)
public void Play(SoundEvent soundEvent, Transform owner, SoundTag localSoundTag)
public void Play(SoundEvent soundEvent, Transform owner, params SoundParameterInternals[] soundParameterInternals)
public void Play(SoundEvent soundEvent, Transform owner, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

soundEvent

The SoundEvent to play

owner

The owner Transform

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

17.2 SoundManager.Instance PlayAtPosition

// Plays the SoundEvent at the Vector3 position with another Transform as the owner

public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Vector3 position)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Vector3 position, SoundTag localSoundTag)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Vector3 position, params SoundParameterInternals[] soundParameterInternals)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Vector3 position, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

// Plays the SoundEvent at the Transform position with another Transform as the owner

public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Transform position)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Transform position, SoundTag localSoundTag)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Transform position, params SoundParameterInternals[] soundParameterInternals)
public void PlayAtPosition(SoundEvent soundEvent, Transform owner, Transform position, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

soundEvent

The SoundEvent to play

owner

The owner Transform

position

The Transform or Vector3 where is should play at (Transform can follow position)

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

17.3 SoundManager.Instance Stop

// Stops the SoundEvent at the owner Transform

public void Stop(SoundEvent soundEvent, Transform owner, bool allowFadeOut = true)

// Stops the SoundEvent at the position Transform

public void StopAtPosition(SoundEvent soundEvent, Transform position, bool allowFadeOut = true)

// Stops all the SoundEvents at the owner Transform

public void StopAllAtOwner(Transform owner, bool allowFadeOut = true)

// Stops the SoundEvent everywhere

public void StopEverywhere(SoundEvent soundEvent, bool allowFadeOut = true)

// Stops all SoundEvents

public void StopEverything(bool allowFadeOut = true)

Parameters

soundEvent

The SoundEvent to stop

owner

The owner Transform

position

The position Transform

allowFadeOut

If the SoundEvent should be allowed to fade out. Otherwise it is going to be stopped immediately

17.4 SoundManager.Instance Play2D

Useful if you want to play SoundEvents without passing an owner.

// Plays the SoundEvent with the 2D Transform as owner

public void Play2D(SoundEvent soundEvent)
public void Play2D(SoundEvent soundEvent, SoundTag localSoundTag)
public void Play2D(SoundEvent soundEvent, params SoundParameterInternals[] soundParameterInternals)
public void Play2D(SoundEvent soundEvent, SoundTag localSoundTag, params SoundParameterInternals[] soundParameterInternals)

Parameters

soundEvent

The SoundEvent to play

localSoundTag

The SoundTag which will determine the Local SoundTag of the SoundEvent

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

17.5 SoundManager.Instance Stop2D

// Stops the SoundEvent at the 2D Transform

public void Stop2D(SoundEvent soundEvent, bool allowFadeOut = true)

// Stops all SoundEvents at the 2D Transform

public void StopAllAt2D(Transform owner, bool allowFadeOut = true)

Parameters

soundEvent

The SoundEvent to stop

allowFadeOut

If the SoundEvent should be allowed to fade out. Otherwise it is going to be stopped immediately

17.6 SoundManager.Instance PlayMusic

Useful if you want to play music with automatic stopping of the old music when playing a new song.

// Plays the SoundEvent at the SoundManagers music Transform

public void PlayMusic(SoundEvent soundEvent, bool stopAllOtherMusic = true, bool allowFadeOut = true)

public void PlayMusic(SoundEvent soundEvent, bool stopAllOtherMusic = true, bool allowFadeOut = true, params SoundParameterInternals[] soundParameterInternals)

Parameters

soundEvent

The SoundEvent to play

stopAllOtherMusic

If all other SoundEvents played at the SoundManager music Transform should be stopped

allowFadeOut

If the other stopped SoundEvent should be allowed to fade out. Otherwise they are going to be stopped immediately

soundParameterInternals

For example SoundParameterVolumeDecibel is used to modify how the SoundEvent is played

17.7 SoundManager.Instance StopMusic

// Stops the SoundEvent playing at the SoundManagers music Transform

public void StopMusic(SoundEvent soundEvent, bool allowFadeOut = true)

// Stops the all SoundEvents playing at the SoundManagers music Transform

public void StopAllMusic(bool allowFadeOut = true)

Parameters

soundEvent

The SoundEvent to stop

allowFadeOut

If the other stopped SoundEvent should be allowed to fade out. Otherwise they are going to be stopped immediately

17.8 SoundManager.Instance Get SoundEvent State

// If playing it returns SoundEventState.Playing

// If not playing, but it is delayed it returns SoundEventState.Delayed

// If not playing, but it is delayed it returns SoundEventState.Delayed

// If not playing and it is not delayed it returns SoundEventState.NotPlaying

// If the SoundEvent or Transform is null it returns SoundEventState.NotPlaying

public SoundEventState GetSoundEventState()

17.9 SoundManager.Instance Get Length or Time

// Returns the length (in seconds) of the AudioClip in the last played AudioSource

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

// pitchSpeed determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

public float GetLastPlayedClipLength(SoundEvent soundEvent, Transform owner, bool pitchSpeed)

// Returns the current time (in seconds) of the AudioClip in the last played AudioSource

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

// pitchSpeed determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

public float GetLastPlayedClipTime(SoundEvent soundEvent, Transform owner, bool pitchSpeed)

// Returns the max length (in seconds) of the SoundEvent (calculated from the longest audioClip)

// Is scaled by the pitch of the SoundEvent and SoundContainer

// Does not take into account random, intensity or parameter pitch

// Returns 0 if the SoundEvent is null

public float GetMaxLength(SoundEvent soundEvent)

// Returns the time (in seconds) since the SoundEvent was played

// Calculated using Time.realtimeSinceStartup

// Returns 0 if the InstanceSoundEvent is not playing

// Returns 0 if the SoundEvent or Transform is null

public float GetTimePlayed(SoundEvent soundEvent, Transform owner)

Parameters

soundEvent

The SoundEvent to get length or time from

owner

The owner Transform

pitchSpeed

Determines if it should be scaled by pitch. E.g. -12 semitones will be twice as long

forceUpdate

Force recheck the max length, otherwise will use cached length after first check

17.10 SoundManager.Instance SoundTag

// Sets the global SoundTag

public void SetGlobalSoundTag(SoundTag soundTag)

// Returns the global SoundTag

public SoundTag GetGlobalSoundTag()

17.11 SoundManager.Instance Global Distance Scale

// Sets the global distance scale (default is a scale of 100 units)

public void SetGlobalDistanceScale(float distanceScale)

// Returns the global distance scale

public float GetGlobalDistanceScale()

17.12 SoundManager.Instance Speed Of Sound

// Set if speed of sound should be active

public void SetSpeedOfSoundEnabled(bool speedOfSoundEnabled)

// Set the speed of sound scale

// The default is a multiplier of 1 (by the base value of 340 unity units per second)

public void SetSpeedOfSoundScale(float speedOfSoundScale)

// Returns the speed of sound scale

public float GetSpeedOfSoundScale()

17.13 SoundManager.Instance Voice Limit

// Sets the Voice limit

public void SetVoiceLimit(int voiceLimit)

// Returns the Voice limit

public int GetVoiceLimit()

// Sets the VoiceEffect limit

public void SetVoiceEffectLimit(int voiceEffectLimit)

// Returns the VoiceEffect limit

public int GetVoiceEffectLimit()

17.14 SoundManager.Instance Disable Playing Sounds

// Disables/enables all the Play/PlayAtPosition functionality

public void SetDisablePlayingSounds(bool disablePlayingSounds)

// If the Play/PlayAtPosition functionality is disabled

public bool GetDisablePlayingSounds()

17.15 SoundManager.Instance Get Transform

// Returns the Transform of the SoundManager

public Transform GetTransformSoundManager()

// Returns the Transform used by the eg. PlayMusic() functions

public Transform GetTransformMusic()

// Returns the Transform used by the eg. Play2D() functions

public Transform GetTransform2D()