Audio effects

Every bus in ExoJS carries a filter chain — an ordered list of AudioEffect instances that process audio in series. Filters are applied at the bus level, which means adding a filter to app.audio.music affects every voice routing through the music bus. You can also create custom buses for isolated effect chains.

The filter chain

A bus’s filter chain is inputNode → [filter₁ → filter₂ → ...] → panNode → outputNode. Adding a filter appends it to the end of the chain. Order matters — a compressor before reverb sounds different from a compressor after reverb.

import { CompressorEffect, DelayEffect, ReverbEffect } from '@codexo/exojs-audio-fx';

const compressor = new CompressorEffect({ threshold: -20, ratio: 8 });
const reverb = new ReverbEffect({ wet: 0.3 });
const delay = new DelayEffect({ delaySeconds: 0.25, wet: 0.2, feedback: 0.4 });

app.audio.master.addEffect(compressor);
app.audio.master.addEffect(reverb);
app.audio.sound.addEffect(delay);

Remove a filter to take it out of the chain without destroying it:

app.audio.master.removeEffect(reverb);

Filters are reusable — move one from bus to bus by removing it from the old bus and adding it to the new one. Destroy a filter with filter.destroy() when it’s no longer needed anywhere.

CompressorEffect

A dynamics compressor that clamps the dynamic range of audio passing through it. Useful for evening out volume, adding punch to SFX, and preventing clipping when many sounds play simultaneously:

const compressor = new CompressorEffect({
    threshold: -24,   // dBFS — signals above this get compressed
    ratio: 12,        // 1:1 = no compression, 20:1 = near-limiting
    attack: 0.003,    // seconds — how fast compression kicks in
    release: 0.25,    // seconds — how fast it lets go
    knee: 30,         // dB — softens the threshold transition
});

app.audio.master.addEffect(compressor);

All properties are live get/set. The compressor.reduction getter returns the current gain reduction in dB (always ≤ 0) — useful for live level metering:

update(delta) {
    const gr = this.compressor.reduction;
    this.meterBar.height = Math.abs(gr) * 10; // scale to pixels
}

ReverbEffect and DelayEffect

ReverbEffect simulates acoustic space by convolving audio through a procedurally-generated impulse response:

const reverb = new ReverbEffect({
    durationSeconds: 2,   // IR length — longer = bigger space
    decay: 2,             // exponential decay factor
    wet: 0.4,             // 0 = dry only, 1 = wet only
});

DelayEffect creates an echo with configurable feedback:

const delay = new DelayEffect({
    delaySeconds: 0.3,    // echo interval
    feedback: 0.45,       // 0 = one echo, 0.95 = long tail
    wet: 0.5,             // dry/wet mix
});

Both expose live wet, delaySeconds, feedback, decay, and durationSeconds properties. Changing durationSeconds or decay on a reverb rebuilds the impulse response — prefer to keep these stable during playback.

DuckingEffect

A sidechain compressor — when the sidechain bus exceeds a threshold, the main signal is attenuated. Common use case: automatically lower music volume when voice-over plays:

import { AudioBus } from '@codexo/exojs';
import { DuckingEffect } from '@codexo/exojs-audio-fx';

const voiceBus = new AudioBus('voice-over', { parent: app.audio.master });
app.audio.registerBus(voiceBus);

const ducker = new DuckingEffect({
    sidechain: voiceBus,
    threshold: -30,   // dBFS — sidechain level that triggers ducking
    ratio: 6,         // gain reduction ratio
    attackMs: 25,     // how fast ducking engages
    releaseMs: 260,   // how fast audio recovers after sidechain drops
});

app.audio.music.addEffect(ducker);

threshold, ratio, attackMs, and releaseMs are live get/set. The filter.ready promise resolves when the worklet processor is loaded and the chain is fully wired.

Shaping and modulation

Several filters cover tone shaping and modulation effects:

import { HighpassFilter, LowpassFilter } from '@codexo/exojs';
import { ChorusEffect, EqualizerEffect } from '@codexo/exojs-audio-fx';

// Three-band equalizer — low shelf, peaking mid, high shelf
const eq = new EqualizerEffect({ low: 3, mid: -2, high: 4 });

// Frequency cuts — animate the frequency property for sweeps
const lp = new LowpassFilter({ frequency: 2000, resonance: 1 });
const hp = new HighpassFilter({ frequency: 200, resonance: 1 });

// Modulated delay for thickness and doubling (native nodes, instant startup)
const chorus = new ChorusEffect({ rateHz: 1.5, depthMs: 5, wet: 0.5 });

All parameters on these effects are live get/set. The EqualizerEffect API reference documents individual band frequencies; the ChorusEffect and LowpassFilter references cover constructor options in detail.

Distortion and modulation effects

Like ChorusEffect, the six filters below are built from native Web Audio nodes — they’re ready the instant you construct them, with no worklet loading or ready promise involved. All expose a live wet dry/wet mix; see each API reference for the full option list.

DistortionEffect

Soft-clip saturation through a tanh-based WaveShaperNode curve, followed by a tone-control lowpass on the wet path. drive (0..1) controls clip intensity and tone (0..1) sweeps the wet-path cutoff logarithmically from 100 Hz to 20 kHz:

import { DistortionEffect } from '@codexo/exojs-audio-fx';

const dist = new DistortionEffect({ drive: 0.6, tone: 0.7, wet: 0.8 });
app.audio.sound.addEffect(dist);

PhaserEffect

Sweeps a cascade of allpass filters with a sine LFO, producing moving notches in the spectrum. stages (an even number, 2..12) sets the notch count and feedback (0..0.9) sharpens the resonance:

import { PhaserEffect } from '@codexo/exojs-audio-fx';

const phaser = new PhaserEffect({ stages: 6, rateHz: 0.3, depth: 0.8, feedback: 0.4, wet: 0.6 });
app.audio.music.addEffect(phaser);

FlangerEffect

A short (0.5–20 ms) LFO-modulated delay with a feedback loop, producing the classic sweeping “jet-plane” comb-filter sound. Unlike ChorusEffect — a longer, feedback-free delay used for thickening — the feedback here reinforces phase cancellation:

import { FlangerEffect } from '@codexo/exojs-audio-fx';

const flanger = new FlangerEffect({ delayMs: 3, depthMs: 2, rateHz: 0.25, feedback: 0.5, wet: 0.5 });
app.audio.sound.addEffect(flanger);

TremoloEffect

Amplitude-modulates the signal with a sine LFO for classic volume pulsing. Set autoPan: true to have the same LFO drive stereo panning in sync with the pulse:

import { TremoloEffect } from '@codexo/exojs-audio-fx';

const tremolo = new TremoloEffect({ rateHz: 5, depth: 0.7, autoPan: true });
app.audio.music.addEffect(tremolo);

RingModulatorEffect

Multiplies the input by a carrier oscillator, producing sum/difference sidebands while suppressing the fundamental. Mid-range carrier frequencies (100–1000 Hz) give the classic robotic ring-mod timbre; sub-audio rates (< 20 Hz) sound like tremolo:

import { RingModulatorEffect } from '@codexo/exojs-audio-fx';

const ringMod = new RingModulatorEffect({ frequency: 220, waveform: 'sine', wet: 0.8 });
app.audio.sound.addEffect(ringMod);

AutoWahEffect

An envelope-driven wah: a rectifier and smoothing filter track input loudness and sweep a resonant bandpass filter upward from baseFrequency. sensitivity sets the maximum sweep in Hz and responseMs controls how snappy or legato the response feels:

import { AutoWahEffect } from '@codexo/exojs-audio-fx';

const wah = new AutoWahEffect({ baseFrequency: 300, sensitivity: 2500, q: 5, wet: 0.8 });
app.audio.sound.addEffect(wah);

Ping-pong delay, limiting, and convolution

PingPongDelayEffect

A stereo delay whose taps cross-feed between channels, bouncing echoes hard-left/hard-right. delayTime sets the per-tap interval in seconds and feedback (0..0.9) controls how long the bounce sustains:

import { PingPongDelayEffect } from '@codexo/exojs-audio-fx';

const pingPong = new PingPongDelayEffect({ delayTime: 0.3, feedback: 0.5, wet: 0.5 });
app.audio.music.addEffect(pingPong);

LimiterEffect

A brick-wall limiter — a DynamicsCompressorNode fixed at a high ratio and hard knee — meant as a safety net at the end of a chain to catch peaks before they clip:

import { LimiterEffect } from '@codexo/exojs-audio-fx';

const limiter = new LimiterEffect({ threshold: -3, release: 0.1 });
app.audio.master.addEffect(limiter);

ConvolutionEffect

Convolves the signal with a real impulse response instead of ReverbEffect’s procedurally generated one — useful for captured spaces, cabinet/speaker simulation, or telephone-style filtering. Pass a decoded AudioBuffer or a loaded Sound; call setImpulse() to swap the IR later:

import { ConvolutionEffect } from '@codexo/exojs-audio-fx';
import { Sound } from '@codexo/exojs';

await loader.load(Sound, { hall: 'hall.wav' });
const convReverb = new ConvolutionEffect({ impulse: loader.get(Sound, 'hall'), wet: 0.6 });
app.audio.master.addEffect(convReverb);

Worklet-based effects

Four filters use AudioWorkletProcessor and load asynchronously. They extend WorkletEffect, which exposes a ready promise — the engine registers the worklet, you construct the filter and add it to a bus, and the chain rewires automatically once the processor is loaded.

import { BitCrusherEffect, GranularEffect, PitchShiftEffect, VocoderEffect } from '@codexo/exojs-audio-fx';

// Granular pitch shifting (0.25x to 4x)
const shifter = new PitchShiftEffect({ pitch: 1.2, wet: 1.0 });

// Cross-synthesis between a carrier signal and a modulator bus
const vocoder = new VocoderEffect({ modulator: modulatorBus, numBands: 14 });

// Slices input into short grains with random pitch and time offset
const granular = new GranularEffect({ grainSize: 0.05, density: 50, wet: 1.0 });

// Lo-fi bit-depth and sample-rate reduction
const crusher = new BitCrusherEffect({ bits: 4, frequencyReduction: 0.3, wet: 0.8 });

All four have live wet controls. PitchShiftEffect exposes pitch; GranularEffect exposes grainSize, density, spread, pitchMin, and pitchMax for real-time grain cloud manipulation; BitCrusherEffect exposes bits (1..16, quantization depth) and frequencyReduction (0..1, sample-and-hold rate). The API reference documents the full constructor options for each.

Custom buses

Bus-level filters affect everything on that bus. Create isolated chains for specific sound categories:

const ambientBus = new AudioBus('ambient', { parent: app.audio.master });
app.audio.registerBus(ambientBus);

ambientBus.addEffect(new ReverbEffect({ wet: 0.6, durationSeconds: 3 }));
ambientBus.addEffect(new LowpassFilter({ frequency: 800 }));

const wind = loader.get(Sound, 'wind');
// Route this play onto the ambient bus — reverb + lowpass applied.
this.app.audio.play(wind, { bus: ambientBus, loop: true });

registerBus stores the bus by name, retrievable later via app.audio.getBus('ambient'). unregisterBus removes and destroys a custom bus. The three built-in buses (master, music, sound) cannot be unregistered.

Examples

import { Application, AudioStream, Color, Graphics, Scene, Text } from '@codexo/exojs';
import { CompressorEffect } from '@codexo/exojs-audio-fx';
import { mountControls } from '@examples/runtime';

const app = new Application({
    canvas: {
        width: 1280,
        height: 720,
        mount: document.body,
        sizingMode: 'fit',
    },
    clearColor: Color.black,
    loader: {
        basePath: 'assets/',
    },
});

type CompressorParam = 'threshold' | 'ratio' | 'attack' | 'release';

interface SliderDef {
    key: CompressorParam;
    min: number;
    max: number;
}

const sliders: SliderDef[] = [
    { key: 'threshold', min: -60, max: 0 },
    { key: 'ratio', min: 1, max: 16 },
    { key: 'attack', min: 0.001, max: 0.2 },
    { key: 'release', min: 0.02, max: 0.8 },
];

class CompressorScene extends Scene {
    private music!: AudioStream;
    private filter!: CompressorEffect;
    private gfx!: Graphics;
    private labels!: Text[];
    private meterLabel!: Text;
    private tapPrompt!: Text;
    private drag = -1;
    // Canvas-relative bar layout computed in init().
    private barX = 0;
    private barW = 0;
    private labelX = 0;
    private rowY: number[] = [];
    private meterY = 0;
    private hud!: ReturnType<typeof mountControls>;

    override async load(loader): Promise<void> {
        await loader.load(AudioStream, { music: 'audio/demo-loop-main.ogg' });
    }

    override init(loader): void {
        const { width, height } = this.app.canvas;

        // Wide horizontal bars centred on the 16:9 canvas; labels sit to the left.
        this.barW = width * 0.45;
        this.barX = width * 0.32;
        this.labelX = width * 0.1;
        this.rowY = sliders.map((_, i) => height * 0.26 + i * 90);
        this.meterY = this.rowY[this.rowY.length - 1] + 100;

        this.music = loader.get(AudioStream, 'music');
        this.filter = new CompressorEffect();
        app.audio.music.addEffect(this.filter);

        this.gfx = new Graphics();
        this.labels = sliders.map(() => new Text('', { fillColor: Color.white, fontSize: 16 }));
        this.meterLabel = new Text('', { fillColor: Color.white, fontSize: 16 });
        this.meterLabel.setPosition(this.labelX, this.meterY - 6);

        // Shown while the browser still blocks audio (`app.audio.locked`); the
        // first click or keypress unlocks it and the queued music starts.
        this.tapPrompt = new Text('Click or press any key to start audio', { fillColor: Color.white, fontSize: 22, align: 'center' })
            .setAnchor(0.5, 0.5)
            .setPosition(width / 2, height - 48);

        this.hud = mountControls({
            title: 'Compressor',
            controls: [{ keys: 'Drag', action: 'sweep a parameter bar' }],
            status: 'Click or press any key to start…',
            hint: 'The red bar shows live gain reduction — louder peaks pull it further right.',
        });

        this.app.input.onPointerDown.add(p => {
            this.drag = this.sliderAt(p.y);
            this.apply(p.x);
        });
        this.app.input.onPointerMove.add(p => {
            this.apply(p.x);
        });
        this.app.input.onPointerUp.add(() => {
            this.drag = -1;
        });

        // Core defers playback until the AudioContext unlocks on the first
        // gesture, then starts automatically.
        this.app.audio.play(this.music, { loop: true, volume: 0.8 });
        this.hud.setStatus('Compressing music bus…');
    }

    private sliderAt(y: number): number {
        for (let i = 0; i < sliders.length; i++) if (Math.abs(y - this.rowY[i]) <= 16) return i;
        return -1;
    }

    private apply(x: number): void {
        if (this.drag < 0) return;
        const def = sliders[this.drag];
        const t = Math.max(0, Math.min(1, (x - this.barX) / this.barW));
        this.filter[def.key] = def.min + (def.max - def.min) * t;
    }

    private value(def: SliderDef): number {
        return this.filter[def.key];
    }

    override draw(context): void {
        context.backend.clear();
        this.gfx.clear();
        for (let i = 0; i < sliders.length; i++) {
            const def = sliders[i];
            const y = this.rowY[i];
            const val = this.value(def);
            const t = (val - def.min) / (def.max - def.min);
            this.gfx.fillColor = new Color(70, 70, 70);
            this.gfx.drawRectangle(this.barX, y - 6, this.barW, 12);
            this.gfx.fillColor = new Color(120, 200, 255);
            this.gfx.drawRectangle(this.barX, y - 6, this.barW * t, 12);
            this.labels[i].text = `${def.key}: ${val.toFixed(def.key === 'ratio' ? 2 : 3)}`;
            this.labels[i].setPosition(this.labelX, y - 12);
            context.render(this.labels[i]);
        }

        const reduction = this.filter.reduction;
        const meterT = Math.max(0, Math.min(1, -reduction / 24));
        this.gfx.fillColor = new Color(70, 70, 70);
        this.gfx.drawRectangle(this.barX, this.meterY, this.barW, 12);
        this.gfx.fillColor = new Color(255, 140, 140);
        this.gfx.drawRectangle(this.barX, this.meterY, this.barW * meterT, 12);
        this.meterLabel.text = `gain reduction: ${reduction.toFixed(1)} dB`;
        context.render(this.meterLabel);

        context.render(this.gfx);

        if (this.app.audio.locked) {
            context.render(this.tapPrompt);
        }
    }
}

app.start(new CompressorScene());

Interactive compressor with live gain-reduction meter — drag sliders to adjust threshold, ratio, attack, and release.

import { Application, Color, Graphics, Scene, Sound, Text } from '@codexo/exojs';
import { DelayEffect, ReverbEffect } from '@codexo/exojs-audio-fx';
import { mountControlPanel, mountControls } from '@examples/runtime';

const app = new Application({
    canvas: {
        width: 1280,
        height: 720,
        mount: document.body,
        sizingMode: 'fit',
    },
    clearColor: Color.black,
    loader: {
        basePath: 'assets/',
    },
});

class ReverbAndDelayScene extends Scene {
    private sound!: Sound;
    private reverb!: ReverbEffect;
    private delay!: DelayEffect;
    private gfx!: Graphics;
    private prompt!: Text;
    private tapPrompt!: Text;
    private flash = 0;
    private triggers = 0;
    // Canvas-relative click-pad geometry computed in init().
    private pad = { x: 0, y: 0, w: 0, h: 0 };
    private hud!: ReturnType<typeof mountControls>;
    private panel!: ReturnType<typeof mountControlPanel>;

    override async load(loader): Promise<void> {
        await loader.load(Sound, { sfx: 'audio/impact-light.ogg' });
    }

    override init(loader): void {
        const { width, height } = this.app.canvas;

        // A large click pad centred on the canvas.
        this.pad = { x: width / 2 - 240, y: height * 0.36, w: 480, h: 160 };

        this.sound = loader.get(Sound, 'sfx');

        // Reverb (room tail) → Delay (echoes) chained on the sound bus.
        this.reverb = new ReverbEffect({ wet: 0.4, decay: 2 });
        this.delay = new DelayEffect({ wet: 0.35, delaySeconds: 0.25, feedback: 0.45 });
        app.audio.sound.addEffect(this.reverb);
        app.audio.sound.addEffect(this.delay);

        this.gfx = new Graphics();
        this.prompt = new Text('', { fillColor: Color.white, fontSize: 22, align: 'center' })
            .setAnchor(0.5, 0.5)
            .setPosition(width / 2, this.pad.y + this.pad.h / 2);

        // Shown while the browser still blocks audio (`app.audio.locked`); the
        // first click or keypress unlocks it.
        this.tapPrompt = new Text('Click or press any key to start audio', { fillColor: Color.white, fontSize: 22, align: 'center' })
            .setAnchor(0.5, 0.5)
            .setPosition(width / 2, height - 48);

        this.hud = mountControls({
            title: 'Reverb and Delay',
            controls: [{ keys: 'Click', action: 'trigger the impact sound' }],
            status: 'Click or press any key to start…',
            hint: 'Each click fires the dry impact through the reverb tail and delay echoes.',
        });

        // All four effect parameters are live: reverb wet + decay, delay wet,
        // delay time + feedback. Ranges mirror the filter clamps in src/audio/filters.
        this.panel = mountControlPanel({ title: 'Effect chain', corner: 'bottom-left' });
        this.panel.addSlider({
            label: 'Reverb wet',
            min: 0,
            max: 1,
            step: 0.01,
            value: this.reverb.wet,
            onChange: v => {
                this.reverb.wet = v;
            },
        });
        this.panel.addSlider({
            label: 'Reverb decay',
            min: 0.5,
            max: 10,
            step: 0.1,
            value: this.reverb.decay,
            onChange: v => {
                this.reverb.decay = v;
            },
        });
        this.panel.addSlider({
            label: 'Delay wet',
            min: 0,
            max: 1,
            step: 0.01,
            value: this.delay.wet,
            onChange: v => {
                this.delay.wet = v;
            },
        });
        this.panel.addSlider({
            label: 'Delay time (s)',
            min: 0.02,
            max: 0.82,
            step: 0.01,
            value: this.delay.delaySeconds,
            onChange: v => {
                this.delay.delaySeconds = v;
            },
        });
        this.panel.addSlider({
            label: 'Delay feedback',
            min: 0,
            max: 0.95,
            step: 0.01,
            value: this.delay.feedback,
            onChange: v => {
                this.delay.feedback = v;
            },
        });

        this.app.input.onPointerTap.add(() => {
            // The pointer gesture also unlocks the AudioContext; firing while
            // still locked would be silent, so wait until audio is ready.
            if (this.app.audio.locked) return;
            this.app.audio.play(this.sound);
            this.flash = 1;
            this.triggers += 1;
            this.hud.setStatus(`Impacts triggered: ${this.triggers}`);
        });

        this.hud.setStatus('Click anywhere to trigger the impact');
    }

    override update(delta): void {
        this.flash = Math.max(0, this.flash - delta.seconds * 2.2);
    }

    override draw(context): void {
        context.backend.clear();
        this.gfx.clear();

        // A big click pad that flashes on each trigger so the play action reads.
        const lit = Math.floor(60 + this.flash * 180);
        this.gfx.fillColor = new Color(lit, lit, Math.floor(60 + this.flash * 120));
        this.gfx.drawRectangle(this.pad.x, this.pad.y, this.pad.w, this.pad.h);

        this.prompt.text = this.app.audio.locked ? 'Click or press a key to enable audio' : 'Click to play impact';
        context.render(this.gfx);
        context.render(this.prompt);

        if (this.app.audio.locked) {
            context.render(this.tapPrompt);
        }
    }
}

app.start(new ReverbAndDelayScene());

Reverb and delay filters on the SFX bus, with live wet/dry and delay-time sliders.

Where to go next

The next chapter, Beat detection, covers tempo tracking and beat analysis — how to sync game logic to the rhythm of your music.