@audio/quality 1.0.1 → 1.1.0

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.
package/README.md CHANGED
@@ -5,13 +5,14 @@
5
5
  Reference-vs-output comparison for evaluating denoisers, stretchers, codecs, resamplers. Deterministic, no model weights.
6
6
 
7
7
  ```js
8
- import { snr, segSnr, lsd, spectralSim, modulationDepth } from '@audio/quality'
8
+ import { snr, segSnr, lsd, spectralSim, modulationDepth, stoi, estoi } from '@audio/quality'
9
9
 
10
10
  snr(clean, processed) // global SNR, dB
11
11
  segSnr(clean, processed) // frame-averaged, PESQ-style clamp
12
12
  lsd(a, b, { trim: 0.1 }) // log-spectral distance, dB — ~1 transparent, >5 degraded
13
13
  spectralSim(a, b) // cosine similarity of magnitude spectra, 1 = identical
14
14
  modulationDepth(out, [220, 440], 44100) // per-partial hop-rate beating ("crumble")
15
+ stoi(clean, processed, 16000) // speech intelligibility, about 0 to 1; estoi for noise that comes and goes
15
16
  ```
16
17
 
17
18
  | fn | measures | notes |
@@ -26,5 +27,9 @@ modulationDepth(out, [220, 440], 44100) // per-partial hop-rate beating ("crumbl
26
27
  | `chordBalance(data, freqs, sr)` | min/max partial ratio | 1 = balanced |
27
28
  | `chordRetention(data, ref, freqs, sr)` | chord energy kept | 1 = no loss |
28
29
  | `modulationDepth(data, freqs, sr, opts?)` | AM depth per partial | catches tremolo LSD misses |
30
+ | `stoi(clean, out, fs)` | speech intelligibility, about 0 to 1 | STOI; speech only, time-aligned, equal lengths |
31
+ | `estoi(clean, out, fs)` | speech intelligibility, about 0 to 1 | ESTOI; holds for a masker that comes and goes |
29
32
 
30
- 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.
33
+ `stoi` and `estoi` rise with the share of words a listener gets right, but are not that share: how one maps to the other depends on the test. Speech only, the two signals time-aligned (384 ms envelopes are compared frame by frame), at any integer `fs` (resampled to the measure's 10 kHz). STOI ([Taal et al. 2011](https://doi.org/10.1109/TASL.2011.2114881)) takes the bands as independent; ESTOI ([Jensen, Taal 2016](https://doi.org/10.1109/TASLP.2016.2585878)) correlates whole spectra, so it holds under another talker or modulated noise, where STOI can rank conditions in reverse. Correlation with listening tests, each after a fitted monotone map: STOI 0.92 to 0.96 in its paper's three tests, ESTOI 0.89 to 0.98 in its paper's five; over 13 data sets from ten published tests, a few of them used to build the two, 0.80 and 0.86 on average and 0.35 and 0.43 for speech in strong reverberation ([van Kuyk et al.](https://arxiv.org/abs/1708.06027)). NaN when under about 0.4 s of speech is left or `clean` is silent; unequal lengths, several channels or a non-integer rate throw.
34
+
35
+ 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). STOI and ESTOI ported from [pystoi](https://github.com/mpariente/pystoi) 0.4.1 (Manuel Pariente, MIT), resampler and silent-frame removal included, and held to it to 1e-9. MIT.
package/index.d.ts CHANGED
@@ -74,3 +74,14 @@ export function modulationDepth(
74
74
  sr: number,
75
75
  options?: ModulationDepthOptions
76
76
  ): number
77
+
78
+ /**
79
+ * STOI (Taal et al. 2011): intelligibility of the speech in `out` against the clean speech, about 0 to 1, rising with
80
+ * the share of words listeners understand (not that share). Mono, time-aligned, equal lengths, any integer `fs`
81
+ * (resampled to 10 kHz). NaN under 30 frames (about 0.4 s) of speech or for a silent `clean`; 0 for a silent `out`.
82
+ * Throws RangeError on unequal lengths or a non-integer rate, TypeError on several channels. Positional sample rate.
83
+ */
84
+ export function stoi(clean: Float32Array, out: Float32Array, fs: number): number
85
+
86
+ /** ESTOI (Jensen and Taal 2016): STOI with whole spectra correlated, so it holds for a masker that comes and goes (another talker, modulated noise). Inputs, NaN and throws as stoi. */
87
+ export function estoi(clean: Float32Array, out: Float32Array, fs: number): number
package/index.js CHANGED
@@ -5,6 +5,7 @@
5
5
  // - nrr / speechAttenuation: noise-suppression vs speech-retention (dB)
6
6
  // - goertzelEnergy / chordBalance / chordRetention / modulationDepth: per-partial
7
7
  // energy tracking — catches hop-rate beating ("crumble") that LSD misses
8
+ // - stoi / estoi: speech intelligibility against the clean speech (Taal et al. 2011, Jensen and Taal 2016)
8
9
  //
9
10
  // All metrics expect Float32Array inputs; equal length unless noted. Consolidated
10
11
  // from the denoise and stretch families' evaluation suites (one lsd, one source).
@@ -256,3 +257,163 @@ export function modulationDepth(data, freqs, sr, opts = {}) {
256
257
  }
257
258
  return worst
258
259
  }
260
+
261
+ // Speech intelligibility against the clean speech, a number from about 0 to 1 that rises with the share of words
262
+ // listeners understand (not that share itself).
263
+ // [1] C. H. Taal, R. C. Hendriks, R. Heusdens, J. Jensen, "An Algorithm for Intelligibility Prediction of
264
+ // Time-Frequency Weighted Noisy Speech", IEEE Trans. Audio, Speech, Lang. Process. 19(7), 2011, sec. II: STOI.
265
+ // [2] J. Jensen, C. H. Taal, "An Algorithm for Predicting the Intelligibility of Speech Masked by Modulated Noise
266
+ // Maskers", IEEE/ACM Trans. Audio, Speech, Lang. Process. 24(11), 2016, sec. II: ESTOI.
267
+ // Ported from pystoi 0.4.1 (github.com/mpariente/pystoi at 74872b0; Copyright (c) 2018 Pariente Manuel, MIT licence)
268
+ // and held to it by test.js; a step that follows its code rather than the papers names its file.
269
+
270
+ const FS = 10000 // [1] sec. II, [2] sec. II-C: both signals at 10 kHz
271
+ const FRAME = 256, HOP = 128, NFFT = 512 // [1] sec. II: Hann frames of 256 samples, 50% overlap, zero-padded to 512
272
+ const BANDS = 15, LOW = 150 // [1] sec. II: 15 one-third octave bands, the lowest centred at 150 Hz
273
+ const N = 30 // [1] eq. 2: 30 frames to a segment, 384 ms
274
+ const CLIP = 1 + 10 ** (15 / 20) // [1] eq. 3: 1 + 10^(-β/20), β = -15 dB, the lower signal-to-distortion bound
275
+ const RANGE = 40 // [1] sec. II: a frame 40 dB under the clean speech's loudest is silent
276
+ const EPS = Number.EPSILON // pystoi/utils.py EPS, added where pystoi adds it
277
+
278
+ // MATLAB's hanning(256), as pystoi/utils.py takes it: np.hanning(258)[1:-1]
279
+ const WIN = Float64Array.from({ length: FRAME }, (_, n) => 0.5 - 0.5 * Math.cos(PI2 * (n + 1) / (FRAME + 1)))
280
+ // [1] eq. 1: band j sums the DFT bins EDGES[j] to EDGES[j + 1] - 1, the edges 150·2^((2j - 1)/6) Hz rounded to the
281
+ // nearest bin (pystoi/utils.py thirdoct); a band's upper edge is the next one's lower
282
+ const EDGES = Array.from({ length: BANDS + 1 }, (_, j) => Math.round(LOW * 2 ** ((2 * j - 1) / 6) * NFFT / FS))
283
+
284
+ /** STOI [1] of `out` against the clean speech, both mono at `fs` Hz and time-aligned */
285
+ export const stoi = (clean, out, fs) => intelligibility(clean, out, fs, false)
286
+
287
+ /** ESTOI [2]: STOI's bands judged together, for noise that comes and goes (a talker, a fluctuating masker) */
288
+ export const estoi = (clean, out, fs) => intelligibility(clean, out, fs, true)
289
+
290
+ function intelligibility(clean, out, fs, extended) {
291
+ let name = extended ? 'estoi' : 'stoi'
292
+ if (!Number.isInteger(fs) || fs <= 0) throw new RangeError(`${name}: fs must be a sample rate in Hz, got ${fs}`)
293
+ if (!mono(clean) || !mono(out)) throw new TypeError(`${name}: one channel each: pass a Float32Array (a channel, or the channels' mean)`)
294
+ if (clean.length !== out.length) throw new RangeError(`${name}: clean has ${clean.length} samples, out ${out.length}: align them and cut both to one length`)
295
+ // no speech in the reference: nothing to understand, no measure (pystoi gives 0)
296
+ if (!clean.some(v => v !== 0)) return NaN
297
+ let [x, y] = speech(to10k(clean, fs), to10k(out, fs))
298
+ let X = envelopes(x), Y = envelopes(y), M = X.length / BANDS
299
+ // fewer than 30 frames of speech: no segment, no measure (pystoi/stoi.py warns and gives 1e-5)
300
+ if (M < N) return NaN
301
+ let S = M - N + 1, d = 0
302
+ if (!extended) {
303
+ let a = new Float64Array(N), b = new Float64Array(N)
304
+ for (let m = 0; m < S; m++) for (let j = 0; j < BANDS; j++) {
305
+ let o = j * M + m, ex = 0, ey = 0
306
+ for (let n = 0; n < N; n++) { ex += X[o + n] ** 2; ey += Y[o + n] ** 2 }
307
+ // [1] eq. 3: out's envelope scaled to the clean one's energy, then clipped to (1 + 10^(-β/20)) times the clean one
308
+ let g = Math.sqrt(ex) / (Math.sqrt(ey) + EPS)
309
+ for (let n = 0; n < N; n++) { a[n] = X[o + n]; b[n] = Math.min(g * Y[o + n], CLIP * X[o + n]) }
310
+ // [1] eq. 5: their correlation coefficient (pystoi/stoi.py adds EPS to each norm)
311
+ unit(a, 0, 1, N, EPS); unit(b, 0, 1, N, EPS)
312
+ for (let n = 0; n < N; n++) d += a[n] * b[n]
313
+ }
314
+ return d / (S * BANDS) // [1] eq. 6: the mean over bands and segments
315
+ }
316
+ let A = new Float64Array(BANDS * N), B = new Float64Array(BANDS * N)
317
+ for (let m = 0; m < S; m++) {
318
+ for (let j = 0; j < BANDS; j++) for (let n = 0; n < N; n++) { A[j * N + n] = X[j * M + m + n]; B[j * N + n] = Y[j * M + m + n] }
319
+ // [2] eq. 1-2: each band's envelope over the segment (a row) to zero mean and unit norm, then sec. II-A: each
320
+ // frame's spectrum (a column) likewise
321
+ for (let j = 0; j < BANDS; j++) { unit(A, j * N, 1, N); unit(B, j * N, 1, N) }
322
+ for (let n = 0; n < N; n++) { unit(A, n, N, BANDS); unit(B, n, N, BANDS) }
323
+ // [2] eq. 4: the mean over the segment's frames of their spectra's correlation
324
+ let s = 0
325
+ for (let i = 0; i < BANDS * N; i++) s += A[i] * B[i]
326
+ d += s / N
327
+ }
328
+ return d / S // [2] eq. 5: the mean over segments
329
+ }
330
+
331
+ const mono = x => x != null && typeof x.length === 'number' && (x.length === 0 || typeof x[0] === 'number')
332
+
333
+ // n values of v from o at a stride: less their mean, over their norm (plus eps); left at zero when all are equal,
334
+ // where pystoi's ESTOI (utils.py row_col_normalize) adds noise of EPS and returns a random direction
335
+ function unit(v, o, step, n, eps = 0) {
336
+ let mean = 0, norm = 0
337
+ for (let i = 0; i < n; i++) mean += v[o + i * step]
338
+ mean /= n
339
+ for (let i = 0; i < n; i++) { let d = v[o + i * step] -= mean; norm += d * d }
340
+ if (!(norm > 0)) return
341
+ norm = Math.sqrt(norm) + eps
342
+ for (let i = 0; i < n; i++) v[o + i * step] /= norm
343
+ }
344
+
345
+ // [1] sec. II: the frames where the clean speech is 40 dB under its loudest are dropped from both signals, the rest
346
+ // joined. Framing and join follow pystoi/utils.py remove_silent_frames: Hann frames of 256 at a hop of 128, frame k
347
+ // starting at k·128 < length - 256 (the last whole frame is left out, as there), the kept frames overlap-added.
348
+ function speech(x, y) {
349
+ let K = Math.max(0, Math.ceil((x.length - FRAME) / HOP)), e = new Float64Array(K), top = -Infinity, keep = []
350
+ for (let k = 0; k < K; k++) {
351
+ let s = 0
352
+ for (let i = 0; i < FRAME; i++) { let v = WIN[i] * x[k * HOP + i]; s += v * v }
353
+ e[k] = 20 * Math.log10(Math.sqrt(s) + EPS)
354
+ if (e[k] > top) top = e[k]
355
+ }
356
+ for (let k = 0; k < K; k++) if (top - RANGE - e[k] < 0) keep.push(k)
357
+ let n = keep.length && (keep.length - 1) * HOP + FRAME, xs = new Float64Array(n), ys = new Float64Array(n)
358
+ keep.forEach((k, j) => {
359
+ for (let i = 0; i < FRAME; i++) { xs[j * HOP + i] += WIN[i] * x[k * HOP + i]; ys[j * HOP + i] += WIN[i] * y[k * HOP + i] }
360
+ })
361
+ return [xs, ys]
362
+ }
363
+
364
+ // [1] eq. 1: the one-third octave band envelopes, band-major (band j's frames at j·M to j·M + M - 1), of the Hann
365
+ // frames of 256 at a hop of 128 zero-padded to 512, framed as pystoi/utils.py stft frames (the last whole one left out)
366
+ function envelopes(x) {
367
+ let M = Math.max(0, Math.ceil((x.length - FRAME) / HOP)), E = new Float64Array(BANDS * M), f = new Float64Array(NFFT)
368
+ for (let m = 0; m < M; m++) {
369
+ for (let i = 0; i < FRAME; i++) f[i] = WIN[i] * x[m * HOP + i]
370
+ let [re, im] = fft(f)
371
+ for (let j = 0; j < BANDS; j++) {
372
+ let s = 0
373
+ for (let k = EDGES[j]; k < EDGES[j + 1]; k++) s += re[k] * re[k] + im[k] * im[k]
374
+ E[j * M + m] = Math.sqrt(s)
375
+ }
376
+ }
377
+ return E
378
+ }
379
+
380
+ // To 10 kHz as pystoi/utils.py resample_oct does (its Octave-compatible filter, run by scipy.signal.resample_poly):
381
+ // up by p, a zero-phase Kaiser-windowed sinc lowpass at 1/(2·max(p, q)) of the upsampled rate with a transition a
382
+ // tenth of that and 60 dB of rejection, normalized to unit sum (times p), down by q; zeros beyond either end
383
+ let kernels = new Map()
384
+ function to10k(x, fs) {
385
+ if (fs === FS) return x
386
+ let g = gcd(FS, fs), p = FS / g, q = fs / g, h = kernel(p, q), half = (h.length - 1) / 2
387
+ let n = Math.ceil(x.length * p / q), y = new Float64Array(n)
388
+ for (let j = 0; j < n; j++) {
389
+ // y[j] = Σ h[t - i·p]·x[i], t = j·q + half: the filter centred on the output sample
390
+ let t = j * q + half, i = Math.max(0, Math.ceil((t - 2 * half) / p)), end = Math.min(x.length - 1, Math.floor(t / p)), s = 0
391
+ for (; i <= end; i++) s += h[t - i * p] * x[i]
392
+ y[j] = s
393
+ }
394
+ return y
395
+ }
396
+
397
+ function kernel(p, q) {
398
+ let key = p + ':' + q, h = kernels.get(key)
399
+ if (h) return h
400
+ let fc = 1 / (2 * Math.max(p, q)), L = Math.ceil((60 - 8) / (28.714 * (fc / 10))), beta = 0.1102 * (60 - 8.7), sum = 0
401
+ h = new Float64Array(2 * L + 1)
402
+ for (let i = 0; i <= 2 * L; i++) {
403
+ let t = i - L, a = Math.PI * 2 * fc * t
404
+ h[i] = i0(beta * Math.sqrt(1 - (t / L) ** 2)) * (t ? Math.sin(a) / a : 1)
405
+ sum += h[i]
406
+ }
407
+ for (let i = 0; i <= 2 * L; i++) h[i] *= p / sum
408
+ kernels.set(key, h)
409
+ return h
410
+ }
411
+
412
+ // modified Bessel function of the first kind, order 0 (its power series): the Kaiser window's
413
+ function i0(x) {
414
+ let s = 1, t = 1
415
+ for (let k = 1; t > 1e-17 * s; k++) { t *= (x / (2 * k)) ** 2; s += t }
416
+ return s
417
+ }
418
+
419
+ const gcd = (a, b) => b ? gcd(b, a % b) : a
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@audio/quality",
3
- "version": "1.0.1",
4
- "description": "Objective audio quality metrics — SNR, segmental SNR, log-spectral distance, spectral similarity, noise-reduction ratio, per-partial modulation depth",
3
+ "version": "1.1.0",
4
+ "description": "Objective audio quality metrics — SNR, segmental SNR, log-spectral distance, spectral similarity, noise-reduction ratio, per-partial modulation depth, STOI and ESTOI speech intelligibility",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "main": "index.js",
@@ -9,6 +9,9 @@
9
9
  ".": "./index.js",
10
10
  "./package.json": "./package.json"
11
11
  },
12
+ "scripts": {
13
+ "prepublishOnly": "node ../../../compile/tools/tested.js"
14
+ },
12
15
  "files": [
13
16
  "index.js",
14
17
  "index.d.ts"
@@ -24,6 +27,10 @@
24
27
  "snr",
25
28
  "log-spectral-distance",
26
29
  "lsd",
30
+ "stoi",
31
+ "estoi",
32
+ "intelligibility",
33
+ "speech",
27
34
  "evaluation"
28
35
  ],
29
36
  "license": "MIT",