@audio/denoise 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +47 -29
  2. package/package.json +1 -2
package/README.md CHANGED
@@ -99,27 +99,37 @@ dehum(data, { freq: 50, adaptive: true, drift: 0.5 }) // tracks slow ma
99
99
  Adaptive high-pass. Cutoff slides between `cutoffMin` and `cutoffMax` based on the LF/MF energy ratio.
100
100
 
101
101
  ```js
102
- dewind(data, { cutoffMin: 60, cutoffMax: 200 })
102
+ dewind(data, { cutoffMin: 60, cutoffMax: 250 })
103
103
  ```
104
104
 
105
105
  | Param | Default | |
106
106
  |---|---|---|
107
107
  | `cutoffMin` | `60` | Hz — minimum cutoff (LF mostly clean) |
108
- | `cutoffMax` | `200` | Hz — maximum cutoff (heavy rumble) |
108
+ | `cutoffMax` | `250` | Hz — maximum cutoff (heavy rumble) |
109
+ | `order` | `2` | HP sections (each 12 dB/oct) |
109
110
  | `Q` | `0.707` | Butterworth-ish |
110
- | `block` | `512` | Coefficient update interval (samples) |
111
+ | `blockSize` | `1024` | Coefficient update interval (samples) |
111
112
 
112
- **Use when:** wind buffeting, handheld-mic rumble, low-frequency room modes.
113
+ **Use when:** intermittent wind buffeting, handling thumps, low-frequency room modes — the adaptive cutoff opens on gusts and closes between them (measured: beats `wiener` on gusty wind at ~1/10 the CPU).<br>
114
+ **Not for:** continuous rumble under speech — a time-domain cutoff can't separate overlapping spectra; use `wiener`/`omlsa` there (measured ~9 dB vs ~1 dB SNR gain). An LPC-null post-filter was evaluated and rejected: voiced speech is as AR-predictable as wind, so nulling wind poles whitens vowels too (LSD improves, SNR and speech level degrade).
113
115
 
114
116
 
115
117
  ### `deplosive`
116
118
 
117
- Splits the signal into LF (`<200 Hz`) and HF bands; ducks the LF band when it spikes relative to HF (a plosive signature).
119
+ Splits the signal into an LF band (`< crossover`) and its exact complement; ducks the LF band when its energy spikes above `triggerRatio`× the high band (a plosive signature). With no plosive present the output equals the input sample-for-sample — no crossover coloration.
118
120
 
119
121
  ```js
120
- deplosive(data, { ratio: 0.2, attack: 0.005, release: 0.05 })
122
+ deplosive(data, { triggerRatio: 4, attack: 0.005, release: 0.08 })
121
123
  ```
122
124
 
125
+ | Param | Default | |
126
+ |---|---|---|
127
+ | `triggerRatio` | `4` | LF/high energy ratio that opens the duck |
128
+ | `attenuation` | `-18` | dB cut on the LF band when triggered |
129
+ | `crossover` | `200` | Hz — LF/high split point |
130
+ | `attack` | `0.005` | s |
131
+ | `release` | `0.08` | s |
132
+
123
133
  **Use when:** mic plosives (`p`, `b`, `t`) producing low-frequency thuds.
124
134
 
125
135
 
@@ -136,9 +146,10 @@ deesser(data, { freq: 6500, threshold: -28, ratio: 4 })
136
146
  | `freq` | `6000` | Sibilance centre (Hz) |
137
147
  | `threshold` | `-30` | dBFS — engagement level |
138
148
  | `ratio` | `4` | Compression ratio above threshold |
139
- | `attack` | `0.001` | s |
140
- | `release` | `0.05` | s |
149
+ | `attack` | `0.001` | s — how fast the cut engages |
150
+ | `release` | `0.05` | s — how slowly it recovers |
141
151
  | `Q` | `1.4` | Peaking EQ Q |
152
+ | `block` | `64` | Coefficient update interval (samples) |
142
153
 
143
154
  **Use when:** voice post-production with hot s/sh; vocal bus de-essing.
144
155
 
@@ -147,12 +158,19 @@ deesser(data, { freq: 6500, threshold: -28, ratio: 4 })
147
158
 
148
159
  ### `specsub`
149
160
 
150
- Berouti spectral subtraction (1979). Estimates noise from the first `noiseFrames` and subtracts `α·N̂(k)` from each magnitude frame, with a `β·|Y(k)|` floor.
161
+ Berouti spectral subtraction (1979). Estimates noise from the first `noiseFrames` (or tracks it via Minimum Statistics) and subtracts `α(γ)·N̂(k)` — an SNR-adaptive over-subtraction factor — from each magnitude frame, with a `β·|Y(k)|²` spectral floor. Pass an explicit `alpha` to force a fixed factor.
151
162
 
152
163
  ```js
153
- specsub(data, { alpha: 2, beta: 0.01, noiseFrames: 6 })
164
+ specsub(data, { beta: 0.02, noiseFrames: 6 }) // adaptive α(γ)
165
+ specsub(data, { alpha: 2, beta: 0.02 }) // fixed over-subtraction
154
166
  ```
155
167
 
168
+ | Param | Default | |
169
+ |---|---|---|
170
+ | `alpha` | adaptive | Fixed over-subtraction factor; omit for Berouti α(γ) |
171
+ | `beta` | `0.02` | Spectral floor (fraction of the noisy spectrum) |
172
+ | `noiseFrames` | first 4 frames | Leading noise-only frames for the PSD bootstrap |
173
+
156
174
  **Use when:** quick baseline; offline cleanup with a known noise-only preamble.<br>
157
175
  **Not for:** musical-noise-sensitive material — use `wiener` or `omlsa`.
158
176
 
@@ -162,17 +180,17 @@ specsub(data, { alpha: 2, beta: 0.01, noiseFrames: 6 })
162
180
  MMSE Wiener / log-MMSE (Ephraim-Malah 1984/1985) with decision-directed a-priori SNR.
163
181
 
164
182
  ```js
165
- wiener(data, { rule: 'mmse-lsa', alpha: 0.98 })
166
- wiener(data) // defaults: 'wiener' rule
183
+ wiener(data, { rule: 'wiener' }) // pure Wiener gain
184
+ wiener(data) // defaults: 'mmse-lsa' rule
167
185
  ```
168
186
 
169
187
  | Param | Default | |
170
188
  |---|---|---|
171
- | `rule` | `'wiener'` | `'wiener'` or `'mmse-lsa'` (log-spectral, less musical noise) |
172
- | `alpha` | `0.98` | Decision-directed smoothing |
173
- | `frameSize` | `1024` | STFT frame |
189
+ | `rule` | `'mmse-lsa'` | `'wiener'` or `'mmse-lsa'` (log-spectral, less musical noise) |
190
+ | `alpha` | `0.98` | Decision-directed smoothing (alias of `alphaDD`) |
191
+ | `frameSize` | `2048` | STFT frame |
174
192
  | `hopSize` | `frameSize/4` | OLA hop |
175
- | `noiseFrames` | `6` | Initial noise-only frames for PSD bootstrap |
193
+ | `noiseFrames` | first 4 frames | Leading noise-only frames for PSD bootstrap |
176
194
 
177
195
  **Use when:** transparent broadband denoise; the "safe default" for stationary noise.
178
196
 
@@ -189,9 +207,9 @@ omlsa(data, { gMinDb: -25 }) // less aggressiv
189
207
 
190
208
  | Param | Default | |
191
209
  |---|---|---|
192
- | `gMinDb` | `-25` | dB floor for non-speech bins |
193
- | `alpha` | `0.92` | Decision-directed smoothing |
194
- | `frameSize` | `1024` | |
210
+ | `gMinDb` | `-20` | dB floor for non-speech bins (alias of `gMin`) |
211
+ | `alpha` | `0.92` | Decision-directed smoothing (alias of `alphaDD`) |
212
+ | `frameSize` | `2048` | |
195
213
  | `hopSize` | `frameSize/4` | |
196
214
 
197
215
  **Use when:** speech in non-stationary noise (street, café, car); generally the highest-quality choice for noisy speech.
@@ -204,15 +222,15 @@ omlsa(data, { gMinDb: -25 }) // less aggressiv
204
222
  Detects impulses as AR-residual outliers (`> threshold·σ`); replaces each click region with an AR-LS interpolation (Janssen 1986 / Godsill-Rayner 1998).
205
223
 
206
224
  ```js
207
- declick(data, { threshold: 4, order: 50 })
225
+ declick(data, { threshold: 4, order: 60 })
208
226
  ```
209
227
 
210
228
  | Param | Default | |
211
229
  |---|---|---|
212
230
  | `threshold` | `4` | σ-multiple for click detection |
213
- | `order` | `50` | AR model order |
214
- | `pad` | `2` | Extra samples on each side of the detected click |
215
- | `maxGap` | `order` | Maximum gap to interpolate (longer → skipped) |
231
+ | `order` | `60` | AR model order |
232
+ | `guard` | `2` | Extra samples on each side of the detected click |
233
+ | `maxBurst` | `64` | Longest run repaired (longer → left as a real transient) |
216
234
 
217
235
  **Use when:** vinyl pops, edit clicks, occasional impulse noise.<br>
218
236
  **Not for:** dense crackle (use `decrackle`); long dropouts (use `arInterpolate` directly).
@@ -223,7 +241,7 @@ declick(data, { threshold: 4, order: 50 })
223
241
  Continuous AR-residual outlier detection with MAD-based threshold. Suited to high-rate impulse noise.
224
242
 
225
243
  ```js
226
- decrackle(data, { madThreshold: 4 })
244
+ decrackle(data, { threshold: 3 })
227
245
  ```
228
246
 
229
247
  **Use when:** shellac / 78 RPM crackle; persistent low-amplitude clicks.
@@ -252,8 +270,7 @@ declip(data) // auto-detects c
252
270
 
253
271
  ### `dereverb`
254
272
 
255
- Late-reverb spectral subtraction (Lebart, Boucher & Denbigh 2001). Models the late tail as exponentially decaying noise:
256
- `|R̂(k)|² ≈ exp(-2·δ·t·hop) · |Y_prev(k)|²` and subtracts à la Berouti.
273
+ Late-reverb suppression (Lebart, Boucher & Denbigh 2001 estimate, Habets-class gain). Models the late tail as a decaying sum of past frames' power, then applies a decision-directed Wiener gain on the signal-to-reverb ratio — the cross-frame smoothing suppresses the musical noise hard subtraction produces.
257
274
 
258
275
  ```js
259
276
  dereverb(data, { t60: 0.6, predelay: 0.04 })
@@ -263,8 +280,9 @@ dereverb(data, { t60: 0.6, predelay: 0.04 })
263
280
  |---|---|---|
264
281
  | `t60` | `0.5` | Assumed reverberation time (s) |
265
282
  | `predelay` | `0.04` | Direct-sound passthrough (s) |
266
- | `alpha` | `1.5` | Over-subtraction factor |
267
- | `beta` | `0.05` | Spectral floor |
283
+ | `alpha` | `1.5` | Reverb-PSD over-estimation factor |
284
+ | `alphaDD` | `0.98` | Decision-directed SIR smoothing |
285
+ | `gMin` | `0.05` | Gain floor for reverb-dominated bins |
268
286
 
269
287
  **Use when:** moderate room reverb (RT60 ≤ 1 s) on a single channel.<br>
270
288
  **Not for:** heavy reverb or convolutive distortion — use multi-channel WPE (out of scope).
@@ -289,7 +307,7 @@ gate(data, { threshold: -45, attack: 0.005, release: 0.1, hold: 0.05, lookahead:
289
307
  VAD-driven inverse gate. Uses energy + spectral flatness with a percentile-based noise floor; attenuates frames classified as non-speech with smooth attack/release.
290
308
 
291
309
  ```js
292
- debreath(data, { reduction: 0.3 }) // -10 dB on non-speech
310
+ debreath(data, { range: -10 }) // -10 dB on non-speech (default -12)
293
311
  ```
294
312
 
295
313
  **Use when:** breath, mouth noise, hiss in pauses on a voiceover.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audio/denoise",
3
- "version": "0.3.2",
3
+ "version": "0.3.4",
4
4
  "type": "module",
5
5
  "description": "Noise reduction — gate, spectral subtraction, Wiener, OM-LSA, dehum, declick, decrackle, declip, deesser, dereverb",
6
6
  "sideEffects": false,
@@ -15,7 +15,6 @@
15
15
  "test": "node test.js",
16
16
  "test:all": "npm test --workspaces --if-present && npm test",
17
17
  "measure": "node scripts/measure.js",
18
- "compare": "node scripts/compare.js",
19
18
  "publish:all": "npm publish --workspaces && npm publish"
20
19
  },
21
20
  "repository": {