Manual

Manual

Buses and effects

Every sound your game plays goes through its mix: a set of buses, each with a fader, its effects, and the bus it sends to. This page covers the mix, the Audio panel where you lay it out as a mixer's strips, the effects a bus can run and their settings, and how your code plays sounds on a bus and changes the mix while the game runs. How sounds are played is on Sounds and audio sources.

The mix

The mix is made of buses. Master comes first and sends to the speakers. Every other bus sends to Master, or to a bus before it, so a sound played on a bus is mixed through that bus, through each bus it sends to, and through Master on its way out. A typical game has a bus each for its music, its sound effects and its interface, all sending to Master, so the player can turn each up and down on its own.

The mix is saved in settings/audio.json, beside your game's assets, and a build packs it, so a built game plays the mix as you saved it. A game with no audio.json has Master alone.

The Audio panel

Open it with Window ▸ Audio (Ctrl+8). It sits beside Logs along the bottom of the default layout, and shows each bus as a strip, side by side, Master first. + Add Bus, after the last strip, adds a bus called New Bus, sending to Master.

Each strip, from the top:

PartWhat it does
The nameClick it to type a new name. Your code plays on a bus by its name, so no two buses share one. Master is always called Master.
SSolo: hear this bus alone, with what it is heard through.
MMute: silence it.
BBypass: hear it without its effects.
+Add Effect: adds an effect at the bottom of the bus's list.
The faderIts volume, in decibels
Two metersHow loud each channel is as it leaves the bus
The readingIts volume, such as -6.0 dB
Its effectsOne row each, in the order they run
SendThe bus it sends to: Master, or a bus to its left. Master's says Speakers.
The timerWhether its sounds follow the game's time scale (see Follow the time scale)

Right-click a strip for Reset Volume, which puts its fader back at 0 dB, and Delete Bus. Master can't be deleted, since every bus is heard through it. When you delete a bus, each bus that sent to it sends to Master.

Each change is written to settings/audio.json when you finish it: a fader let go, a button pressed, a name typed. You hear a change as you make it, whether the game is playing or not, and since it is a change to the file, it stays after you stop. If the file can't be read, the panel says why in amber over the strips and changes nothing.

Faders and meters

A fader goes from -80 dB at its bottom to +6 dB at its top, with 0 dB, the bus as it is, three quarters of the way up, and -6 dB, about half as loud, half way. Most of its travel is in the range a mix is made in. Hold Ctrl while dragging to move it a whole decibel at a time. At -60 dB and below, a bus is silent.

The two meters beside the fader show the loudest sample of the left and right channels as they leave the bus, after its effects and its fader, falling back once the sound has gone. They are green for most of their height, then yellow, then red at the top.

Solo, Mute and Bypass

M silences its bus. S solos it: while any bus is soloed, a bus is heard only if it is soloed, is on the way from a soloed bus to Master, or sends to a soloed bus. So soloing your music bus lets you hear the music alone, through Master.

B bypasses the bus's effects: each is turned dry, so you hear the bus as it would be without them, and nothing stops playing.

Solo and Mute are saved in the mix with everything else, so take them off before you build.

Follow the time scale

Sounds play at their own speed whatever the game's time does. Click a bus's timer to make its sounds follow the game's time scale instead: they play at their pitch times the time scale, slowing down and speeding up with it, and are held while it is zero. The buses that send to it follow too, so their timers are shown dim, saying which bus they follow it through.

A game's sound effects usually follow the time scale, while its music and its interface's sounds, on buses of their own, do not. A sound held by a time scale of zero carries on as the scale comes back, but a sound your code paused stays paused. Set the time scale with world.Time.Scale (see Systems at a fixed rate).

Effects

Each bus runs its effects in the order its strip lists them, before its fader. Click + on a strip and pick a kind to add one at the bottom of the list, picked, so the Inspector shows its settings.

Each effect is a row of its strip: a grip, a tick, and its name, which is grayed while it is off or its bus is bypassed. Drag a row to put it elsewhere in the list. Click the tick to turn it off or on: an effect that is off is turned dry, so you hear the bus without it. Right-click a row for Move Up, Move Down, Reset to Defaults, which puts every setting back where a new effect starts, and Remove.

Click an effect's row to edit it in the Inspector. Its header says where it is, such as Effect 0 on Music, with its tick and a ⋮ menu holding the same items as its row's. Under them is a slider for each setting, which you hear as you drag it and which is saved when you let go. A frequency or a time moves along its slider as a logarithm, so the low end has as much room as the high. Resting the pointer on a setting's name says its range and where a new effect starts.

EffectWhat it doesSettings, and where a new one starts
ReverbA room's reverberationRoom Size from 0 to 0.99 (0.9), bigger the more; Damping from 0 to 1 (0.1), how fast the highs leave it; Stereo Width from 0, mono, to 1 (1); Mix (50%)
Low PassTakes away what is above a frequencyCutoff from 20 Hz to 20 kHz (1 kHz); Resonance from 0 to 1 (0), how much it rings at its cutoff; Mix (100%)
High PassTakes away what is below a frequencyAs Low Pass
EQLifts or lowers the lows, a band in the middle, and the highsLow Gain from -24 to +24 dB (0) at Low Frequency, 20 Hz to 1 kHz (200 Hz); Mid Gain (0) at Mid Frequency, 100 Hz to 10 kHz (1 kHz), with Mid Width from 0.1 to 10 (1); High Gain (0) at High Frequency, 1 kHz to 20 kHz (5 kHz)
DelayAn echo, which feeds back into itselfTime from 10 to 2,000 ms (500 ms); Feedback from -60 to 0 dB (-6 dB); Mix (50%)
CompressorTurns down what is louder than a thresholdThreshold from -60 to 0 dB (-20 dB); Ratio from 1:1 to 20:1 (4:1); Attack from 0.1 to 100 ms (10 ms); Release from 10 to 1,000 ms (100 ms); Makeup Gain from 0 to 24 dB (0); Mix (100%)
DistortionClips what is driven past full scaleKind, Hard Clip or Soft Clip (Hard Clip); Drive from 0 to 48 dB (0); Mix (100%)

Mix is how much of what the effect makes is heard, from none of it to all of it. The EQ's gains of 0 dB leave its bands as they are. A ratio of 4:1 turns a sound four decibels over the threshold down to one decibel over.

A Delay's Time is set as the mix's tracks are made, so changing it makes them again, which stops what is playing.

Sounds on a bus

An Audio Source plays on the bus its Output names. Your code names the bus a sound plays on with PlayOptions.Bus:

Sound click = world.Audio.Play(clickClip, new PlayOptions { Bus = "UI" });

An Audio Source keeps its bus by an identity of the bus's own, so renaming a bus keeps every Audio Source on it. An Audio Source whose bus was deleted plays on Master, as does a sound your code plays on a bus the mix doesn't have, which the log says.

Buses from code

Your code can change the mix while the game plays, by each bus's name. A change lasts until play ends, and then the mix is the project's again:

world.Audio.SetBusVolume("Music", -12f);          // in decibels, from -80 to +6world.Audio.SetBusVolumeLinear("SFX", 0.5f);      // as a share, from 0, silent, to 1, the fader at 0 dBworld.Audio.SetBusMute("Music", true);world.Audio.SetBusBypass("SFX", true);

SetBusVolumeLinear suits a settings menu's slider, which goes from 0 to 1. Decibels.FromLinear and Decibels.ToLinear turn between the two: a half is about -6 dB and a tenth -20 dB.

An effect is named by its bus and its place in the bus's list, the top one 0. Turn one off or on, or change a setting, in the setting's own unit, over a fade:

// The camera went under water: muffle the SFX bus's first effect, a Low Pass.world.Audio.SetBusEffect("SFX", 0, BusEffectValue.Cutoff, 600f, fade: 0.5f);world.Audio.SetBusEffectEnabled("Music", 1, false);

A Mix is set as a share from 0 to 1, and a setting out of its range is kept to it. A Delay's Time can't be changed from code. A bus, an effect or a setting the mix doesn't have changes nothing, and the log says so. HasBus(name) says whether the mix has a bus of that name.

BusLevels() says how loud each bus has been since you last asked, in the mix's order: the loudest sample of each channel as it leaves the bus's fader, from 0 to 1 at full scale. Use it to draw a meter of your own, or to make something pulse with the music.

The mix file

settings/audio.json holds each bus by its identity and its name, and only what differs from where a bus starts:

{
  "abyssAudio": 2,
  "next": 3,
  "buses": [
    { "id": 0, "name": "Master" },
    { "id": 1, "name": "Music", "volume": -6, "send": 0 },
    { "id": 2, "name": "SFX", "send": 0, "followsTimeScale": true, "effects": [ { "kind": "lowPass", "on": false, "cutoff": 2400 } ] }
  ]
}

next is the identity the next bus gets. An identity is never given twice, so a bus added after one was deleted is never mistaken for it.

In the Scripting API

  • WorldAudio: buses turned, muted, bypassed and their effects changed from code, and their levels read.
  • BusEffectKind and BusEffectValue: the kinds of effect, and the settings code changes.
  • Decibels: volumes as decibels and as shares.
  • BusLevel: how loud a bus has been.
  • AudioMix and AudioBus: the mix and its buses, as settings/audio.json holds them.