@audio/stft 1.0.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 ADDED
@@ -0,0 +1,5 @@
1
+ # @audio/stft
2
+
3
+ > Shared STFT — batch / stream / analyse, one canonical implementation for all @audio packages
4
+
5
+ Planned — not implemented yet. See the umbrella README for status and sources.
package/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export { stftBatch, stftStream, stftAnalyse, wrapPhase } from './stft.js'
2
+ export { hannWindow, normFloor, PI2 } from './util.js'
package/package.json ADDED
@@ -0,0 +1,36 @@
1
+ {
2
+ "name": "@audio/stft",
3
+ "version": "1.0.0",
4
+ "type": "module",
5
+ "sideEffects": false,
6
+ "description": "Canonical STFT \u2014 batch / stream / analyse with normalized Hann OLA; stream \u2261 batch under any chunking",
7
+ "main": "index.js",
8
+ "exports": {
9
+ ".": "./index.js",
10
+ "./package.json": "./package.json"
11
+ },
12
+ "files": [
13
+ "index.js",
14
+ "stft.js",
15
+ "util.js"
16
+ ],
17
+ "dependencies": {
18
+ "fourier-transform": "^2.3.0"
19
+ },
20
+ "keywords": [
21
+ "audio",
22
+ "dsp",
23
+ "stft",
24
+ "fft",
25
+ "overlap-add",
26
+ "spectral"
27
+ ],
28
+ "license": "MIT",
29
+ "author": "Dmitry Iv. <dfcreative@gmail.com>",
30
+ "engines": {
31
+ "node": ">=18"
32
+ },
33
+ "publishConfig": {
34
+ "access": "public"
35
+ }
36
+ }
package/stft.js ADDED
@@ -0,0 +1,136 @@
1
+ // One canonical STFT for the @audio ecosystem — batch / stream / analyse.
2
+ // process(mag, phase, state, ctx) → { mag, phase } per frame; Hann analysis+synthesis
3
+ // windows, correctly normalized overlap-add, stream ≡ batch under any chunking.
4
+ // Extracted verbatim from @audio/denoise-core (differential-tested there since wave 1).
5
+ //
6
+ // Two flavours:
7
+ // stftBatch — process whole signal, return Float32Array
8
+ // stftStream — write(chunk) / write() pull-based wrapper for real-time
9
+
10
+ import { fft, ifft } from 'fourier-transform'
11
+ import { hannWindow, makeStreamBufs, appendIn, growOut, compactIn, take, normFloor, PI2 } from './util.js'
12
+
13
+ export function wrapPhase(p) { return p - Math.round(p / PI2) * PI2 }
14
+
15
+ function frame(data, pos, win, half, process, state, ctx, sc) {
16
+ let N = win.length, f = sc.f
17
+ for (let i = 0; i < N; i++) f[i] = (data[pos + i] || 0) * win[i]
18
+
19
+ let [re, im] = fft(f)
20
+ let mag = sc.mag, phase = sc.phase
21
+ for (let k = 0; k <= half; k++) {
22
+ mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
23
+ phase[k] = Math.atan2(im[k], re[k])
24
+ }
25
+
26
+ let r = process(mag, phase, state, ctx)
27
+ let r2 = sc.r2, i2 = sc.i2
28
+ for (let k = 0; k <= half; k++) {
29
+ r2[k] = r.mag[k] * Math.cos(r.phase[k])
30
+ i2[k] = r.mag[k] * Math.sin(r.phase[k])
31
+ }
32
+ return ifft(r2, i2)
33
+ }
34
+
35
+ function scratch(N, half) {
36
+ return {
37
+ f: new Float64Array(N),
38
+ mag: new Float64Array(half + 1),
39
+ phase: new Float64Array(half + 1),
40
+ r2: new Float64Array(half + 1),
41
+ i2: new Float64Array(half + 1)
42
+ }
43
+ }
44
+
45
+ export function stftBatch(data, process, opts) {
46
+ let N = opts?.frameSize || 2048
47
+ let hop = opts?.hopSize || (N >> 2)
48
+ let half = N >> 1
49
+ let win = hannWindow(N)
50
+ let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
51
+
52
+ let outLen = data.length
53
+ let out = new Float32Array(outLen)
54
+ let norm = new Float32Array(outLen)
55
+ let state = {}
56
+ let sc = scratch(N, half)
57
+ let pos = 0
58
+
59
+ while (pos + N <= outLen + hop) {
60
+ let sf = frame(data, pos, win, half, process, state, ctx, sc)
61
+ for (let i = 0; i < N && pos + i < outLen; i++) {
62
+ out[pos + i] += sf[i] * win[i]
63
+ norm[pos + i] += win[i] * win[i]
64
+ }
65
+ pos += hop
66
+ }
67
+
68
+ let nf = normFloor(win, hop)
69
+ for (let i = 0; i < outLen; i++) {
70
+ let n = Math.max(norm[i], nf)
71
+ if (n > 1e-8) out[i] /= n
72
+ }
73
+ return out
74
+ }
75
+
76
+ export function stftStream(process, opts) {
77
+ let N = opts?.frameSize || 2048
78
+ let hop = opts?.hopSize || (N >> 2)
79
+ let half = N >> 1
80
+ let win = hannWindow(N)
81
+ let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
82
+ let state = {}, sc = scratch(N, half)
83
+ let nf = normFloor(win, hop)
84
+
85
+ let st = makeStreamBufs(N, nf)
86
+ let aPos = 0, flushed = false
87
+
88
+ function run() {
89
+ while (aPos + N <= st.il) {
90
+ let sf = frame(st.ib, aPos, win, half, process, state, ctx, sc)
91
+ growOut(st, st.pos + N)
92
+ let ob = st.ob, nb = st.nb, base = st.pos
93
+ for (let i = 0; i < N; i++) {
94
+ ob[base + i] += sf[i] * win[i]
95
+ nb[base + i] += win[i] * win[i]
96
+ }
97
+ st.hi = Math.max(st.hi, st.pos + N)
98
+ aPos += hop
99
+ st.pos += hop
100
+ }
101
+ if (aPos > N * 2) { compactIn(st, aPos - N); aPos -= aPos - N }
102
+ }
103
+
104
+ return {
105
+ write(chunk) {
106
+ appendIn(st, chunk); run()
107
+ return take(st, Math.max(0, st.pos - N + hop))
108
+ },
109
+ flush() {
110
+ if (!flushed) { appendIn(st, new Float32Array(N)); flushed = true }
111
+ run()
112
+ return take(st, st.pos)
113
+ }
114
+ }
115
+ }
116
+
117
+ // Analysis-only sweep — visit every frame's magnitude+phase but produce no output.
118
+ // Used by VAD, noise-profile estimators, dereverb late-tail estimation.
119
+ export function stftAnalyse(data, visit, opts) {
120
+ let N = opts?.frameSize || 2048
121
+ let hop = opts?.hopSize || (N >> 2)
122
+ let half = N >> 1
123
+ let win = hannWindow(N)
124
+ let f = new Float64Array(N)
125
+ let mag = new Float64Array(half + 1), phase = new Float64Array(half + 1)
126
+
127
+ for (let pos = 0; pos + N <= data.length; pos += hop) {
128
+ for (let i = 0; i < N; i++) f[i] = data[pos + i] * win[i]
129
+ let [re, im] = fft(f)
130
+ for (let k = 0; k <= half; k++) {
131
+ mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
132
+ phase[k] = Math.atan2(im[k], re[k])
133
+ }
134
+ visit(mag, phase, pos)
135
+ }
136
+ }
package/util.js ADDED
@@ -0,0 +1,75 @@
1
+ // Internal — Hann window + stream ring buffers + OLA normalization.
2
+ // Canonical source extracted from @audio/denoise-core (the ecosystem original).
3
+
4
+ export const PI2 = Math.PI * 2
5
+
6
+
7
+ let _hannCache = new Map()
8
+ export function hannWindow(N) {
9
+ let w = _hannCache.get(N)
10
+ if (w) return w
11
+ w = new Float64Array(N)
12
+ for (let i = 0; i < N; i++) w[i] = 0.5 * (1 - Math.cos(PI2 * i / N))
13
+ _hannCache.set(N, w)
14
+ return w
15
+ }
16
+
17
+ export function makeStreamBufs(N, nf = 0) {
18
+ return {
19
+ N, nf,
20
+ ib: new Float32Array(N * 4), il: 0,
21
+ ob: new Float32Array(N * 8), nb: new Float32Array(N * 8),
22
+ pos: 0, oread: 0, hi: 0
23
+ }
24
+ }
25
+
26
+ export function appendIn(st, chunk) {
27
+ let need = st.il + chunk.length
28
+ if (need > st.ib.length) {
29
+ let b = new Float32Array(Math.max(need * 2, st.ib.length * 2))
30
+ b.set(st.ib.subarray(0, st.il)); st.ib = b
31
+ }
32
+ st.ib.set(chunk, st.il); st.il += chunk.length
33
+ }
34
+
35
+ export function growOut(st, need) {
36
+ if (need <= st.ob.length) return
37
+ let len = Math.max(need * 2, st.ob.length * 2)
38
+ let o = new Float32Array(len), n = new Float32Array(len)
39
+ o.set(st.ob); n.set(st.nb); st.ob = o; st.nb = n
40
+ }
41
+
42
+ export function compactIn(st, trim) {
43
+ if (trim <= 0) return
44
+ st.ib.copyWithin(0, trim, st.il); st.il -= trim
45
+ }
46
+
47
+ export function take(st, upTo) {
48
+ upTo = Math.min(upTo, st.pos)
49
+ if (upTo <= st.oread) return new Float32Array(0)
50
+ let len = Math.floor(upTo - st.oread)
51
+ let out = new Float32Array(len)
52
+ for (let i = 0; i < len; i++) {
53
+ let j = st.oread + i, n = st.nf > 0 ? Math.max(st.nb[j], st.nf) : st.nb[j]
54
+ out[i] = n > 1e-8 ? st.ob[j] / n : 0
55
+ }
56
+ st.oread += len
57
+ if (st.oread > st.N * 8) {
58
+ // shift left; zero only past the high-water mark — frames extend N−hop beyond
59
+ // pos, so zeroing from pos would erase the last frame's partial overlap-add tail
60
+ st.ob.copyWithin(0, st.oread); st.nb.copyWithin(0, st.oread)
61
+ st.pos -= st.oread; st.hi = Math.max(0, st.hi - st.oread); st.oread = 0
62
+ st.ob.fill(0, st.hi); st.nb.fill(0, st.hi)
63
+ }
64
+ return out
65
+ }
66
+
67
+ export function normFloor(win, hop) {
68
+ let N = win.length, min = Infinity
69
+ for (let i = 0; i < hop; i++) {
70
+ let s = 0
71
+ for (let j = i; j < N; j += hop) s += win[j] * win[j]
72
+ if (s > 0 && s < min) min = s
73
+ }
74
+ return min === Infinity ? 0 : min
75
+ }