@audio/spectral-pvoc 1.0.0 → 1.1.0

package/README.md

@@ -13,6 +13,8 @@ import { findPeaks, scatterLocked, lockPhase, makeFrameRatio } from '@audio/spec
 | `scatterGated(mag, phase, prevPhase, ratio, ctx, …scratch)` | Bernsee/SMB peak-gated bin scatter — pitch shift by ratio, RMS-preserving collisions |
 | `scatterLocked(mag, phase, prevPhase, reset, peaks, ratio, ctx, …scratch)` | Laroche-Dolson rigid-ROI scatter — phase-coherent shift |
 | `lockPhase(phase, propPhase, mag, half)` | lock non-peak bins to their peak's rotation (time-stretch coherence) |
+| `lockMap(mag, half, owner)` | which peak each bin locks to (−1: free) — the regions `lockPhase` uses |
+| `lockState(half)` / `lockAdvance(re, im, st, reset, anaHop, synHop, freqPerBin, half)` | the phase-locked vocoder frame on complex bins: locked bins rotate by one complex multiply, only free bins take trig |
 | `findPeaks(mag, half)` / `nearestPeak(peaks, k)` | local-maxima peak indices + nearest lookup |
 | `makeFrameRatio(ratio)` | scalar or time-varying ratio → per-frame resolver |
 | `wrapPhase(p)` / `WIN_GAIN` / `PI2` | phase wrap, Hann OLA gain constant |

package/index.d.ts

@@ -0,0 +1,109 @@
+/** Phase-vocoder engine — frame-level primitives over STFT magnitude/phase arrays. Pure math, no defaults. */
+
+/** Per-frame geometry the scatter/lock primitives read from. */
+export interface PvocCtx {
+  /** Nyquist bin index (frameSize / 2) */
+  half: number
+  /** hop size, samples */
+  hop: number
+  /** Hz per FFT bin (fs / N) */
+  freqPerBin: number
+  /** analysis window / FFT size */
+  N: number
+}
+
+export const PI2: number
+/** rms(w)/mean(w) for the engine's periodic Hann — energy-preserving OLA gain for scatterGated. */
+export const WIN_GAIN: number
+
+/** Wrap a phase (radians) into (−π, π]. */
+export function wrapPhase(p: number): number
+
+/** Local magnitude maxima of `mag[0..half]` above a fraction of the frame's peak. Returns bin indices, ascending. */
+export function findPeaks(mag: Float32Array | Float64Array, half: number): number[]
+
+/** Binary-search the peak (from `findPeaks`) nearest bin `k`. Returns −1 if `peaks` is empty. */
+export function nearestPeak(peaks: number[], k: number): number
+
+/**
+ * Bernsee/SMB peak-gated bin scatter — pitch shift by `ratio`, RMS-preserving collisions.
+ * `newMag`/`newFreq`/`peakMag` are caller-owned scratch sized `half+1`, zero-filled before the call.
+ * Writes into `newMag`/`newFreq` in place.
+ */
+export function scatterGated(
+  mag: Float32Array | Float64Array,
+  phase: Float32Array | Float64Array,
+  prevPhase: Float32Array | Float64Array | null,
+  ratio: number,
+  ctx: PvocCtx,
+  newMag: Float64Array,
+  newFreq: Float64Array,
+  peakMag: Float64Array,
+): void
+
+/**
+ * Laroche-Dolson rigid-ROI peak-locked bin scatter — phase-coherent shift by `ratio`.
+ * `syn` is the caller-owned running frame-center phase accumulator indexed by source bin (NaN means untracked), mutated in place.
+ * `newMag`/`newPhase`/`peakMag` are caller-owned scratch sized `half+1`; `peakDest`/`peakSynPhase` sized `peaks.length`. All zero-filled before the call.
+ */
+export function scatterLocked(
+  mag: Float32Array | Float64Array,
+  phase: Float32Array | Float64Array,
+  prevPhase: Float32Array | Float64Array | null,
+  reset: boolean,
+  peaks: number[],
+  ratio: number,
+  ctx: PvocCtx,
+  syn: Float64Array,
+  newMag: Float64Array,
+  newPhase: Float64Array,
+  peakDest: Int32Array,
+  peakSynPhase: Float64Array,
+  peakMag: Float64Array,
+): void
+
+/** Scalar or time-varying ratio → per-frame resolver. */
+export function makeFrameRatio(ratio: number | ((t: number) => number)): {
+  /** ratio at t = 0 */
+  scalar: number
+  /** ratio at a given frame position */
+  at(frameStart: number, sampleRate: number): number
+}
+
+/** Lock non-peak bin phases to their nearest peak's rotation, in place on `propPhase` (time-stretch coherence). */
+export function lockPhase(
+  phase: Float32Array | Float64Array,
+  propPhase: Float32Array | Float64Array,
+  mag: Float32Array | Float64Array,
+  half: number,
+): void
+
+/**
+ * Which peak each bin locks to, into `owner` (sized ≥ `half+1`): the peak whose rotation bin k takes, or −1 for a
+ * free bin (a peak itself, or under 3% of its peak's magnitude). The regions `lockPhase` uses; returns `owner`.
+ */
+export function lockMap(mag: Float32Array | Float64Array, half: number, owner: Int32Array): Int32Array
+
+/** Complex-domain locked-vocoder state over `half+1` bins; the caller fills `mag` with each frame's magnitudes. */
+export interface LockState {
+  mag: Float64Array
+  owner: Int32Array
+  xr: Float64Array
+  xi: Float64Array
+  xm: Float64Array
+  ur: Float64Array
+  ui: Float64Array
+}
+
+/** State for `lockAdvance` over `half+1` bins. */
+export function lockState(half: number): LockState
+
+/**
+ * One phase-locked vocoder frame on complex bins, in place: `re`/`im` hold the analysis bins, then the synthesis bins
+ * (`st.mag` = this frame's magnitudes). `reset` restarts synthesis phases at the analysis phases (first frame,
+ * transient); otherwise free bins advance at their instantaneous frequency and locked bins take their peak's rotation.
+ */
+export function lockAdvance(
+  re: Float64Array, im: Float64Array, st: LockState, reset: boolean,
+  anaHop: number, synHop: number, freqPerBin: number, half: number,
+): void

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@audio/spectral-pvoc",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Phase-vocoder engine — peak-gated and peak-locked spectral bin scatter (Bernsee, Laroche-Dolson), phase locking, peak finding; powers @audio/shift-pvoc* and @audio/stretch-pvoc*",
   "type": "module",
   "sideEffects": false,
   "main": "pvoc.js",
   "exports": {
-    ".": "./pvoc.js",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./pvoc.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
-    "pvoc.js"
+    "pvoc.js",
+    "index.d.ts"
   ],
   "dependencies": {},
   "keywords": [
@@ -30,8 +34,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "types": "index.d.ts",
   "repository": {
     "directory": "packages/spectral-pvoc"
   },
-  "homepage": "https://github.com/audiojs/spectral/tree/main/packages/spectral-pvoc"
+  "homepage": "https://github.com/audiojs/spectral/tree/main/packages/spectral-pvoc",
+  "funding": "https://github.com/sponsors/audiojs"
 }

package/pvoc.js

@@ -6,12 +6,14 @@
 //   - scatterGated: Bernsee/SMB peak-gated bin scatter (pitch shift by ratio)
 //   - scatterLocked: Laroche-Dolson rigid-ROI peak-locked scatter (phase coherent)
 //   - lockPhase: lock non-peak bin phases to their nearest peak's rotation (time stretch)
+//   - lockMap: which peak each bin locks to — the same regions, for complex-domain locking
+//   - lockState / lockAdvance: the phase-locked vocoder step on complex bins (no polar round trip)
 //   - findPeaks / nearestPeak / makeFrameRatio / wrapPhase: the supporting primitives
 
 export const PI2 = Math.PI * 2
 
 export function wrapPhase(p) {
-  return p - Math.round(p / PI2) * PI2
+  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)
 }
 
 // First-order local magnitude peaks above a fraction of the frame's peak.
@@ -122,11 +124,18 @@ function lobeGain(dw, N) {
 // same RMS-preserving collision policy as `scatterGated`.
 // `reset` skips phase-derivative estimation (first frame, or a caller-detected phase
 // discontinuity such as a transient) and uses the analysis phase directly instead of
-// integrating. `syn` is the caller-owned running per-bin phase accumulator (persists across
-// frames). `newMag`/`newPhase`/`peakMag` are caller-owned scratch sized `half+1`, zero-filled
+// integrating. `syn` holds frame-center phases indexed by SOURCE bin, including each
+// peak's neighbours so moving peaks inherit coherent history. NaN marks untracked bins.
+// `newMag`/`newPhase`/`peakMag` are caller-owned scratch sized `half+1`, zero-filled
 // by the caller; `peakDest`/`peakSynPhase` are caller-owned scratch sized `peaks.length`.
 export function scatterLocked(mag, phase, prevPhase, reset, peaks, ratio, ctx, syn, newMag, newPhase, peakDest, peakSynPhase, peakMag) {
   let { half, hop, freqPerBin } = ctx
+  // Without a resolved partial there is no pitch to move. Preserve DC and
+  // short boundary frames rather than dropping their energy; re-seed later peaks.
+  if (!peaks.length) {
+    for (let k = 0; k <= half; k++) { newMag[k] = mag[k]; newPhase[k] = phase[k]; syn[k] = NaN }
+    return
+  }
   if (_boost.length <= half) _boost = new Float64Array(half + 1)
   for (let i = 0; i < peaks.length; i++) {
     let k = peaks[i]
@@ -142,10 +151,11 @@ export function scatterLocked(mag, phase, prevPhase, reset, peaks, ratio, ctx, s
     // within ±half a bin — where the scalloping model below is accurate.
     let destBin = k + Math.round((shifted - trueFreq) / freqPerBin)
     if (destBin < 0 || destBin > half) { peakDest[i] = -1; continue }
-    let newSyn = reset ? phase[k] : wrapPhase(syn[destBin] + shifted * hop)
+    // Center-referenced phase survives destination-bin changes (each bin adds π
+    // at N/2). Read all previous phases before updating source-bin history below.
+    let newSyn = reset || !Number.isFinite(syn[k]) ? phase[k] + k * Math.PI : wrapPhase(syn[k] + shifted * hop)
     peakDest[i] = destBin
-    peakSynPhase[i] = newSyn
-    syn[destBin] = newSyn
+    peakSynPhase[i] = newSyn - destBin * Math.PI
     let r = lobeGain(shifted - (trueFreq + (destBin - k) * freqPerBin), ctx.N)
     _boost[i] = 1 / (r * r)
   }
@@ -157,12 +167,13 @@ export function scatterLocked(mag, phase, prevPhase, reset, peaks, ratio, ctx, s
   let eIn = 0, eOut = 0
   for (let k = 0; k <= half; k++) {
     let pi = nearestPeak(peaks, k)
-    if (pi < 0) continue
+    if (pi < 0) { syn[k] = NaN; continue }
     let destBin = peakDest[pi]
-    if (destBin < 0) continue
+    if (destBin < 0) { syn[k] = NaN; continue }
     let e = mag[k] * mag[k]
     eIn += e
     let pk = peaks[pi]
+    syn[k] = wrapPhase(peakSynPhase[pi] + destBin * Math.PI + (phase[k] - phase[pk]) + (k - pk) * Math.PI)
     let dest = destBin + (k - pk)
     if (dest < 0 || dest > half) continue
     eOut += e
@@ -236,24 +247,83 @@ function peakMask(mag, half) {
   return peaks
 }
 
-// Lock non-peak bin phases to nearest peak's rotation, in place on `propPhase`.
+// Which bins ride which peak: `owner[k]` = the peak whose rotation bin k takes (its region of
+// influence reaches halfway to the neighbouring peaks), or -1 for a free bin — a peak itself, or a
+// bin under 3% of its peak's magnitude, which keeps its own phase advance. Returns `owner`.
 let _peakBins = new Int32Array(0)
-export function lockPhase(phase, propPhase, mag, half) {
+export function lockMap(mag, half, owner) {
   let peaks = peakMask(mag, half)
   if (_peakBins.length < half + 1) _peakBins = new Int32Array(half + 1)
   let peakBins = _peakBins, nBins = 0
   for (let k = 0; k <= half; k++) if (peaks[k]) peakBins[nBins++] = k
-  if (!nBins) return
-
+  owner.fill(-1, 0, half + 1)
   for (let i = 0; i < nBins; i++) {
     let pk = peakBins[i]
     let start = i === 0 ? 0 : Math.floor((peakBins[i - 1] + pk) * 0.5) + 1
     let end = i === nBins - 1 ? half : Math.floor((pk + peakBins[i + 1]) * 0.5)
-    let delta = propPhase[pk] - phase[pk]
     let lockFloor = Math.max(1e-10, mag[pk] * 0.03)
-    for (let k = start; k <= end; k++) {
-      if (k === pk || mag[k] < lockFloor) continue
-      propPhase[k] = phase[k] + delta
+    for (let k = start; k <= end; k++) if (k !== pk && !(mag[k] < lockFloor)) owner[k] = pk
+  }
+  return owner
+}
+
+// Lock non-peak bin phases to nearest peak's rotation, in place on `propPhase`.
+let _owner = new Int32Array(0)
+export function lockPhase(phase, propPhase, mag, half) {
+  if (_owner.length < half + 1) _owner = new Int32Array(half + 1)
+  let owner = lockMap(mag, half, _owner)
+  for (let k = 0; k <= half; k++) {
+    let pk = owner[k]
+    if (pk >= 0) propPhase[k] = phase[k] + (propPhase[pk] - phase[pk])
+  }
+}
+
+// ── Complex-domain phase locking ──
+// The propagate-then-lockPhase vocoder step on complex bins (pair with fourier-transform/stft's `complex` frames).
+// A bin riding a peak takes the peak's rotation R = Y(p)·conj(X(p))/|X(p)|², Y(k) = X(k)·R: one complex multiply,
+// the identity locking of Laroche & Dolson. Only free bins — the peaks, and bins too quiet to lock — advance at
+// their instantaneous frequency, one atan2 and one sin/cos each. State keeps unit synthesis phasors and the previous
+// analysis bins, so no bin needs its phase as an angle.
+
+/** Frame-to-frame state over half+1 bins: `mag` (the caller fills this frame's magnitudes), the lock map, the
+ *  previous analysis bins and magnitudes, the unit synthesis phasors. */
+export function lockState(half) {
+  let n = half + 1, f = () => new Float64Array(n)
+  return { mag: f(), owner: new Int32Array(n), xr: f(), xi: f(), xm: f(), ur: f(), ui: f() }
+}
+
+/** One vocoder frame in place: `re`/`im` hold the analysis bins, then the synthesis bins. `reset` (first frame, a
+ *  transient) restarts each bin's synthesis phase at its analysis phase; otherwise free bins advance by their
+ *  instantaneous frequency over the hops and locked bins take their peak's rotation. */
+export function lockAdvance(re, im, st, reset, anaHop, synHop, freqPerBin, half) {
+  let { mag, owner, xr, xi, xm, ur, ui } = st, n = half + 1
+  if (reset) for (let k = 0; k < n; k++) {
+    let m = mag[k]
+    if (m) { ur[k] = re[k] / m; ui[k] = im[k] / m; continue }
+    let a = Math.atan2(im[k], re[k])   // a zero bin: the direction its zeros' signs give atan2
+    ur[k] = Math.cos(a); ui[k] = Math.sin(a)
+  } else {
+    lockMap(mag, half, owner)
+    for (let k = 0; k < n; k++) {
+      if (owner[k] >= 0) continue
+      // phase advance since the previous frame, arg(X·conj(Xprev)); a zero bin has no product angle: its own angles
+      let d = mag[k] && xm[k] ? Math.atan2(im[k] * xr[k] - re[k] * xi[k], re[k] * xr[k] + im[k] * xi[k]) : Math.atan2(im[k], re[k]) - Math.atan2(xi[k], xr[k])
+      let dp = wrapPhase(d - k * freqPerBin * anaHop)
+      let a = (k * freqPerBin + dp / anaHop) * synHop, c = Math.cos(a), s = Math.sin(a), u = ur[k], v = ui[k]
+      ur[k] = u * c - v * s
+      ui[k] = u * s + v * c
     }
+    for (let k = 0, p = -1, rr = 0, ri = 0; k < n; k++) {
+      let pk = owner[k]
+      if (pk < 0) continue
+      if (pk !== p) { p = pk; let m = mag[p]; rr = (ur[p] * re[p] + ui[p] * im[p]) / m; ri = (ui[p] * re[p] - ur[p] * im[p]) / m }
+      let q = 1 / mag[k]
+      ur[k] = (re[k] * rr - im[k] * ri) * q
+      ui[k] = (re[k] * ri + im[k] * rr) * q
+    }
+  }
+  for (let k = 0; k < n; k++) {
+    xr[k] = re[k]; xi[k] = im[k]; xm[k] = mag[k]
+    re[k] = mag[k] * ur[k]; im[k] = mag[k] * ui[k]
   }
 }