Building a 10-band equalizer with the Web Audio API
The audio chain behind Melodius's equalizer: shelves, ten peaking filters, a stereo-width matrix, a leveler, loudness normalisation and a limiter, all changed with click-free parameter ramps.
Melodius has a real equalizer on the web and desktop, not a set of presets that swap files. It is built from standard Web Audio nodes. Here is the chain, why each stage exists, and the detail that matters most: changing the sound while music plays without a click.
The chain
decks -> preamp -> bass shelf -> 10 peaking bands -> treble shelf
-> stereo width -> balance -> leveler -> normaliser -> limiter -> speakersEvery node stays connected all the time. Turning the equalizer off does not rewire anything; it sets each stage to unity, so the chain becomes transparent.
Ten bands and two shelves
The bands sit at 32, 64, 125, 250, 500 Hz and 1, 2, 4, 8, 16 kHz, roughly an octave apart, each a BiquadFilterNode of type peaking with Q 1.4, about one octave wide. Gains run from −12 to +12 dB. A low shelf at 100 Hz and a high shelf at 8 kHz give simple bass and treble controls on top.
The preamp, from −12 to +6 dB, comes first for a reason: boosting several bands can push the signal past full scale and clip. Lowering the preamp leaves headroom. It also turns a mono source into stereo, so the next stage always has two channels.
Stereo width as a 2x2 matrix
Width is a mix of the left and right channels, built from a splitter, four gains and a merger:
L' = a·L + b·R
R' = b·L + a·R with a = (1 + w) / 2, b = (1 − w) / 2At w = 1 the sound is untouched. At w = 0 both channels become the average, which is mono. Above 1, b goes negative and subtracts a little of the other channel, widening the image. A StereoPannerNode handles balance afterwards.
Leveler, normaliser, limiter
- Leveler: an optional compressor (threshold −24 dB, ratio 3, soft knee) that evens out loud and quiet parts. Off means ratio 1, which passes everything through.
- Normaliser: a slow gain that brings each song towards about −16 dB, as streaming apps do, boosting at most 6 dB and cutting at most 9 dB, and ignoring near-silence so quiet intros are not pumped up.
- Limiter: a fast, hard compressor at −1 dB as the last stage, so no combination of settings can clip the output.
Changing sound without clicks
Setting gain.value directly jumps the parameter between two samples, which you hear as a click or a zipper noise while dragging a slider. Every change is a short ramp instead:
const RAMP_SECONDS = 0.04;
private ramp(param: AudioParam, value: number) {
const now = this.ctx.currentTime;
param.cancelScheduledValues(now); // drop a ramp still in flight
param.setValueAtTime(param.value, now);
param.setTargetAtTime(value, now, RAMP_SECONDS);
}One settings model for every app
The settings shape, the presets and the limits live in the shared core package, and anything read from storage or another device goes through a sanitiser first: out-of-range gains are clamped, unknown presets fall back, malformed bands are dropped. A preset saved on a phone sounds the same on the desktop, which I wrote about in shipping one app to four platforms.
