@audio/stft 2.0.0 → 2.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
@@ -24,7 +24,28 @@ let tail = s.flush()
24
24
  stftAnalyse(input, (mag, phase, ctx) => { /* inspect */ }, { fs: 44100 })
25
25
  ```
26
26
 
27
- Also exports `wrapPhase`, `hannWindow` (periodic Hann, from [`window-function`](https://github.com/scijs/window-function)), `normFloor`, `PI2`.
27
+ A process may also edit `mag` and `phase` in place and return nothing.
28
+
29
+ **Complex bins.** With `complex: true`, `process(re, im, state, ctx)` gets the bins themselves and edits them in place (or returns `{ re, im }`): no polar round trip, the `sqrt`, `atan2`, `cos` and `sin` of every bin of every frame. `magnitude(re, im, out)` gives |X|, the expression the polar form's `mag` is, so a gain computed from it is the polar form's gain to the bit. With a Wiener-like gain from |X|, the complex stream takes 0.47 of the polar stream's time at N = 2048 and 0.46 at N = 512 (31 interleaved pairs, thread CPU time, Node 25, Apple M4 Max). Its samples are the polar form's but for a rare one a float32 step off: the round trip's rounding is about 1e-16 of a frame in float64 (none differed in 34.6 million samples compared, 48 kHz, N = 512 to 2048).
30
+
31
+ ```js
32
+ const mag = new Float64Array(1025) // noise: the noise power of each bin
33
+ const wiener = (re, im, state, ctx) => {
34
+ magnitude(re, im, mag)
35
+ for (let k = 0; k < re.length; k++) { let s = mag[k] ** 2 / noise[k], g = s / (1 + s); re[k] *= g; im[k] *= g }
36
+ }
37
+ let s = stftStream(wiener, { fs: 48000, frameSize: 2048, complex: true })
38
+ ```
39
+
40
+ **Real time, nothing allocated.** `write(chunk, out, length)` writes the samples now final into `out` from its start instead of returning a new array, and returns how many; `flush(out)` likewise: into a `Float32Array` and with a whole `hopSize`, the same bits as the arrays, call for call (a `Float64Array` takes each sample before its rounding to float32). `out` takes as many as it holds, the rest waits for the next call. `length`: the samples taken from the chunk's start, when the chunk is a longer array. `maxChunk` (default `frameSize`) is the longest chunk: the stream's memory is made for it when the stream is made, so a loop of such chunks allocates nothing (a longer chunk grows it once, and costs the engine a recompile: 12 MB on Node 25; frames of 16384 and up allocate 2 bytes a call on Node 20). A write gives at most `maxChunk + hopSize − 1` samples and a flush at most `frameSize − 1`: an `out` of the larger holds every call.
41
+
42
+ ```js
43
+ let s = stftStream(process, { fs: 48000, frameSize: 2048, hopSize: 512, maxChunk: 128 })
44
+ let out = new Float32Array(Math.max(128 + 512 - 1, 2048 - 1))
45
+ let n = s.write(block, out) // out[0..n): the samples now final
46
+ ```
47
+
48
+ Also exports `wrapPhase`, `hannWindow` (periodic Hann, from [`window-function`](https://github.com/scijs/window-function)), `normFloor`, `magnitude`, `PI2`.
28
49
 
29
50
  ## See also
30
51
 
package/index.d.ts CHANGED
@@ -1,4 +1,10 @@
1
- export interface StftOptions { frameSize?: number; hopSize?: number; fs?: number }
1
+ export interface StftOptions {
2
+ frameSize?: number; hopSize?: number; fs?: number
3
+ /** process(re, im, state, ctx) on the complex bins, edited in place: no polar round trip. */
4
+ complex?: boolean
5
+ /** The longest chunk write is given (default frameSize): the stream's memory is made for it up front, a longer chunk grows it once. */
6
+ maxChunk?: number
7
+ }
2
8
  export interface StftContext {
3
9
  hop: number; half: number; N: number; fs: number
4
10
  /** Radians per bin, 2π/N. */
@@ -7,17 +13,28 @@ export interface StftContext {
7
13
  pos: number
8
14
  }
9
15
  export interface Spectrum { mag: ArrayLike<number>; phase: ArrayLike<number> }
10
- /** State starts empty and persists for the duration of one batch/stream. */
11
- export type SpectralProcessor = (mag: Float64Array, phase: Float64Array, state: Record<string, unknown>, ctx: StftContext) => Spectrum
12
- export function stftBatch(data: ArrayLike<number>, process: SpectralProcessor, options?: StftOptions): Float32Array
13
- export function stftStream(process: SpectralProcessor, options?: StftOptions): {
16
+ /** State starts empty and persists for the duration of one batch/stream. Returns nothing when it edited mag and phase in place. */
17
+ export type SpectralProcessor = (mag: Float64Array, phase: Float64Array, state: Record<string, unknown>, ctx: StftContext) => Spectrum | void
18
+ /** With complex: the bins themselves, edited in place (nothing returned), or arrays of its own returned. */
19
+ export type ComplexProcessor = (re: Float64Array, im: Float64Array, state: Record<string, unknown>, ctx: StftContext) => { re: ArrayLike<number>; im: ArrayLike<number> } | void
20
+ export interface StftStream {
21
+ /** The samples now final, in a new array. */
14
22
  write(chunk: ArrayLike<number>): Float32Array
23
+ /** The samples now final into out from its start, as many as it holds (the rest waits for the next call): how many. length: the samples taken from the chunk's start. */
24
+ write(chunk: ArrayLike<number>, out: Float32Array | Float64Array, length?: number): number
15
25
  flush(): Float32Array
26
+ flush(out: Float32Array | Float64Array): number
16
27
  }
28
+ export function stftBatch(data: ArrayLike<number>, process: SpectralProcessor, options?: StftOptions & { complex?: false }): Float32Array
29
+ export function stftBatch(data: ArrayLike<number>, process: ComplexProcessor, options: StftOptions & { complex: true }): Float32Array
30
+ export function stftStream(process: SpectralProcessor, options?: StftOptions & { complex?: false }): StftStream
31
+ export function stftStream(process: ComplexProcessor, options: StftOptions & { complex: true }): StftStream
17
32
  /** Visits complete frames only; pos is the frame's sample offset. */
18
33
  export function stftAnalyse(data: ArrayLike<number>, visit: (mag: Float64Array, phase: Float64Array, pos: number) => void, options?: StftOptions): void
19
34
  export function wrapPhase(phase: number): number
20
35
  /** Returns a cached periodic Hann window. */
21
36
  export function hannWindow(length: number): Float64Array
22
37
  export function normFloor(win: ArrayLike<number>, hop: number): number
38
+ /** Each bin's |X| into out (a new array when omitted): the polar form's mag, to the bit. */
39
+ export function magnitude(re: ArrayLike<number>, im: ArrayLike<number>, out?: Float64Array): Float64Array
23
40
  export const PI2: number
package/index.js CHANGED
@@ -1,2 +1,2 @@
1
1
  export { stftBatch, stftStream, stftAnalyse, wrapPhase } from './stft.js'
2
- export { hannWindow, normFloor, PI2 } from './util.js'
2
+ export { hannWindow, normFloor, magnitude, PI2 } from './util.js'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audio/stft",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "description": "Canonical STFT — batch / stream / analyse with normalized Hann OLA; stream ≡ batch under any chunking",
@@ -47,7 +47,8 @@
47
47
  "url": "https://github.com/audiojs/stft/issues"
48
48
  },
49
49
  "scripts": {
50
- "test": "node test.js"
50
+ "test": "node test.js",
51
+ "prepublishOnly": "node ../compile/tools/tested.js"
51
52
  },
52
53
  "devDependencies": {
53
54
  "tst": "^9.4.0"
package/stft.js CHANGED
@@ -10,36 +10,51 @@
10
10
  // stftStream — write(chunk) / write() pull-based wrapper for real-time
11
11
 
12
12
  import { fft, ifft } from 'fourier-transform'
13
- import { hannWindow, makeStreamBufs, appendIn, growOut, compactIn, take, normFloor, PI2 } from './util.js'
13
+ import { hannWindow, makeStreamBufs, appendIn, appendZeros, growOut, compactIn, take, takeInto, normFloor, PI2 } from './util.js'
14
14
 
15
15
  export function wrapPhase(p) { return p - Math.floor(p / PI2 + 0.5) * PI2 } // floor(x + 0.5) rounds like Math.round here, several times faster in V8 (hot: per bin per frame)
16
16
 
17
- function frame(data, pos, win, half, process, state, ctx, sc) {
17
+ // One frame's samples: process(mag, phase, state, ctx) → { mag, phase }, or with `complex` process(re, im, state, ctx)
18
+ // on the complex bins, no polar round trip (sqrt, atan2, cos, sin a bin). Either edits its bins in place and returns
19
+ // nothing, or returns arrays of its own: nothing returned is nothing allocated a frame. The bins are the stream's own
20
+ // arrays, made once (a process may run fft or ifft itself: their internal views would be overwritten)
21
+ function frame(data, pos, win, half, process, state, ctx, sc, complex) {
18
22
  let N = win.length, f = sc.f
19
23
  // before the input, its mirror image (x[-k] = x[k], numpy's 'reflect'): frames that start early carry the
20
24
  // signal's own level and spectrum, so processes that learn from the first frames (a noise profile) learn the
21
25
  // signal, not silence
22
26
  for (let i = 0; i < N; i++) { let j = pos + i; f[i] = (data[j < 0 ? -j : j] || 0) * win[i] }
23
27
 
24
- let [re, im] = fft(f)
28
+ let re = sc.re, im = sc.im
29
+ fft(f, sc.spec)
30
+ if (complex) {
31
+ let r = process(re, im, state, ctx)
32
+ if (r) {
33
+ if (r.re !== re) for (let k = 0; k <= half; k++) re[k] = r.re[k]
34
+ if (r.im !== im) for (let k = 0; k <= half; k++) im[k] = r.im[k]
35
+ }
36
+ return ifft(re, im)
37
+ }
25
38
  let mag = sc.mag, phase = sc.phase
26
39
  for (let k = 0; k <= half; k++) {
27
40
  mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
28
41
  phase[k] = Math.atan2(im[k], re[k])
29
42
  }
30
43
 
31
- let r = process(mag, phase, state, ctx)
44
+ let r = process(mag, phase, state, ctx), m = r ? r.mag : mag, p = r ? r.phase : phase
32
45
  let r2 = sc.r2, i2 = sc.i2
33
46
  for (let k = 0; k <= half; k++) {
34
- r2[k] = r.mag[k] * Math.cos(r.phase[k])
35
- i2[k] = r.mag[k] * Math.sin(r.phase[k])
47
+ r2[k] = m[k] * Math.cos(p[k])
48
+ i2[k] = m[k] * Math.sin(p[k])
36
49
  }
37
50
  return ifft(r2, i2)
38
51
  }
39
52
 
40
53
  function scratch(N, half) {
54
+ let re = new Float64Array(half + 1), im = new Float64Array(half + 1)
41
55
  return {
42
56
  f: new Float64Array(N),
57
+ re, im, spec: [re, im], // fft's output pair, made once: an array a frame is an allocation a frame
43
58
  mag: new Float64Array(half + 1),
44
59
  phase: new Float64Array(half + 1),
45
60
  r2: new Float64Array(half + 1),
@@ -53,6 +68,7 @@ export function stftBatch(data, process, opts) {
53
68
  let half = N >> 1
54
69
  let win = hannWindow(N)
55
70
  let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
71
+ let complex = !!opts?.complex
56
72
 
57
73
  let outLen = data.length
58
74
  let out = new Float32Array(outLen)
@@ -68,7 +84,7 @@ export function stftBatch(data, process, opts) {
68
84
 
69
85
  while (pos < outLen) {
70
86
  ctx.pos = pos
71
- let sf = frame(data, pos, win, half, process, state, ctx, sc)
87
+ let sf = frame(data, pos, win, half, process, state, ctx, sc, complex)
72
88
  for (let i = Math.max(0, -pos); i < N && pos + i < outLen; i++) {
73
89
  out[pos + i] += sf[i] * win[i]
74
90
  norm[pos + i] += win[i] * win[i]
@@ -84,21 +100,34 @@ export function stftBatch(data, process, opts) {
84
100
  return out
85
101
  }
86
102
 
103
+ // The same number, a whole one as a small integer: a caller's 2 ** k or N / 4 is a heap number, and the stream's
104
+ // positions derived from it would sit in double fields, a number allocated where one reaches a builtin (each frame, on
105
+ // Node 20 and 22)
106
+ const whole = x => x === (x | 0) ? x | 0 : x
107
+
108
+ // write(chunk) returns the samples now final; write(chunk, out, length) writes them into out from its start instead,
109
+ // as many as it holds, and returns how many (the rest waits for the next call): with the stream's memory made here
110
+ // for chunks up to opts.maxChunk (a longer one grows it once), a real-time loop allocates nothing. length: the
111
+ // samples taken from the chunk's start. flush() and flush(out) likewise
87
112
  export function stftStream(process, opts) {
88
- let N = opts?.frameSize || 2048
89
- let hop = opts?.hopSize || (N >> 2)
113
+ let N = whole(opts?.frameSize || 2048)
114
+ let hop = whole(opts?.hopSize || (N >> 2))
90
115
  let half = N >> 1
91
116
  let win = hannWindow(N)
92
117
  let ctx = { hop, half, N, fs: opts?.fs || 44100, freqPerBin: PI2 / N }
93
118
  let state = {}, sc = scratch(N, half)
94
119
  let nf = normFloor(win, hop)
120
+ let complex = !!opts?.complex
95
121
 
96
122
  // the first frame starts N − hop before the input, as in stftBatch: the input buffer starts with those
97
123
  // N − hop samples, the input's mirror image (written once N − hop + 1 samples have come, frames wait for it),
98
124
  // and the output skips them; the grid stays on the hop, so the hold-back stays under a frame
99
- let P = N - hop, st = makeStreamBufs(N, nf)
125
+ let P = N - hop, st = makeStreamBufs(N, nf, opts?.maxChunk || N)
100
126
  st.il = st.oread = P
101
- let aPos = 0, flushed = false, fed = 0, sent = 0, mirrored = false
127
+ let aPos = 0, flushed = false, mirrored = false
128
+ // the samples fed and sent, in typed arrays: past V8's small integers (2^31, 12 hours at 48 kHz) a closure variable
129
+ // holding a count is a number allocated at each write
130
+ let fed = new Float64Array(1), sent = new Float64Array(1)
102
131
  ctx.pos = hop - N
103
132
 
104
133
  function mirror() {
@@ -107,9 +136,9 @@ export function stftStream(process, opts) {
107
136
  }
108
137
 
109
138
  function run() {
110
- if (!mirrored) { if (fed <= P && !flushed) return; mirror() }
139
+ if (!mirrored) { if (fed[0] <= P && !flushed) return; mirror() }
111
140
  while (aPos + N <= st.il) {
112
- let sf = frame(st.ib, aPos, win, half, process, state, ctx, sc)
141
+ let sf = frame(st.ib, aPos, win, half, process, state, ctx, sc, complex)
113
142
  ctx.pos += hop
114
143
  growOut(st, st.pos + N)
115
144
  let ob = st.ob, nb = st.nb, base = st.pos
@@ -125,22 +154,29 @@ export function stftStream(process, opts) {
125
154
  }
126
155
 
127
156
  return {
128
- write(chunk) {
129
- appendIn(st, chunk); fed += chunk.length; run()
157
+ write(chunk, out, length) {
158
+ let len = length ?? chunk.length
159
+ appendIn(st, chunk, len); fed[0] += len; run()
130
160
  // samples below pos are final: every later frame starts at pos or beyond, so
131
161
  // emitting them now bounds the hold-back at N − 1 (a frame must fill first)
132
- let out = take(st, st.pos)
133
- sent += out.length
134
- return out
162
+ if (out == null) { let o = take(st, st.pos); sent[0] += o.length; return o }
163
+ let n = takeInto(st, st.pos, out)
164
+ sent[0] += n
165
+ return n
135
166
  },
136
- flush() {
137
- if (!flushed) { if (!mirrored) mirror(); appendIn(st, new Float32Array(N)); flushed = true }
167
+ flush(out) {
168
+ if (!flushed) { if (!mirrored) mirror(); appendZeros(st, N); flushed = true }
138
169
  run()
139
170
  // the padding frames run past the input by up to a hop: stop where the input
140
171
  // stopped, so the stream's total length equals the batch's
141
- let out = take(st, st.pos).subarray(0, Math.max(0, fed - sent))
142
- sent += out.length
143
- return out
172
+ if (out == null) {
173
+ let o = take(st, st.pos).subarray(0, Math.max(0, fed[0] - sent[0]))
174
+ sent[0] += o.length
175
+ return o
176
+ }
177
+ let n = takeInto(st, st.oread + Math.max(0, fed[0] - sent[0]), out)
178
+ sent[0] += n
179
+ return n
144
180
  }
145
181
  }
146
182
  }
package/util.js CHANGED
@@ -1,4 +1,4 @@
1
- // Internal — Hann window + stream ring buffers + OLA normalization.
1
+ // Internal — Hann window + stream ring buffers + OLA normalization; |X| of complex bins.
2
2
 
3
3
  import hann from 'window-function/hann'
4
4
 
@@ -16,22 +16,35 @@ export function hannWindow(N) {
16
16
  return w
17
17
  }
18
18
 
19
- export function makeStreamBufs(N, nf = 0) {
19
+ // Sized for chunks up to maxChunk, so a write never grows them: the input kept is under 3N before a chunk (frames
20
+ // wait for N, the buffer moves down past 2N), and the output from the last sample taken (moved down past 8N) reaches
21
+ // a chunk's frames plus one frame past that; a flush adds N. A longer chunk grows them once
22
+ export function makeStreamBufs(N, nf = 0, maxChunk = N) {
23
+ let L = Math.max(N, maxChunk)
20
24
  return {
21
25
  N, nf,
22
- ib: new Float32Array(N * 4), il: 0,
23
- ob: new Float32Array(N * 8), nb: new Float32Array(N * 8),
26
+ ib: new Float32Array(3 * N + L), il: 0,
27
+ ob: new Float32Array(9 * N + L), nb: new Float32Array(9 * N + L),
24
28
  pos: 0, oread: 0, hi: 0
25
29
  }
26
30
  }
27
31
 
28
- export function appendIn(st, chunk) {
29
- let need = st.il + chunk.length
32
+ // `len` samples of chunk (all of it by default) after the input
33
+ export function appendIn(st, chunk, len = chunk.length) {
34
+ let need = st.il + len
30
35
  if (need > st.ib.length) {
31
36
  let b = new Float32Array(Math.max(need * 2, st.ib.length * 2))
32
37
  b.set(st.ib.subarray(0, st.il)); st.ib = b
33
38
  }
34
- st.ib.set(chunk, st.il); st.il += chunk.length
39
+ if (len === chunk.length) st.ib.set(chunk, st.il)
40
+ else for (let i = 0; i < len; i++) st.ib[st.il + i] = chunk[i] // a loop: a subarray to set from is an allocation
41
+ st.il += len
42
+ }
43
+
44
+ // n zeros after the input (a flush's padding), in place of a chunk of them made for it
45
+ export function appendZeros(st, n) {
46
+ if (st.il + n > st.ib.length) appendIn(st, new Float32Array(n))
47
+ else { st.ib.fill(0, st.il, st.il + n); st.il += n }
35
48
  }
36
49
 
37
50
  export function growOut(st, need) {
@@ -46,11 +59,24 @@ export function compactIn(st, trim) {
46
59
  st.ib.copyWithin(0, trim, st.il); st.il -= trim
47
60
  }
48
61
 
62
+ // The final samples up to upTo, in a new array
49
63
  export function take(st, upTo) {
50
64
  upTo = Math.min(upTo, st.pos)
51
65
  if (upTo <= st.oread) return new Float32Array(0)
52
- let len = Math.floor(upTo - st.oread)
53
- let out = new Float32Array(len)
66
+ let out = new Float32Array(Math.floor(upTo - st.oread))
67
+ read(st, out, out.length)
68
+ return out
69
+ }
70
+
71
+ // The final samples up to upTo into out from its start, as many as it holds: how many (the rest waits for the next)
72
+ export function takeInto(st, upTo, out) {
73
+ upTo = Math.min(upTo, st.pos)
74
+ let len = upTo > st.oread ? Math.min(Math.floor(upTo - st.oread), out.length) : 0
75
+ read(st, out, len)
76
+ return len
77
+ }
78
+
79
+ function read(st, out, len) {
54
80
  for (let i = 0; i < len; i++) {
55
81
  let j = st.oread + i, n = st.nf > 0 ? Math.max(st.nb[j], st.nf) : st.nb[j]
56
82
  out[i] = n > 1e-8 ? st.ob[j] / n : 0
@@ -63,6 +89,12 @@ export function take(st, upTo) {
63
89
  st.pos -= st.oread; st.hi = Math.max(0, st.hi - st.oread); st.oread = 0
64
90
  st.ob.fill(0, st.hi); st.nb.fill(0, st.hi)
65
91
  }
92
+ }
93
+
94
+ // Each bin's magnitude |X| into out (a new array when omitted): the expression the polar form's mag is, so a gain
95
+ // computed from it is the polar form's gain to the bit
96
+ export function magnitude(re, im, out = new Float64Array(re.length)) {
97
+ for (let k = 0; k < re.length; k++) out[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k])
66
98
  return out
67
99
  }
68
100