@audio/quality 1.0.0

package/README.md

@@ -0,0 +1,30 @@
+# @audio/quality
+
+> Objective audio quality metrics — how close is the processed signal to the reference?
+
+Reference-vs-output comparison for evaluating denoisers, stretchers, codecs, resamplers. Deterministic, no model weights.
+
+```js
+import { snr, segSnr, lsd, spectralSim, modulationDepth } from '@audio/quality'
+
+snr(clean, processed)                   // global SNR, dB
+segSnr(clean, processed)                // frame-averaged, PESQ-style clamp
+lsd(a, b, { trim: 0.1 })                // log-spectral distance, dB — ~1 transparent, >5 degraded
+spectralSim(a, b)                       // cosine similarity of magnitude spectra, 1 = identical
+modulationDepth(out, [220, 440], 44100) // per-partial hop-rate beating ("crumble")
+```
+
+| fn | measures | notes |
+|---|---|---|
+| `snr(clean, out)` | global SNR (dB) | time-aligned inputs |
+| `segSnr(clean, out, opts?)` | segmental SNR (dB) | per-frame, [-10, 35] clamp, silence-skipped |
+| `lsd(a, b, opts?)` | log-spectral distance (dB) | `trim` crops edge artifacts (default 0) |
+| `spectralSim(a, b, opts?)` | spectral cosine similarity | alignment-free |
+| `nrr(noisy, out, from?, to?)` | noise-floor drop (dB) | pass a quiet-segment range |
+| `speechAttenuation(clean, out, from?, to?)` | speech-energy loss (dB) | should be ≈0 |
+| `goertzelEnergy(data, f, sr)` | single-frequency energy | Goertzel, 20% edge trim |
+| `chordBalance(data, freqs, sr)` | min/max partial ratio | 1 = balanced |
+| `chordRetention(data, ref, freqs, sr)` | chord energy kept | 1 = no loss |
+| `modulationDepth(data, freqs, sr, opts?)` | AM depth per partial | catches tremolo LSD misses |
+
+Consolidated from the [denoise](https://github.com/audiojs/denoise) and [stretch](https://github.com/audiojs/stretch) families' evaluation suites. FFT via [fourier-transform](https://github.com/scijs/fourier-transform). MIT.

package/index.js

@@ -0,0 +1,258 @@
+// Objective audio quality metrics — reference-vs-output comparison.
+//   - snr / segSnr: global and segmental signal-to-noise ratio (dB)
+//   - lsd: frame-averaged log-spectral distance (dB) — spectral colouration
+//   - spectralSim: frame-averaged cosine similarity of magnitude spectra
+//   - nrr / speechAttenuation: noise-suppression vs speech-retention (dB)
+//   - goertzelEnergy / chordBalance / chordRetention / modulationDepth: per-partial
+//     energy tracking — catches hop-rate beating ("crumble") that LSD misses
+//
+// All metrics expect Float32Array inputs; equal length unless noted. Consolidated
+// from the denoise and stretch families' evaluation suites (one lsd, one source).
+
+import { fft } from 'fourier-transform'
+
+const PI2 = Math.PI * 2
+
+let _hannCache = new Map()
+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
+}
+
+const lin2db = x => 20 * Math.log10(Math.max(x, 1e-30))
+
+// fft() returns zero-copy views into a per-size cache — copy magnitudes immediately.
+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
+}
+
+// Trim edges (algorithm startup/tail artifacts) and crop to common length.
+function align(a, b, trim) {
+  let n = Math.min(a.length, b.length)
+  let cut = Math.floor(n * trim)
+  let len = n - 2 * cut
+  return [a.subarray(cut, cut + len), b.subarray(cut, cut + len)]
+}
+
+// Global SNR (dB). Clean = reference, out = processed. SNR = 10·log10(∑clean² / ∑(clean-out)²)
+export function snr(clean, out) {
+  let n = Math.min(clean.length, out.length)
+  let s = 0, e = 0
+  for (let i = 0; i < n; i++) {
+    let c = clean[i], d = c - out[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, out, opts = {}) {
+  let N = opts.frameSize || 512
+  let hop = opts.hopSize || (N >> 1)
+  let floor = opts.floor ?? 1e-5
+  let n = Math.min(clean.length, out.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 - out[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
+}
+
+// Frame-averaged log-spectral distance in dB. Lower is better.
+// ~1 dB: transparent. 2–4 dB: audible colouration. >5 dB: degraded.
+// `trim` crops that fraction off each edge before comparing (startup/tail artifacts);
+// default 0 = compare everything (time-aligned use); stretch/shift evaluation
+// typically passes ~0.1.
+export function lsd(a, b, opts = {}) {
+  let N = opts.frameSize || 1024
+  let hop = opts.hopSize || (N >> 1)
+  let trim = opts.trim ?? 0
+  let floor = opts.floor ?? 1e-5
+
+  let [x, y] = trim > 0 ? align(a, b, trim) : [a, b]
+  let win = hannWindow(N)
+  let half = N >> 1
+  let mx = new Float64Array(half + 1), my = new Float64Array(half + 1)
+  let n = Math.min(x.length, y.length)
+  let sum = 0, frames = 0
+
+  for (let pos = 0; pos + N <= n; pos += hop) {
+    let ex = magFrame(x, pos, win, N, half, mx)
+    let ey = magFrame(y, pos, win, N, half, my)
+    if (ex < floor && ey < floor) continue
+
+    // Per-frame peak-relative magnitude floor: prevents log amplification of
+    // near-silent bins (critical for pure tones where one bin holds all energy).
+    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
+}
+
+// Frame-averaged cosine similarity of magnitude spectra. 1 = identical.
+export function spectralSim(a, b, opts = {}) {
+  let N = opts.frameSize || 1024
+  let hop = opts.hopSize || (N >> 1)
+  let trim = opts.trim ?? 0.1
+  let floor = opts.floor ?? 1e-5
+
+  let [x, y] = align(a, b, trim)
+  let win = hannWindow(N)
+  let half = N >> 1
+  let mx = new Float64Array(half + 1), my = new Float64Array(half + 1)
+  let sum = 0, frames = 0
+
+  for (let pos = 0; pos + N <= x.length; pos += hop) {
+    let ex = magFrame(x, pos, win, N, half, mx)
+    let ey = magFrame(y, pos, win, N, half, my)
+    if (ex < floor || ey < floor) continue
+
+    let dot = 0, nx = 0, ny = 0
+    for (let k = 0; k <= half; k++) {
+      dot += mx[k] * my[k]
+      nx += mx[k] * mx[k]
+      ny += my[k] * my[k]
+    }
+    let denom = Math.sqrt(nx * ny)
+    if (denom > 0) { sum += dot / denom; frames++ }
+  }
+  return frames ? sum / frames : 0
+}
+
+// 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, out, from = 0, to) {
+  to = to ?? Math.min(noisy.length, out.length)
+  let nIn = 0, nOut = 0, len = to - from
+  for (let i = from; i < to; i++) { nIn += noisy[i] * noisy[i]; nOut += out[i] * out[i] }
+  return lin2db(Math.sqrt(nIn / len)) - lin2db(Math.sqrt(nOut / len))
+}
+
+// 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, out, from = 0, to) {
+  to = to ?? Math.min(clean.length, out.length)
+  let cIn = 0, cOut = 0, len = to - from
+  for (let i = from; i < to; i++) {
+    cIn += clean[i] * clean[i]
+    cOut += out[i] * out[i]
+  }
+  return lin2db(Math.sqrt(cIn / len)) - lin2db(Math.sqrt(cOut / len))
+}
+
+// Goertzel energy at a single frequency. Trims 20% edges to avoid artifacts.
+export function goertzelEnergy(data, freq, sr) {
+  let w = 2 * Math.PI * freq / sr, c = 2 * Math.cos(w), s1 = 0, s2 = 0
+  let start = Math.floor(data.length * 0.2), end = Math.floor(data.length * 0.8)
+  for (let i = start; i < end; i++) { let s = data[i] + c * s1 - s2; s2 = s1; s1 = s }
+  return Math.sqrt(s1 * s1 + s2 * s2 - c * s1 * s2) / (end - start)
+}
+
+// Ratio of min/max partial energies. 1.0 = perfectly balanced, 0 = one partial destroyed.
+export function chordBalance(data, freqs, sr) {
+  let energies = freqs.map(f => goertzelEnergy(data, f, sr))
+  let mn = Math.min(...energies), mx = Math.max(...energies)
+  return mx > 1e-10 ? mn / mx : 0
+}
+
+// Total chord energy preserved relative to reference. 1.0 = no loss.
+export function chordRetention(data, ref, freqs, sr) {
+  let refE = freqs.reduce((s, f) => s + goertzelEnergy(ref, f, sr), 0)
+  let outE = freqs.reduce((s, f) => s + goertzelEnergy(data, f, sr), 0)
+  return refE > 1e-10 ? outE / refE : 0
+}
+
+// Per-partial amplitude-modulation depth — captures hop-rate beating ("crumble")
+// that LSD misses. 0 = stable, ~0.05 = transparent, ~0.3+ = obvious tremolo.
+export function modulationDepth(data, freqs, sr, opts = {}) {
+  let win = opts.envWindow || 2048
+  let hop = opts.envHop || 256
+  let trim = opts.trim ?? 0.1
+  let cut = Math.floor(data.length * trim)
+  let len = data.length - 2 * cut
+  if (len < win * 2) return 0
+  let frames = Math.floor((len - win) / hop) + 1
+  if (frames < 8) return 0
+
+  let hann = new Float64Array(win)
+  let hannSum = 0
+  for (let i = 0; i < win; i++) { hann[i] = 0.5 * (1 - Math.cos(2 * Math.PI * i / (win - 1))); hannSum += hann[i] }
+
+  // Two-pass: first measure each partial's mean amplitude, then only score those
+  // above 5% of the loudest. Otherwise weak/absent partials score huge spurious
+  // modulation from spectral-leakage noise.
+  let envs = freqs.map(() => new Float64Array(frames))
+  let means = new Float64Array(freqs.length)
+  for (let fi = 0; fi < freqs.length; fi++) {
+    let f = freqs[fi]
+    let w = 2 * Math.PI * f / sr
+    let env = envs[fi]
+    let mean = 0
+    for (let k = 0; k < frames; k++) {
+      let re = 0, im = 0, base = cut + k * hop
+      for (let i = 0; i < win; i++) {
+        let s = data[base + i] * hann[i]
+        let phase = w * i
+        re += s * Math.cos(phase)
+        im -= s * Math.sin(phase)
+      }
+      let mag = Math.sqrt(re * re + im * im) / hannSum
+      env[k] = mag
+      mean += mag
+    }
+    means[fi] = mean / frames
+  }
+
+  let maxMean = 0
+  for (let i = 0; i < means.length; i++) if (means[i] > maxMean) maxMean = means[i]
+  let floor = maxMean * 0.05
+
+  let worst = 0
+  for (let i = 0; i < freqs.length; i++) {
+    if (means[i] < floor) continue
+    let env = envs[i], mean = means[i]
+    let acVar = 0
+    for (let k = 0; k < frames; k++) { let d = env[k] - mean; acVar += d * d }
+    let depth = Math.sqrt(acVar / frames) / mean
+    if (depth > worst) worst = depth
+  }
+  return worst
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@audio/quality",
+  "version": "1.0.0",
+  "description": "Objective audio quality metrics — SNR, segmental SNR, log-spectral distance, spectral similarity, noise-reduction ratio, per-partial modulation depth",
+  "type": "module",
+  "sideEffects": false,
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js"
+  ],
+  "dependencies": {
+    "fourier-transform": "^2.2.0"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "quality",
+    "metrics",
+    "snr",
+    "log-spectral-distance",
+    "lsd",
+    "evaluation"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/measure.git",
+    "directory": "packages/quality"
+  },
+  "homepage": "https://github.com/audiojs/measure/tree/main/packages/quality",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}