<p align="center"><img src="docs/banner.svg" alt="audioblur.js: a low-CPU multiband noise gate for voice" width="100%"></p>

<p align="center">
  <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-4da3ff"></a>
  <img alt="Zero dependencies" src="https://img.shields.io/badge/dependencies-0-4f8a5e">
  <img alt="No WebAssembly" src="https://img.shields.io/badge/WebAssembly-none-6c7f96">
  <img alt="About 9 KB gzipped" src="https://img.shields.io/badge/gzipped-~9%20KB-2f6fbd">
  <img alt="50 checks" src="https://img.shields.io/badge/checks-50%20pass-4f8a5e">
  <a href="https://dialersapps.pages.dev/lab/notes/audioblur.html"><img alt="Read the blog post" src="https://img.shields.io/badge/blog-field%20note-14202e"></a>
</p>

**audioblur.js** is a small, fast **multiband noise gate** for voice audio. It splits the signal into bands, tracks each
band's noise floor and speech level, and turns down everything that sits just above the floor, so the hiss, hum and room
noise **between the words** drop by 12 to 16 dB while the speech comes through at the same level. It runs on a whole clip
(`process`) or **live, chunk by chunk** (`createStream`), and ships an **AudioWorklet** wrapper (`createNode`). It is plain
JavaScript on `Float32Array`s: no WebAssembly, no model file, no dependencies, no allocation in the steady state.

> [!IMPORTANT]
> **audioblur is a gate, not a neural network.** It quiets noise in the gaps between words and in bands without speech.
> It **cannot remove noise that is under the speech itself** (a fan while you talk, keyboard clatter over a word); the way
> [RNNoise](https://jmvalin.ca/demo/rnnoise/) can. We position it as an **alternative to RNNoise for when a small, cheap
> gate is enough**, and **not as a replacement for it**. See [Gate or RNNoise?](#gate-or-rnnoise) and [Known limits](#known-limits).

**Try it live:** [demo](https://dialersapps.github.io/audioblur/demo.html) (your audio or a generated test recording, offline or through a real AudioWorklet) &middot; [tests](https://dialersapps.github.io/audioblur/test.html) (50 checks, run in your browser)

**Contents:** [Quick start](#quick-start) &middot; [Gate or RNNoise?](#gate-or-rnnoise) &middot; [Options](#options) &middot; [API](#api) &middot; [How it works](#how-it-works) &middot; [In pictures](#what-it-does-in-pictures) &middot; [Numbers](#numbers-what-we-measured) &middot; [Tests](#tests) &middot; [Known limits](#known-limits) &middot; [Licence](#licence)

## Quick start

```html
<script src="audioblur.js"></script>            <!-- or: import * as audioblur from "./audioblur.mjs" -->
```

**A whole clip** (offline; takes the clip's own noise floor and speech level into account):

```js
const cleaned = audioblur.process(float32Samples, sampleRate, { reduction: 16 });   // a new Float32Array
```

**Live, in an AudioWorklet** (the stream runs inside the node; a running tracker replaces the clip statistics):

```js
const ctx = new AudioContext();
const gate = await audioblur.createNode(ctx, { reduction: 16, release: 50 });       // needs https or localhost
micSource.connect(gate).connect(ctx.destination);
gate.set({ reduction: 24 });                                                         // change options while it runs
gate.onstate = (s) => console.log(s.bands.map((b) => b.gainDb));                     // optional: floor, speech, gain per band
console.log(gate.latencySamples, 'samples of delay');                                // 17 ms by default
```

**Live, in your own loop** (any environment: a Worker, Node, a native bridge):

```js
const stream = audioblur.createStream(48000, { reduction: 16 });
const out = new Float32Array(128);
function onAudioBlock(input /* Float32Array, any length */) { stream.process(input, out); /* out is delayed by stream.latencySamples */ }
```

Offline and streaming take the same options. Every option is checked, and an unknown name (a typo) throws.

## Gate or RNNoise?

RNNoise is a hybrid of classic DSP and a small recurrent neural network, trained on speech; it estimates a gain per band
every 10 ms and **does clean noise that sits under the voice** ([Mozilla's write-up](https://hacks.mozilla.org/2017/09/rnnoise-deep-learning-noise-suppression/)).
audioblur does less, much more cheaply. The numbers marked "measured" come from [`tools/measure.mjs`](tools/measure.mjs)
([results.json](docs/results.json)); the rest are properties of the two designs.

| | audioblur.js | RNNoise (as WebAssembly) |
|---|---|---|
| What it is | multiband downward expander: a gate with a tracker | neural-network noise suppressor |
| Noise **under** speech | **not reduced** (gate is open while you talk) | reduced |
| Noise in the **gaps** | reduced by up to `reduction` dB (default 16) | reduced |
| CPU, 48 kHz, one thread | **measured: 6.5 ms per second of audio** (0.65% of one core; 3.8 to 7.7 across runs) | **measured: about 80 ms per second** (58 to 81 across runs; `@jitsi/rnnoise-wasm` 0.2.1, `-Os` build, no SIMD). About **15x** more than audioblur in the same runs |
| CPU, 16 kHz | measured: 1.9 ms per second | needs 48 kHz input, so you resample first |
| Sample rates | 3 to 384 kHz accepted (tested 8 to 96 kHz) | 48 kHz only |
| Delay | 17 ms by default; `lookahead: 0` gives 5 ms | 10 ms (one 480-sample frame) |
| Memory | 22 KiB (16 kHz) to 39 KiB (48 kHz) per mono stream, measured | model weights plus a WASM heap |
| Setup | one 29 KB file (9 KB gzipped), no wasm, no model | wasm binary plus glue code |
| Tuning | `reduction`, `release`, `attack`, `sensitivity`, ... | none, apart from what you build around it |
| Strengths | cheap enough for many streams or a weak phone; predictable; tunable | handles steady and changing noise under speech |

**Use audioblur** when the noise is mostly hiss, hum and room tone in the pauses (voice messages, push-to-talk, intercoms,
call recordings), when CPU or battery is tight, when you mix many streams on a server, or when you want a knob that does what
it says. **Use RNNoise** when the noise is there while people talk. They are not exclusive; a gate after a suppressor is a
plausible chain, but we have not measured that.

## Options

`reduction` is the main knob. All options are optional.

| Option | Default | Range | What it does |
|---|---|---|---|
| `reduction` | `16` | 0 to 60 dB | The **deepest cut** applied to anything below the threshold. What you actually get is `min(reduction x depth, (threshold - level) x (ratio - 1))`, see `adaptiveDepth`. |
| `release` | `50` | 1 to 5000 ms | How slowly the gain closes after speech. Longer is smoother, shorter is tighter. |
| `attack` | `6` | 0.5 to 1000 ms | How fast the gain opens when speech starts. Keep it below 12 ms; long attacks clip word starts. |
| `sensitivity` | `10` | 0 to 40 dB | Where the gate starts to close: `threshold = floor + max(sensitivity, 0.25 x gap)`, never above `floor + 0.5 x gap`. **Higher = stronger gating** (and a higher risk of eating soft speech). |
| `ratio` | `4` | 1 to 20 | Expansion ratio below the threshold: 4 means every dB under the threshold becomes 4 dB. |
| `lookahead` | `12` | 0 to 100 ms | How far ahead of the audio the detector looks, so word starts are not clipped. Stream delay = `lookahead` + one hop. |
| `crossovers` | `[500, 3000]` | up to 6 values | Band edges in Hz: N crossovers make N+1 bands. At least 1.5x apart, 20 Hz to 45% of the sample rate. `bands` is accepted as an alias. More bands cost more CPU, see [Numbers](#numbers-what-we-measured). |
| `adaptiveDepth` | `true` | | Eases the cut when speech and noise are close. The best band's speech-over-noise gap sets the depth: 42 dB or more gives the full `reduction`, 22 dB or less gives `minDepth` of it. Set `false` to always cut the full amount. |
| `minDepth` | `0.3` | 0 to 1 | The floor of `adaptiveDepth`, as a fraction of `reduction`. |
| `bypass` | `false` | | Offline: returns an exact copy. Stream: a 5 ms crossfade to the delayed input. |

<details><summary><b><code>advanced</code> options</b> (pass as <code>{ advanced: { ... } }</code>; the defaults are tuned, you should not need these)</summary>

| Option | Default | What it does |
|---|---|---|
| `hopMs`, `winMs` | 5, 20 | One gain value every `hopMs`, measured over a window of `winMs`. |
| `floorPct`, `speechPct` | 0.1, 0.95 | The noise floor is the 10th percentile of a band's levels, the speech level the 95th. |
| `marginFrac`, `maxMarginFrac` | 0.25, 0.5 | Threshold placement (see `sensitivity`). |
| `headroomDb` | 0 | If above 0, the threshold is never closer than this to the speech level. |
| `minSepDb` | 9 | A band whose speech-over-floor gap is smaller than this is not gated on its own; it follows the nearest band below that has one. |
| `depthSepLo`, `depthSepHi` | 22, 42 | The gap range of `adaptiveDepth`. |
| `minSec` | 0.6 | A clip shorter than this is returned untouched; a stream stays open this long while it warms up. |
| `trackSec` | 20 | **Stream only.** Forgetting time constant of the running level statistics. |
| `holdSec` | 20 | **Stream only.** How long the last good floor and speech estimate is kept when the gap disappears (a long silence). |
| `allpassComp` | `true` | Allpass-compensates the lower bands so the bands sum to **exactly flat** magnitude. `false` is the plain cascade, which rings up to 0.28 dB around the lower crossover. |

</details>

## API

| Call | Returns | Notes |
|---|---|---|
| `audioblur.process(samples, sampleRate, options?)` | new `Float32Array` | Whole clip, mono. The input is not modified. A clip shorter than `advanced.minSec` is returned as a copy. Accepts a `Float32Array` or an array of numbers. |
| `audioblur.analyze(samples, sampleRate, options?)` | `{ output, active, depth, hopMs, bands: [{ active, floorDb, refDb, thresholdDb, gainDb }] }` | Same processing as `process`, plus the per-band floor, speech level, threshold and gain curve (dB per hop). Used by the demo and the figures. |
| `audioblur.createStream(sampleRate, options?)` | stream | Live, mono. See below. |
| `audioblur.createNode(audioContext, options?)` | `Promise<AudioWorkletNode>` | One stream per channel inside an AudioWorklet. Extra options: `channels` (default 2), `statePeriodMs` (default 0 = off). The node has `set(options)`, `reset()`, `onstate`, `onerror`, `latencySamples`, `latencySeconds`. Needs a secure context (https or localhost). The worklet code is generated from the library itself (`audioblur.workletSource`), so there is no second file to host. |
| `audioblur.split(samples, sampleRate, crossovers?)` | array of `Float32Array` | Just the allpass-compensated Linkwitz-Riley band split. The bands sum back to the input's magnitude. |
| `audioblur.latency(sampleRate, options?)` | samples | The delay a stream with these options adds. |
| `audioblur.defaults()` | object | A copy of every default, `advanced` included. |
| `audioblur.version`, `audioblur.workletSource` | | |

A **stream** has:

| Member | |
|---|---|
| `process(input, output?)` | Any chunk length. Writes `input.length` samples to `output` (allocated if you omit it; pass your own to stay allocation-free; `output === input` is fine) and returns it. The output is the input delayed by `latencySamples`; the first `latencySamples` samples are zeros. Non-finite samples are treated as 0. Chunk size does not change the output: 1, 7, 128 or 4096 samples per call give identical samples. |
| `flush()` | The last `latencySamples` samples still in the delay line (feeds zeros through). |
| `reset()` | Back to the fresh state (filters, tracker, delay line). Options are kept. |
| `setOptions(partial)` | Change `reduction`, `release`, `attack`, `sensitivity`, `ratio`, `adaptiveDepth`, `minDepth`, `bypass` and the `advanced` thresholds while it runs. `lookahead`, `crossovers`, `hopMs`, `winMs` and `allpassComp` need a new stream and throw here. |
| `getState()` | `{ ready, depth, latencySamples, bands: [{ active, floorDb, refDb, levelDb, gainDb }] }` for meters. |
| `latencySamples`, `sampleRate`, `bands`, `options` | |

**Stereo and multichannel:** a stream is mono. `createNode` runs one independent stream per channel. Independent detection
can shift a stereo image when one side is noisier; if that matters, gate a mono sum and apply the same gain yourself
(`getState().bands[i].gainDb`), or process the mid channel only. We have not built linked detection.

## How it works

<p align="center"><img src="docs/signal-flow.svg" alt="Signal flow: bands, level, tracker, gain, smoothing, apply, sum" width="100%"></p>

1. **Split** into bands with Linkwitz-Riley 4th-order crossovers (two cascaded Butterworth biquads per side, 500 Hz and 3 kHz by default). The lower bands pass through the allpass of each crossover above them, so the bands sum back to exactly the input's magnitude. The test suite checks each band against the analytic response.
2. **Level** per band: mean power over 20 ms windows, one value every 5 ms.
3. **Tracker**: the band's **noise floor** (10th percentile of its levels) and **speech level** (95th percentile). Offline these are exact percentiles of the whole clip. In a stream they are weighted percentiles from a 96-bin level histogram with exponential forgetting (20 s), so it follows a changing noise floor with no buffer of past audio and no sorting. A band with no clear gap between the two (typically the top band, where only sibilants reach) follows the nearest band below that has one.
4. **Gain**: `threshold = floor + max(sensitivity, 0.25 x gap)`. Below it, the band is turned down by `(threshold - level) x (ratio - 1)` dB, never more than `reduction x depth`.
5. **Adaptive depth** scales the cap with the best band's speech-over-noise gap, so a noisy clip or a quiet talker, where soft speech sits at the noise level, is not eaten.
6. **Smooth** with a fast attack (6 ms) and a slow release (50 ms), then **apply** to the band delayed by the lookahead, so the gain is open before the first sample of a word gets there.
7. **Sum** the bands.

<p align="center"><img src="docs/lookahead.svg" alt="The low-band gain opens within about 20 ms of an abrupt word start; the first sample leaves the delay 17 ms after it arrived" width="100%"></p>

**Offline vs streaming.** Offline looks at the whole clip: exact percentiles of the clip and a look-ahead window. The stream is causal: the same options, running estimates, and a delay line of `lookahead` plus one hop. On our test recording they agree on the gap attenuation within 0.1 dB and on speech level within 0.01 dB once the tracker has warmed up. The stream spends its first 0.6 s warming up (the gate is open), and a long silence makes it hold the last good estimate for `holdSec` and then let go, because a constant level cannot be told from noise.

**Robustness.** Non-finite samples are replaced with 0 (one NaN would otherwise poison the filters for good). The filter state is flushed to zero once it decays below 1e-30, because a tail that decays into subnormal numbers makes every later multiply about 20x slower (we found this one in the measurements: 72 ms per second after speech followed by digital silence, 5.6 ms after the fix; a check in the test suite guards it).

## What it does, in pictures

<p align="center"><img src="docs/before-after.svg" alt="Level of a noisy recording before and after, and the gain in each band" width="100%"></p>

On the seeded test recording (synthetic voice plus hiss, rumble and mains hum, 30 dB SNR) the default settings take the gaps down by **12.3 dB** and change the speech level by **0.00 dB**. With `adaptiveDepth: false` the cut is the full **16.0 dB**. The gain curves show what a gate does inside speech too: it closes briefly in the deep syllable dips of this synthetic voice and opens again.

<p align="center"><img src="docs/spectrograms.svg" alt="Spectrograms before and after" width="100%"></p>

<p align="center"><img src="docs/knobs.svg" alt="The main options measured" width="100%"></p>

`reduction` is a ceiling; the achieved cut flattens near 26 dB here because with `ratio: 4` and a threshold about 9 dB above the floor the gate cannot cut deeper (with `ratio: 8` the full 40 dB is reached on this recording). `release` is the time the gain takes to close 63% of the way. A long `attack` clips word starts. `sensitivity` raises the threshold, which matters on a noisy recording and does nothing once it passes the gap-based cap.

<p align="center"><img src="docs/adaptive-depth.svg" alt="Gap attenuation against signal to noise ratio, with and without adaptive depth" width="100%"></p>

<p align="center"><img src="docs/tracker.svg" alt="The running tracker following a noise floor that drops and rises" width="100%"></p>

In the stream the floor estimate follows a 12 dB **drop** in noise in about 3 s and a 10 dB **rise** in about 26 s (time to cover 90% of the step; default 20 s memory), because the old, lower floor has to age out of the histogram first. A rise that is slow to track is the safe direction: until the estimate catches up the threshold sits low and the gate stays open.

## Numbers: what we measured

Everything here is from [`tools/measure.mjs`](tools/measure.mjs) and [`tests/`](tests) on **synthetic seeded signals**, on one machine: an
**Intel i7-4790 (2014, 3.6 GHz), Node 24**, single thread. That machine also runs other heavy work, so timings vary by about 2x
from run to run; the headline numbers are the best of 9 to 15 runs and [results.json](docs/results.json) has the medians. **It is a desktop CPU, not a phone, and we did not measure energy
use or battery**: CPU time per second of audio is our proxy.

<p align="center"><img src="docs/cpu.svg" alt="CPU time per second of audio: audioblur versus RNNoise WebAssembly" width="100%"></p>

| | 16 kHz | 48 kHz |
|---|---|---|
| Stream, 3 bands, 128-sample blocks | **1.9 ms per second of audio** (0.19% of one core, 527x real time) | **6.5 ms per second** (0.65%, 155x). Three separate runs: 3.8 to 7.7 ms |
| `process()` on a 60 s clip | 3.3 ms per second | 9.4 ms per second |
| Per hour of audio | about 7 CPU-seconds | about 23 CPU-seconds |
| Memory per stream | 22 KiB | 39 KiB |

- **Cost scales with the band count** (stream, 48 kHz): 1 band 1.2, 2 bands 3.1, **3 bands 6.3**, 5 bands 10.5, 7 bands 16.4 ms per second.
- **Allocation-free steady state:** with a caller-supplied output buffer, the heap did not grow (-3.7 KiB, 0 KiB of array buffers) over 20,000 blocks of 128 samples.
- **Digital silence** costs no more than speech (5.5 ms per second for silence and 5.6 for speech followed by silence, against 6.5 for speech, at 48 kHz). Block size matters a little: in one run 128-sample blocks (the AudioWorklet size) took 7.7 ms per second, 4096-sample blocks 5.2 and one-sample calls 11.9.
- **Latency:** 17 ms by default (12 ms lookahead + one 5 ms hop), 5 ms with `lookahead: 0`.
- **Against RNNoise, same machine, same input, interleaved runs** (`@jitsi/rnnoise-wasm` 0.2.1: the rnnoise 0.2 model, emscripten `-Os`, no SIMD; one 480-sample frame at a time, float copies included): RNNoise **81 ms per second** (8.1% of one core, 12x real time), audioblur **5.1 ms** in the same run. About **15x** (14 to 16x in three runs). A SIMD or native build of RNNoise would be faster than this one; we did not measure one. To reproduce: `npm i @jitsi/rnnoise-wasm` next to the repo, then `npm run measure`.
- **Quality on the test recording** (not on real speech): gaps **-12.3 dB** (default) or **-16.0 dB** (`adaptiveDepth: false`) on the 30 dB SNR scene, **-16.0 dB** on a 48 dB scene; speech level **0.00 dB**; worst loss in the first 30 ms of any word **-0.33 dB** offline and **-0.51 dB** in the stream; gap attenuation and speech level agree between offline and stream; works from 8 kHz to 96 kHz.

**What we did not measure:** real speech or any listening test; noise types other than hiss, rumble and hum; energy use; phones or other browsers' JavaScript engines; and **noise-suppression quality against RNNoise**. RNNoise is trained on real speech, and our signals are synthetic, so comparing quality on them would tell you nothing about either library. Only the CPU comparison above is like for like.

## Tests

`node tests/run.mjs` (Node 18+) or open [`test.html`](test.html): **49 checks in Node and 50 in the browser** (the extra one compares the ES module build with the script build), all passing in Node 24 and in Chromium.

- the options (defaults, ranges, typos throw, bad crossovers and sample rates throw);
- the band split against the **analytic Linkwitz-Riley response** (the `tan()` pre-warp formula, which is independent of the biquad code): every band within 0.0008 dB over 35 points, the crossover point at -6.02 dB, the bands summing to unity within 0.0000 dB;
- offline: gap attenuation equals `reduction` (6, 12, 24 dB set, 6.0, 12.0, 23.5 dB measured), the adaptive depth, release time, word onsets, bypass bit-exact, odd input;
- stream: the delay, **identical output for chunk sizes 1, 7, 64, 128, 480 and 4096**, in-place use, `reset()`, live `setOptions()`, the bypass crossfade, NaN and Infinity input, a long pause (held), a very long pause (lets go, recovers within 10 s), a noise floor that drops and rises;
- the **running tracker against the exact clip percentiles** (an independent computation of the same statistics): within 1.5 dB in every band;
- the **AudioWorklet processor**, run against a stub of the worklet scope: it registers `audioblur` and matches `createStream` sample for sample, per channel, including a live `set()`;
- the filter-tail check (silence after speech is not slower than speech);
- eight sample rates from 8 to 96 kHz.

**Port check.** The gate was built for a push-to-talk web app. The offline path was ported from that code and, with `allpassComp: false`, reproduces its output **bit for bit** (largest sample difference 0 in ten comparisons: five synthetic clips from 8 to 48 kHz at two reduction settings). That check needs the original source, which is not in this repository.

## Known limits

- **It is a gate.** It does not touch noise that sits under speech, and it will not fix a recording where the noise is as loud as the voice. With a poor signal-to-noise ratio the adaptive depth deliberately cuts less (about 5 dB at 12 dB SNR in our test).
- **It needs a contrast between speech and pauses.** A constant level, whether noise or music, cannot be told from noise. After minutes of nothing but steady noise the stream lets go and passes it (it had recovered by 10 s after speech returned in our test). Music is treated as speech and passes.
- **Gaps only:** a click or knock in a pause that is louder than the threshold passes through.
- **Mono streams.** Multichannel means independent streams per channel; see the API section.
- **Warm-up:** the first 0.6 s of a stream is not gated, and a clip shorter than 0.6 s is returned untouched.
- **Delay:** a stream adds `lookahead` plus one hop (17 ms by default) and its first samples are zeros.
- **Tested** in Node 24 and Chromium. Not tested in Firefox or Safari, in a mobile WebView, or on a phone. `createNode` needs AudioWorklet and a secure context.
- **Synthetic evidence only.** The numbers above are real measurements of a deterministic test signal; they are not a claim about how it sounds on your recordings. Try the [demo](https://dialersapps.github.io/audioblur/demo.html) on yours.

**Prior art.** In October 2026 we searched npm, GitHub and the web for a small, dependency-free JavaScript multiband gate or expander with a streaming AudioWorklet mode and **did not find one**; the closest was a single-band Web Audio preset on npm (`noise-gate`). That is a search, not proof; if you know of one, please open an issue.

## Licence

MIT, (c) 2026 Dialer's Apps. See [LICENSE](LICENSE).
