GameMaker offers a selection of audio effects, such as reverb, delay, bitcrusher, parametric EQ, etc.
Sounds are always played through "buses". All sounds in GameMaker are played through its main bus.
Effects are applied on buses. GameMaker allows you to:
Audio effects are processed on an "audio bus".
GameMaker has one audio bus by default, the main audio bus, which you can access through the built-in audio_bus_main struct.
All audio that you play in GameMaker ends up on this audio bus, whether that is 2D audio, 3D audio or emitter audio. This is referred to as all audio being routed to the main bus.
You can create your own bus to apply effects to a few sounds. All custom buses are routed to the main bus, so the parameters and effects on the main bus are applied to all other buses.
NOTE An audio bus can have a maximum of 8 effects assigned to its effects array. Set a slot to undefined to remove an effect.
The quickest way to apply effects to all audio is by adding them to the main bus:
var _ef_reverb = audio_effect_create(AudioEffectType.Reverb1);
_ef_reverb.size = 0.6;
_ef_reverb.mix = 0.5;
audio_bus_main.effects[0] = _ef_reverb;
This first creates a new audio effect of type AudioEffectType.Reverb1. Its parameters are then set by directly setting the members of the returned AudioEffect Struct.
The size of the reverb effect is set to 0.6 and the mix value to 0.5 (how much of the effect can be heard from 0-1, similar to lerp).
The effect is then assigned to the main audio bus's effects array. Assigning the effect to a slot in the array enables the effect.
NOTE Because the effect is processed from the moment it's assigned, it's good practice to first set the effect's parameters and only then assign the effect to the effects array. This will make sure that no transition from no effect to an audible effect occurs.
Sometimes you might want to turn off individual effects or turn off all effects on a bus. You can do this by setting bypass for an effect or a bus to true:
// Bypassing an effect
audio_bus_main.effects[0].bypass = true;
// Bypassing all effects on a bus
audio_bus_main.bypass = true;
Setting bypass to true means that what comes out of the bus or effect is the same as what goes in -- the input is the output.
For a single effect this means that this effect is skipped, for a bus this means that all effects on the bus are skipped.
By default audio emitters output directly to the main bus, so the audio that is played on an emitter will end up there and have the same effects applied as all other audio.
You can add effects to an audio emitter by creating a new audio bus using audio_bus_create and assigning it to the emitter using audio_emitter_bus:
emitter = audio_emitter_create(); // Emitter is created
emitter_bus = audio_bus_create(); // Bus is created
audio_emitter_bus(emitter, emitter_bus); // Emitter is assigned to bus
Assigning an emitter to a bus will make the emitter output to that bus. You can assign any number of emitters to a bus.
Any audio output on a bus created using audio_bus_create still ends up on GameMaker's main audio bus.
This means that you can apply a delay effect to all sounds that are played on an emitter, and a reverb effect on the main audio bus. Audio that is played on the emitter is processed by the audio bus assigned to it so it will be heard with the delay effect from the emitter bus and the reverb effect from the main bus. Audio that is played directly on the main bus will only have the reverb effect applied.
To get the audio bus that is assigned to an emitter, use audio_emitter_get_bus.
NOTE As previously mentioned, audio can only be processed on a different bus than the main bus by playing it on an emitter (using audio_play_sound_on).
A single audio effect struct returned by audio_effect_create can be assigned to multiple effect slots (either on the same bus or on different buses):
ef_lpf = audio_effect_create(AudioEffectType.LPF2, {cutoff: 300, q: 1.5});
bus_1.effects[0] = ef_lpf;
bus_1.effects[4] = ef_lpf;
bus_2.effects[0] = ef_lpf;
For each of these assignments a new effect is instantiated. You could compare this to Objects And Instances; the struct returned by audio_effect_create returns an "object" and every assignment creates a new "instance" of it. The "instance" is that what actually processes the audio for the effect slot it is assigned to. Each effect slot gets its own "instance" of the effect.
When you make changes to any of the variables of the ef_lpf struct here, the effect's parameters will change accordingly on bus_1.effects[0], bus_1.effects[4] and bus_2.effects[0].
When targeting HTML5, audio buses and effects functionality will be limited in the following situations:
In these situations audio buses and effects functions, enums and structs can still be used without generating GML errors, but they will mostly have no audible effect (the exception to this being audio bus gain and bus routing).