@audio/denoise-core 0.1.0

package/ar.js

@@ -0,0 +1,131 @@
+// Auto-regressive modelling for click/click-burst interpolation and de-clip extrapolation.
+//   - Levinson-Durbin recursion → AR(p) coefficients from autocorrelation
+//   - LS interpolation of missing samples from neighbouring AR predictions
+//   - Forward AR extrapolation (used by de-clip)
+//
+// Reference: Godsill & Rayner (1998), "Digital Audio Restoration", §5.
+
+// Biased autocorrelation R[0..p]. Bias is preferable for short windows (Toeplitz PSD).
+export function autocorr(x, p) {
+  let n = x.length, R = new Float64Array(p + 1)
+  for (let k = 0; k <= p; k++) {
+    let s = 0
+    for (let i = 0; i + k < n; i++) s += x[i] * x[i + k]
+    R[k] = s
+  }
+  return R
+}
+
+// Levinson-Durbin: solve Toeplitz Yule-Walker for AR(p) coefficients.
+// Returns { a: Float64Array(p+1), e: residual variance }.  a[0] = 1 by convention.
+export function levinson(R, p) {
+  let a = new Float64Array(p + 1)
+  let prev = new Float64Array(p + 1)
+  a[0] = 1
+  let e = R[0]
+  if (e <= 0) return { a, e: 0 }
+
+  for (let i = 1; i <= p; i++) {
+    let k = -R[i]
+    for (let j = 1; j < i; j++) k -= a[j] * R[i - j]
+    k /= e
+    for (let j = 0; j <= i; j++) prev[j] = a[j]
+    a[i] = k
+    for (let j = 1; j < i; j++) a[j] = prev[j] + k * prev[i - j]
+    e *= 1 - k * k
+    if (e <= 0) { e = 0; break }
+  }
+  return { a, e }
+}
+
+// Convenience: AR fit on a window.
+export function arFit(x, p) {
+  return levinson(autocorr(x, p), p)
+}
+
+// Predict next sample via AR(p): x̂[n] = -∑ a[k]·x[n-k], k=1..p.
+export function arPredict(a, hist) {
+  let p = a.length - 1, s = 0
+  for (let k = 1; k <= p; k++) s -= a[k] * hist[hist.length - k]
+  return s
+}
+
+// Forward AR extrapolation by m samples beyond context tail.
+// Used for de-clip: fit AR on un-clipped neighbourhood, project into clipped region.
+export function arExtrapolate(context, a, m) {
+  let p = a.length - 1
+  let buf = new Float64Array(p + m)
+  for (let i = 0; i < p; i++) buf[i] = context[context.length - p + i]
+  for (let i = 0; i < m; i++) {
+    let s = 0
+    for (let k = 1; k <= p; k++) s -= a[k] * buf[p + i - k]
+    buf[p + i] = s
+  }
+  return buf.subarray(p)
+}
+
+// Least-squares interpolation of indices `gap` (sorted ints) inside x using AR(p).
+// Solves Bᵀ B  · u = -Bᵀ A · k, where u = unknowns, k = knowns,
+// (B,A) split of the AR convolution matrix on (gap, ¬gap).
+//
+// Direct sparse Gauss-Seidel is enough for clusters up to ~50 samples; very small
+// gaps (≤8) reduce to a few iterations and are dominated by the AR fit cost itself.
+export function arInterpolate(x, gap, a) {
+  let p = a.length - 1
+  let n = x.length, m = gap.length
+  if (m === 0) return x
+
+  let inGap = new Uint8Array(n)
+  for (let i = 0; i < m; i++) inGap[gap[i]] = 1
+
+  // M = sum over t of (sum_{k:t-k∈gap} a[k] * a[k - (t - gap_j)]) — assemble m×m system implicitly.
+  // For practicality, use Jacobi iteration: x_g = -∑_{j≠g} M[g,j]/M[g,g] · x_j  + b/M[g,g]
+  // with M[g,g] = ∑_k a[k]² for k where g+k≤n+p
+  // and forcing term computed from neighbours.
+  let mdiag = new Float64Array(m)
+  for (let i = 0; i < m; i++) {
+    let g = gap[i], s = 0
+    for (let k = 0; k <= p; k++) {
+      let t = g + k
+      if (t >= 0 && t < n + p) s += a[k] * a[k]
+    }
+    mdiag[i] = s || 1
+  }
+
+  // initial: linear interpolation between gap boundaries
+  for (let i = 0; i < m; i++) {
+    let g = gap[i]
+    let lo = g, hi = g
+    while (lo > 0 && inGap[lo - 1]) lo--
+    while (hi < n - 1 && inGap[hi + 1]) hi++
+    let xLo = lo > 0 ? x[lo - 1] : 0
+    let xHi = hi < n - 1 ? x[hi + 1] : 0
+    x[g] = xLo + (xHi - xLo) * (g - lo + 1) / (hi - lo + 2)
+  }
+
+  // 30 Gauss-Seidel sweeps converge well past audible accuracy for short gaps
+  let iter = 30
+  for (let it = 0; it < iter; it++) {
+    for (let i = 0; i < m; i++) {
+      let g = gap[i]
+      // residual r[t] = ∑_k a[k] x[t-k] for t = g..g+p; gradient wrt x[g] is
+      // ∑_k a[k] r[g+k]; setting it to zero gives the update.
+      let num = 0
+      for (let k = 0; k <= p; k++) {
+        let t = g + k
+        if (t < 0 || t >= n + p) continue
+        let rt = 0
+        for (let j = 0; j <= p; j++) {
+          let idx = t - j
+          if (idx < 0 || idx >= n) continue
+          rt += a[j] * x[idx]
+        }
+        // remove self-contribution so we can solve for x[g]
+        rt -= a[k] * x[g]
+        num -= a[k] * rt
+      }
+      x[g] = num / mdiag[i]
+    }
+  }
+  return x
+}

package/index.js

@@ -0,0 +1,6 @@
+export * from './stft.js'
+export * from './util.js'
+export * from './noise.js'
+export * from './vad.js'
+export * from './ar.js'
+export * from './quality.js'

package/noise.js

@@ -0,0 +1,119 @@
+// Noise PSD estimators feeding the statistical denoisers (Wiener, OM-LSA, MMSE).
+//   - profile: average |X|² over a user-chosen quiet segment (manual baseline)
+//   - minimumStatistics: Martin (2001) — track minima of smoothed |X|² in sliding window
+//   - imcra: Cohen (2003) — Improved MCRA, two-iteration smoothing + speech-presence-driven
+//
+// All estimators are stateful: pass the same params object across frames in stream mode.
+
+import { stftAnalyse } from './stft.js'
+
+// One-shot batch profile from a quiet segment of `data`. Returns Float64Array(N/2+1).
+export function noiseProfile(data, opts = {}) {
+  let N = opts.frameSize || 2048
+  let hop = opts.hopSize || (N >> 2)
+  let half = N >> 1
+  let from = Math.max(0, opts.from ?? 0)
+  let to = Math.min(data.length, opts.to ?? Math.min(data.length, from + N * 8))
+  let seg = data.subarray(from, to)
+  let psd = new Float64Array(half + 1)
+  let count = 0
+  stftAnalyse(seg, mag => {
+    for (let k = 0; k <= half; k++) psd[k] += mag[k] * mag[k]
+    count++
+  }, { frameSize: N, hopSize: hop })
+  let scale = count ? 1 / count : 0
+  for (let k = 0; k <= half; k++) psd[k] *= scale
+  return psd
+}
+
+// Minimum Statistics (Martin 2001) — frame-by-frame online updater.
+// Keeps a rolling D-frame minimum of smoothed PSD per bin; multiplies by a bias
+// compensation factor so the minimum tracks E{|N|²} rather than the lower-tail.
+//
+// Usage:
+//   let est = minStats(half, { D: 96 })
+//   stftAnalyse(data, m => est.update(m))
+//   let psd = est.psd  // current noise PSD
+//
+// D ≈ 1.5 s of frames at hop = N/4 ≈ 96 frames @ 44.1k / N=2048.
+export function minStats(half, opts = {}) {
+  let D = opts.D || 96
+  let alpha = opts.alpha ?? 0.7              // smoothing on PSD
+  let bias = opts.bias ?? 1.5                 // empirical comp from Martin §VII
+  let smoothed = new Float64Array(half + 1)
+  let psd = new Float64Array(half + 1)
+  let buf = []                                 // ring of recent smoothed frames
+
+  return {
+    psd,
+    update(mag) {
+      let p = new Float64Array(half + 1)
+      for (let k = 0; k <= half; k++) {
+        let pk = mag[k] * mag[k]
+        smoothed[k] = alpha * smoothed[k] + (1 - alpha) * pk
+        p[k] = smoothed[k]
+      }
+      buf.push(p)
+      if (buf.length > D) buf.shift()
+      for (let k = 0; k <= half; k++) {
+        let mn = Infinity
+        for (let i = 0; i < buf.length; i++) if (buf[i][k] < mn) mn = buf[i][k]
+        psd[k] = mn * bias
+      }
+    }
+  }
+}
+
+// IMCRA — Improved Minima Controlled Recursive Averaging (Cohen 2003).
+// Drives noise PSD via speech-presence probability (SPP) so it stops updating
+// during voiced regions. SPP itself is supplied by the caller (see vad.js spp())
+// or computed internally from the smoothed-to-min PSD ratio.
+export function imcra(half, opts = {}) {
+  let alpha = opts.alpha ?? 0.92
+  let alphaD = opts.alphaD ?? 0.85
+  let beta = opts.beta ?? 1.47
+  let psd = new Float64Array(half + 1)
+  let psdInit = false
+  let smoothed = new Float64Array(half + 1)
+  let mins = new Float64Array(half + 1)
+  let prevMins = new Float64Array(half + 1)
+  let frameCount = 0
+  let resetEvery = opts.resetEvery || 80      // ≈ 0.9 s @ 44.1k, hop=512
+
+  return {
+    psd,
+    update(mag, sppOverride) {
+      let init = !psdInit
+      for (let k = 0; k <= half; k++) {
+        let pk = mag[k] * mag[k]
+        smoothed[k] = init ? pk : alpha * smoothed[k] + (1 - alpha) * pk
+        if (init || smoothed[k] < mins[k]) mins[k] = smoothed[k]
+        if (!init && smoothed[k] < prevMins[k]) prevMins[k] = smoothed[k]
+      }
+      frameCount++
+      if (frameCount >= resetEvery) {
+        for (let k = 0; k <= half; k++) {
+          let mn = Math.min(mins[k], prevMins[k])
+          prevMins[k] = mins[k]
+          mins[k] = smoothed[k]
+          // bias-compensated minimum tracker
+          if (init) psd[k] = mn * beta
+        }
+        frameCount = 0
+        psdInit = true
+      }
+
+      if (!psdInit) return
+
+      for (let k = 0; k <= half; k++) {
+        let mn = Math.min(mins[k], prevMins[k]) * beta
+        // SPP from local SNR vs minimum: high if smoothed >> minimum.
+        let snr = smoothed[k] / Math.max(mn, 1e-30)
+        let p = sppOverride !== undefined ? sppOverride : 1 / (1 + Math.exp(-3 * (snr - 5)))
+        let alphaTilde = alphaD + (1 - alphaD) * p
+        let pk = mag[k] * mag[k]
+        psd[k] = alphaTilde * psd[k] + (1 - alphaTilde) * pk
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@audio/denoise-core",
+  "version": "0.1.0",
+  "description": "Shared restoration primitives — STFT (batch/stream/analyse), noise estimation (min-stats, IMCRA), VAD, AR modeling, quality metrics",
+  "type": "module",
+  "sideEffects": false,
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./stft": "./stft.js",
+    "./util": "./util.js",
+    "./noise": "./noise.js",
+    "./vad": "./vad.js",
+    "./ar": "./ar.js",
+    "./quality": "./quality.js"
+  },
+  "files": [
+    "index.js",
+    "stft.js",
+    "util.js",
+    "noise.js",
+    "vad.js",
+    "ar.js",
+    "quality.js"
+  ],
+  "dependencies": {
+    "fourier-transform": "^2.0.0"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "denoise",
+    "stft",
+    "vad",
+    "noise-estimation"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/denoise.git",
+    "directory": "packages/denoise-core"
+  },
+  "homepage": "https://github.com/audiojs/denoise/tree/main/packages/denoise-core",
+  "bugs": {
+    "url": "https://github.com/audiojs/denoise/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/quality.js

@@ -0,0 +1,115 @@
+// Objective quality metrics for denoise evaluation.
+//   - snr: global signal-to-noise ratio (dB) given clean reference
+//   - segSnr: segmental SNR — frame-averaged, perceptually closer than global
+//   - lsd: log-spectral distance (dB) — spectral colouration regression
+//   - nrr: noise reduction ratio (dB) — how much energy was removed below threshold
+//   - speechAttenuation: how much speech energy was removed (dB) — speech-distortion proxy
+//
+// All metrics expect equal-length Float32Array inputs; trim/align caller-side.
+
+import { fft } from 'fourier-transform'
+import { hannWindow, lin2db } from './util.js'
+
+// Global SNR (dB). Clean = reference, denoised = output. SNR = 10·log10(∑clean² / ∑(clean-out)²)
+export function snr(clean, denoised) {
+  let n = Math.min(clean.length, denoised.length)
+  let s = 0, e = 0
+  for (let i = 0; i < n; i++) {
+    let c = clean[i], d = c - denoised[i]
+    s += c * c
+    e += d * d
+  }
+  return e > 0 ? 10 * Math.log10(s / e) : Infinity
+}
+
+// Segmental SNR — average per-frame SNR clamped to [-10, 35] dB (PESQ-style).
+// Drops silent frames (energy < floor) so silence doesn't bias the mean.
+export function segSnr(clean, denoised, opts = {}) {
+  let N = opts.frameSize || 512
+  let hop = opts.hopSize || (N >> 1)
+  let floor = opts.floor ?? 1e-5
+  let n = Math.min(clean.length, denoised.length)
+  let sum = 0, frames = 0
+  for (let pos = 0; pos + N <= n; pos += hop) {
+    let s = 0, e = 0
+    for (let i = 0; i < N; i++) {
+      let c = clean[pos + i], d = c - denoised[pos + i]
+      s += c * c
+      e += d * d
+    }
+    if (s < floor * N) continue
+    let snr = 10 * Math.log10(s / Math.max(e, 1e-30))
+    sum += Math.max(-10, Math.min(35, snr))
+    frames++
+  }
+  return frames ? sum / frames : 0
+}
+
+// Log-spectral distance (dB), frame-averaged. Lower is better (~1 dB transparent).
+export function lsd(a, b, opts = {}) {
+  let N = opts.frameSize || 1024
+  let hop = opts.hopSize || (N >> 1)
+  let floor = opts.floor ?? 1e-5
+  let win = hannWindow(N)
+  let half = N >> 1
+  let mx = new Float64Array(half + 1), my = new Float64Array(half + 1)
+  let n = Math.min(a.length, b.length)
+  let sum = 0, frames = 0
+  for (let pos = 0; pos + N <= n; pos += hop) {
+    let ex = magFrame(a, pos, win, N, half, mx)
+    let ey = magFrame(b, pos, win, N, half, my)
+    if (ex < floor && ey < floor) continue
+    let peak = 0
+    for (let k = 0; k <= half; k++) {
+      if (mx[k] > peak) peak = mx[k]
+      if (my[k] > peak) peak = my[k]
+    }
+    let mfloor = peak * 1e-3 + 1e-12
+    let acc = 0
+    for (let k = 0; k <= half; k++) {
+      let d = 20 * Math.log10((mx[k] + mfloor) / (my[k] + mfloor))
+      acc += d * d
+    }
+    sum += Math.sqrt(acc / (half + 1))
+    frames++
+  }
+  return frames ? sum / frames : 0
+}
+
+let _scratch = new Map()
+function magFrame(data, pos, win, N, half, magOut) {
+  let f = _scratch.get(N)
+  if (!f) { f = new Float64Array(N); _scratch.set(N, f) }
+  let e = 0
+  for (let i = 0; i < N; i++) {
+    let v = (data[pos + i] || 0) * win[i]
+    f[i] = v
+    e += v * v
+  }
+  let [re, im] = fft(f)
+  for (let k = 0; k <= half; k++) magOut[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
+  return e
+}
+
+// Noise reduction ratio (dB): drop in noise-floor RMS after processing.
+// Caller selects a quiet segment by index. Positive = suppression worked.
+export function nrr(noisy, denoised, from = 0, to) {
+  to = to ?? Math.min(noisy.length, denoised.length)
+  let nIn = 0, nOut = 0, len = to - from
+  for (let i = from; i < to; i++) { nIn += noisy[i] * noisy[i]; nOut += denoised[i] * denoised[i] }
+  let inDb = lin2db(Math.sqrt(nIn / len))
+  let outDb = lin2db(Math.sqrt(nOut / len))
+  return inDb - outDb
+}
+
+// Speech attenuation (dB): drop in clean-signal-active RMS — should be near 0.
+// Pass a clean-segment index range so we measure speech retention.
+export function speechAttenuation(clean, denoised, from = 0, to) {
+  to = to ?? Math.min(clean.length, denoised.length)
+  let cIn = 0, cOut = 0, len = to - from
+  for (let i = from; i < to; i++) {
+    cIn += clean[i] * clean[i]
+    cOut += denoised[i] * denoised[i]
+  }
+  return lin2db(Math.sqrt(cIn / len)) - lin2db(Math.sqrt(cOut / len))
+}

package/stft.js

@@ -0,0 +1,134 @@
+// STFT analysis-modification-synthesis with OLA reconstruction.
+// `process(mag, phase, state, ctx)` returns { mag, phase } for synthesis.
+// State persists across frames; OLA divides by ∑win² to make windowing transparent.
+//
+// Two flavours:
+//   stftBatch — process whole signal, return Float32Array
+//   stftStream — write(chunk) / write() pull-based wrapper for real-time
+
+import { fft, ifft } from 'fourier-transform'
+import { hannWindow, makeStreamBufs, appendIn, growOut, compactIn, take, normFloor, PI2 } from './util.js'
+
+export function wrapPhase(p) { return p - Math.round(p / PI2) * PI2 }
+
+function frame(data, pos, win, half, process, state, ctx, sc) {
+  let N = win.length, f = sc.f
+  for (let i = 0; i < N; i++) f[i] = (data[pos + i] || 0) * win[i]
+
+  let [re, im] = fft(f)
+  let mag = sc.mag, phase = sc.phase
+  for (let k = 0; k <= half; k++) {
+    mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
+    phase[k] = Math.atan2(im[k], re[k])
+  }
+
+  let r = process(mag, phase, state, ctx)
+  let r2 = sc.r2, i2 = sc.i2
+  for (let k = 0; k <= half; k++) {
+    r2[k] = r.mag[k] * Math.cos(r.phase[k])
+    i2[k] = r.mag[k] * Math.sin(r.phase[k])
+  }
+  return ifft(r2, i2)
+}
+
+function scratch(N, half) {
+  return {
+    f: new Float64Array(N),
+    mag: new Float64Array(half + 1),
+    phase: new Float64Array(half + 1),
+    r2: new Float64Array(half + 1),
+    i2: new Float64Array(half + 1)
+  }
+}
+
+export function stftBatch(data, process, opts) {
+  let N = opts?.frameSize || 2048
+  let hop = opts?.hopSize || (N >> 2)
+  let half = N >> 1
+  let win = hannWindow(N)
+  let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
+
+  let outLen = data.length
+  let out = new Float32Array(outLen)
+  let norm = new Float32Array(outLen)
+  let state = {}
+  let sc = scratch(N, half)
+  let pos = 0
+
+  while (pos + N <= outLen + hop) {
+    let sf = frame(data, pos, win, half, process, state, ctx, sc)
+    for (let i = 0; i < N && pos + i < outLen; i++) {
+      out[pos + i] += sf[i] * win[i]
+      norm[pos + i] += win[i] * win[i]
+    }
+    pos += hop
+  }
+
+  let nf = normFloor(win, hop)
+  for (let i = 0; i < outLen; i++) {
+    let n = Math.max(norm[i], nf)
+    if (n > 1e-8) out[i] /= n
+  }
+  return out
+}
+
+export function stftStream(process, opts) {
+  let N = opts?.frameSize || 2048
+  let hop = opts?.hopSize || (N >> 2)
+  let half = N >> 1
+  let win = hannWindow(N)
+  let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
+  let state = {}, sc = scratch(N, half)
+  let nf = normFloor(win, hop)
+
+  let st = makeStreamBufs(N, nf)
+  let aPos = 0, flushed = false
+
+  function run() {
+    while (aPos + N <= st.il) {
+      let sf = frame(st.ib, aPos, win, half, process, state, ctx, sc)
+      growOut(st, st.pos + N)
+      let ob = st.ob, nb = st.nb, base = st.pos
+      for (let i = 0; i < N; i++) {
+        ob[base + i] += sf[i] * win[i]
+        nb[base + i] += win[i] * win[i]
+      }
+      aPos += hop
+      st.pos += hop
+    }
+    if (aPos > N * 2) { compactIn(st, aPos - N); aPos -= aPos - N }
+  }
+
+  return {
+    write(chunk) {
+      appendIn(st, chunk); run()
+      return take(st, Math.max(0, st.pos - N + hop))
+    },
+    flush() {
+      if (!flushed) { appendIn(st, new Float32Array(N)); flushed = true }
+      run()
+      return take(st, st.pos)
+    }
+  }
+}
+
+// Analysis-only sweep — visit every frame's magnitude+phase but produce no output.
+// Used by VAD, noise-profile estimators, dereverb late-tail estimation.
+export function stftAnalyse(data, visit, opts) {
+  let N = opts?.frameSize || 2048
+  let hop = opts?.hopSize || (N >> 2)
+  let half = N >> 1
+  let win = hannWindow(N)
+  let f = new Float64Array(N)
+  let mag = new Float64Array(half + 1), phase = new Float64Array(half + 1)
+
+  for (let pos = 0; pos + N <= data.length; pos += hop) {
+    for (let i = 0; i < N; i++) f[i] = data[pos + i] * win[i]
+    let [re, im] = fft(f)
+    for (let k = 0; k <= half; k++) {
+      mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
+      phase[k] = Math.atan2(im[k], re[k])
+    }
+    visit(mag, phase, pos)
+  }
+}

package/util.js

@@ -0,0 +1,182 @@
+// Shared helpers: window functions, dB conversions, biquad cascade, streaming buffers.
+
+export const PI2 = Math.PI * 2
+
+export function clamp(v, min, max) { return v < min ? min : v > max ? max : v }
+
+export function db2lin(db) { return Math.pow(10, db / 20) }
+export function lin2db(x) { return 20 * Math.log10(Math.max(x, 1e-30)) }
+
+let _hannCache = new Map()
+export function hannWindow(N) {
+  let w = _hannCache.get(N)
+  if (w) return w
+  w = new Float64Array(N)
+  for (let i = 0; i < N; i++) w[i] = 0.5 * (1 - Math.cos(PI2 * i / N))
+  _hannCache.set(N, w)
+  return w
+}
+
+let _sqrtHannCache = new Map()
+export function sqrtHannWindow(N) {
+  let w = _sqrtHannCache.get(N)
+  if (w) return w
+  let h = hannWindow(N)
+  w = new Float64Array(N)
+  for (let i = 0; i < N; i++) w[i] = Math.sqrt(h[i])
+  _sqrtHannCache.set(N, w)
+  return w
+}
+
+// Wrap stream { write, flush } into write(chunk) → process, write() → flush
+export function writer(s) { return chunk => chunk ? s.write(chunk) : s.flush() }
+
+// Apply a single biquad section in-place, persisting state in s = [z1, z2].
+export function biquad(data, b0, b1, b2, a1, a2, s) {
+  let z1 = s[0], z2 = s[1]
+  for (let i = 0, l = data.length; i < l; i++) {
+    let x = data[i]
+    let y = b0 * x + z1
+    z1 = b1 * x - a1 * y + z2
+    z2 = b2 * x - a2 * y
+    data[i] = y
+  }
+  s[0] = z1; s[1] = z2
+}
+
+// Cascade of biquad sections. coefs: array of {b0,b1,b2,a1,a2}. state: 2-num arrays per section.
+export function biquadCascade(data, coefs, state) {
+  for (let i = 0; i < coefs.length; i++) {
+    let c = coefs[i]
+    biquad(data, c.b0, c.b1, c.b2, c.a1, c.a2, state[i])
+  }
+}
+
+// RBJ notch (peak-rejection) at fc with quality Q. Normalized a0 = 1.
+export function notchCoefs(fc, Q, fs) {
+  let w = PI2 * fc / fs
+  let cw = Math.cos(w), sw = Math.sin(w)
+  let alpha = sw / (2 * Q)
+  let a0 = 1 + alpha
+  return {
+    b0: 1 / a0,
+    b1: -2 * cw / a0,
+    b2: 1 / a0,
+    a1: -2 * cw / a0,
+    a2: (1 - alpha) / a0
+  }
+}
+
+// RBJ high-pass at fc, Q.
+export function highpassCoefs(fc, Q, fs) {
+  let w = PI2 * fc / fs
+  let cw = Math.cos(w), sw = Math.sin(w)
+  let alpha = sw / (2 * Q)
+  let a0 = 1 + alpha
+  return {
+    b0: (1 + cw) / 2 / a0,
+    b1: -(1 + cw) / a0,
+    b2: (1 + cw) / 2 / a0,
+    a1: -2 * cw / a0,
+    a2: (1 - alpha) / a0
+  }
+}
+
+// RBJ low-pass at fc, Q.
+export function lowpassCoefs(fc, Q, fs) {
+  let w = PI2 * fc / fs
+  let cw = Math.cos(w), sw = Math.sin(w)
+  let alpha = sw / (2 * Q)
+  let a0 = 1 + alpha
+  return {
+    b0: (1 - cw) / 2 / a0,
+    b1: (1 - cw) / a0,
+    b2: (1 - cw) / 2 / a0,
+    a1: -2 * cw / a0,
+    a2: (1 - alpha) / a0
+  }
+}
+
+// RBJ peaking EQ at fc, Q, gain in dB.
+export function peakingCoefs(fc, Q, gainDb, fs) {
+  let A = Math.pow(10, gainDb / 40)
+  let w = PI2 * fc / fs
+  let cw = Math.cos(w), sw = Math.sin(w)
+  let alpha = sw / (2 * Q)
+  let a0 = 1 + alpha / A
+  return {
+    b0: (1 + alpha * A) / a0,
+    b1: -2 * cw / a0,
+    b2: (1 - alpha * A) / a0,
+    a1: -2 * cw / a0,
+    a2: (1 - alpha / A) / a0
+  }
+}
+
+// Streaming buffer state: input ring (grow-on-demand), output OLA buffer + norm buffer.
+// Plain data + free functions — no accessors/closures, stays in the jz subset.
+export function makeStreamBufs(N, nf = 0) {
+  return {
+    N, nf,
+    ib: new Float32Array(N * 4), il: 0,
+    ob: new Float32Array(N * 8), nb: new Float32Array(N * 8),
+    pos: 0, oread: 0
+  }
+}
+
+export function appendIn(st, chunk) {
+  let need = st.il + chunk.length
+  if (need > st.ib.length) {
+    let b = new Float32Array(Math.max(need * 2, st.ib.length * 2))
+    b.set(st.ib.subarray(0, st.il)); st.ib = b
+  }
+  st.ib.set(chunk, st.il); st.il += chunk.length
+}
+
+export function growOut(st, need) {
+  if (need <= st.ob.length) return
+  let len = Math.max(need * 2, st.ob.length * 2)
+  let o = new Float32Array(len), n = new Float32Array(len)
+  o.set(st.ob); n.set(st.nb); st.ob = o; st.nb = n
+}
+
+export function compactIn(st, trim) {
+  if (trim <= 0) return
+  st.ib.copyWithin(0, trim, st.il); st.il -= trim
+}
+
+export function take(st, upTo) {
+  upTo = Math.min(upTo, st.pos)
+  if (upTo <= st.oread) return new Float32Array(0)
+  let len = Math.floor(upTo - st.oread)
+  let out = new Float32Array(len)
+  for (let i = 0; i < len; i++) {
+    let j = st.oread + i, n = st.nf > 0 ? Math.max(st.nb[j], st.nf) : st.nb[j]
+    out[i] = n > 1e-8 ? st.ob[j] / n : 0
+  }
+  st.oread += len
+  if (st.oread > st.N * 8) {
+    st.ob.copyWithin(0, st.oread); st.nb.copyWithin(0, st.oread)
+    st.pos -= st.oread; st.oread = 0
+    st.ob.fill(0, st.pos); st.nb.fill(0, st.pos)
+  }
+  return out
+}
+
+// Steady-state win² sum — floor prevents amplification at OLA boundaries.
+export function normFloor(win, hop) {
+  let N = win.length, min = Infinity
+  for (let i = 0; i < hop; i++) {
+    let s = 0
+    for (let j = i; j < N; j += hop) s += win[j] * win[j]
+    if (s > 0 && s < min) min = s
+  }
+  return min === Infinity ? 0 : min
+}
+
+// In-place RMS (per chunk).
+export function rms(data) {
+  let s = 0
+  for (let i = 0; i < data.length; i++) s += data[i] * data[i]
+  return Math.sqrt(s / data.length)
+}

package/vad.js

@@ -0,0 +1,91 @@
+// Voice Activity Detection + Speech Presence Probability.
+//   - vad: hard 0/1 decision per frame from energy + spectral flatness + ZCR
+//   - spp: soft probability per bin from a-priori SNR (drives OM-LSA, IMCRA)
+//
+// Use vad() for gating decisions (debreath, gate); spp() for spectral denoise gain.
+
+import { stftAnalyse } from './stft.js'
+import { lin2db } from './util.js'
+
+// Returns { active: Uint8Array(frames), times: Float32Array(frames) of frame-start sec }.
+// Active iff energy is N dB above the rolling noise floor AND spectral flatness < flatTh.
+//
+// Floor estimation: minimum of energy over a sliding D-frame window with bias
+// correction — Martin-style minimum tracking. This avoids the "speech eats its own
+// floor" failure mode of plain exponential smoothing.
+//
+// flatTh ≈ 0.4 — speech is tonal (low flatness), noise is flat (high flatness).
+export function vad(data, opts = {}) {
+  let N = opts.frameSize || 1024
+  let hop = opts.hopSize || (N >> 1)
+  let fs = opts.fs || 44100
+  let snrTh = opts.snrTh ?? 6                  // dB above floor
+  let flatTh = opts.flatTh ?? 0.4              // spectral flatness threshold
+  let D = opts.window || 64                    // frames in min-tracker window
+  let bias = opts.bias ?? 5                    // dB — added to min to estimate true floor
+
+  let frames = Math.max(0, Math.floor((data.length - N) / hop) + 1)
+  let active = new Uint8Array(frames)
+  let times = new Float32Array(frames)
+  let energies = new Float64Array(frames)
+  let flats = new Float64Array(frames)
+  let i = 0
+
+  stftAnalyse(data, (mag, _phase, pos) => {
+    let half = mag.length - 1, e = 0
+    let logSum = 0, linSum = 0, nz = 0
+    for (let k = 1; k <= half; k++) {
+      let p = mag[k] * mag[k]
+      e += p
+      if (p > 1e-30) { logSum += Math.log(p); nz++ }
+      linSum += p
+    }
+    let geom = nz ? Math.exp(logSum / nz) : 0
+    let arith = linSum / Math.max(half, 1)
+    flats[i] = arith > 1e-30 ? geom / arith : 1
+    energies[i] = lin2db(Math.sqrt(e / N))
+    times[i] = pos / fs
+    i++
+  }, { frameSize: N, hopSize: hop })
+
+  // Global noise floor = 10th-percentile energy + bias. Robust on signals where
+  // any short window may be entirely speech.
+  let sorted = Float64Array.from(energies).sort()
+  let floor = sorted[Math.floor(sorted.length * 0.1)] + bias
+
+  for (let j = 0; j < frames; j++) {
+    active[j] = (energies[j] - floor > snrTh && flats[j] < flatTh) ? 1 : 0
+  }
+  return { active, times, hop, frameSize: N }
+}
+
+// Per-bin Speech Presence Probability from a-priori SNR ξ:
+//   p = ξ / (1 + ξ)   (Bayesian formulation under Gaussian model, q-prior = 0.5)
+// Bind to a noise PSD source (e.g. minStats.psd or imcra.psd) and an a-priori SNR estimate.
+export function spp(mag, noisePsd, opts = {}) {
+  let xiMin = opts.xiMin ?? 0.0316             // -15 dB floor
+  let half = mag.length - 1
+  let p = new Float64Array(half + 1)
+  for (let k = 0; k <= half; k++) {
+    let post = (mag[k] * mag[k]) / Math.max(noisePsd[k], 1e-30) - 1
+    let xi = Math.max(xiMin, post)
+    p[k] = xi / (1 + xi)
+  }
+  return p
+}
+
+// Decision-Directed a-priori SNR (Ephraim-Malah 1984), recursive smoothing.
+//   ξ̂[k] = α · |X̂_prev[k]|² / N̂[k]  +  (1-α) · max(γ-1, 0)
+// γ = posterior SNR = |Y[k]|² / N̂[k]. Used by Wiener, MMSE, OM-LSA gain rules.
+export function ddSnr(mag, noisePsd, prevGain, prevMag, alpha = 0.98) {
+  let half = mag.length - 1
+  let xi = new Float64Array(half + 1)
+  for (let k = 0; k <= half; k++) {
+    let n = Math.max(noisePsd[k], 1e-30)
+    let post = (mag[k] * mag[k]) / n
+    let g = prevGain[k] * prevMag[k]
+    let prev = (g * g) / n
+    xi[k] = Math.max(0.0316, alpha * prev + (1 - alpha) * Math.max(post - 1, 0))
+  }
+  return xi
+}