@maruaudio/dsp/analysis/loudness-match measures a dry reference pair and an uncompensated candidate pair over one rolling window and returns a stereo-linked gain that brings the candidate to the reference. Each path sums L² + R², K- weighted or not, into 10 ms buckets in fixed 300-bucket rings. The first complete valid window sets targetDb = referenceDb − candidateDb; learn mode holds it, continuous mode keeps updating. The correction slews by d += (1 − e^(−1/(fs·t)))(target − d) and the gain is 10^(d/20).
Parameters
configureLoudnessMatch(state, mode, metric, windowSeconds, updateSeconds, smoothSeconds, minimumSignalDb, minimumCorrectionDb, maximumCorrectionDb, deadbandDb, ceilingDb); non-finite values take the default.
| Argument | Range as coded | Default | Unit |
|---|---|---|---|
mode | 0 off, 1 learn then hold, 2 continuous | 0 | index |
metric | 0 K, 1 unweighted stereo power | 0 | index |
windowSeconds, updateSeconds | 0.1 to 3, 0.01 to 1, in 10 ms buckets | 1, 0.1 | s |
smoothSeconds | 0.01 to 5 | 0.2 | s |
minimumSignalDb | −100 to −20, per path | −60 | dB |
minimumCorrectionDb, maximumCorrectionDb | −48 to 0, 0 to +48 | −24, +24 | dB |
deadbandDb, ceilingDb | 0 to 6 (vs. the previous target); −24 to +12 (caps boost by the candidate's sample peak) | 0.2, −1 | dB, dBFS |
configureLoudnessMatchCapture(state, seconds) (0, or 0.1 to 30) pools eligible paired energy instead; configureLoudnessMatchSampleGuard(state, enabled, releaseSeconds) (off, 0.005 to 1.5 s, 0.05 s) caps the gain per frame.
Lifecycle
initLoudnessMatch(sampleRate) (8 to 384 kHz) in create → configure outside the sample loop → per frame loudnessMatchTick(state, refL, refR, candL, candR), multiplying both candidate channels by the returned gain before any manual output control. requestLoudnessMatch relearns, invalidateLoudnessMatch marks a held match stale, resetLoudnessMatch also clears the gain, and prepareLoudnessMatchSampleRate re-derives rate values and clears measurement.
When to use it
Comparing an insert effect against its bypass at matched loudness, so the choice is not biased by level. Loudmatch and Guitarabin use it (integrating another insert effect).
Limits
- Stereo tick, linked gain. Not integrated LUFS or a true-peak ceiling: ceiling and guard use sample peaks. Silence, tails and invalid windows cannot learn.