@audio/stretch-pvoc-lock 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) Dmitry Iv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This work is offered under the Krishnized License (https://github.com/krishnized/license).

package/README.md

@@ -0,0 +1,23 @@
+# @audio/stretch-pvoc-lock
+
+Phase-locked vocoder (Laroche & Dolson, 1999). After propagating phases, locks non-peak bins to their nearest spectral peak's rotation — restores harmonic phase coherence and eliminates the phasiness of plain phase vocoder.
+
+```js
+import pvocLock from '@audio/stretch-pvoc-lock'
+let out = pvocLock(data, { factor: 2 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT size (power of 2) |
+| `hopSize` | `frameSize/4` | Hop between frames |
+
+**Use when:** general music — tonal/ambient material.<br>
+**Not for:** percussive material where attacks must stay sharp — use [`@audio/stretch-transient`](../stretch-transient).
+
+Part of [`@audio/stretch`](../..).
+
+## License
+
+[MIT](./LICENSE) · [ॐ](https://github.com/krishnized/license/)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@audio/stretch-pvoc-lock",
+  "version": "1.0.0",
+  "description": "Phase-locked vocoder (Laroche & Dolson 1999) — eliminates phasiness of plain pvoc",
+  "type": "module",
+  "sideEffects": false,
+  "main": "pvoc-lock.js",
+  "types": "pvoc-lock.d.ts",
+  "exports": {
+    ".": "./pvoc-lock.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "pvoc-lock.js",
+    "pvoc-lock.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@audio/stretch-core": "^1.0.0",
+    "fourier-transform": "^2.3.0"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "time-stretch",
+    "phase-vocoder",
+    "pvoc",
+    "phase-locking",
+    "stft"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "homepage": "https://github.com/audiojs/stretch/tree/main/packages/stretch-pvoc-lock",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/stretch.git",
+    "directory": "packages/stretch-pvoc-lock"
+  },
+  "bugs": "https://github.com/audiojs/stretch/issues",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pvoc-lock.d.ts

@@ -0,0 +1,9 @@
+import type { StreamWriter, StretchOpts } from '@audio/stretch-core'
+
+export type PvocLockOpts = StretchOpts
+
+declare const pvocLock: {
+  (data: Float32Array, opts?: PvocLockOpts): Float32Array
+  (opts?: PvocLockOpts): StreamWriter
+}
+export default pvocLock

package/pvoc-lock.js

@@ -0,0 +1,44 @@
+// Phase-locked vocoder (Laroche & Dolson, 1999). After propagating phases,
+// locks non-peak bins to their nearest spectral peak's rotation — restores
+// harmonic phase coherence, eliminating the "phasiness" of plain pvoc.
+//
+// For attack preservation on percussion, use @audio/stretch-transient.
+
+import { stftBatch, stftStream } from 'fourier-transform/stft'
+import { writer, wrapPhase, lockPhase, stretchOpts } from '@audio/stretch-core'
+
+function process(mag, phase, state, ctx) {
+  let { half, anaHop, synHop, freqPerBin } = ctx
+
+  if (!state.prev) {
+    state.prev = new Float64Array(half + 1)
+    state.synPrev = new Float64Array(half + 1)
+    state.p = new Float64Array(half + 1)
+    state.first = true
+  }
+
+  // Unlike plain pvoc, pre-pad partial frames are processed, not passed through:
+  // per-frame peak locking re-coheres whatever the early propagation does, and
+  // warming the phase state on pad frames measures ~0.2 dB better LSD at onset.
+  let p = state.p
+  if (state.first) {
+    p.set(phase)
+    state.first = false
+  } else {
+    for (let k = 0; k <= half; k++) {
+      let dp = wrapPhase(phase[k] - state.prev[k] - k * freqPerBin * anaHop)
+      p[k] = state.synPrev[k] + (k * freqPerBin + dp / anaHop) * synHop
+    }
+    lockPhase(phase, p, mag, half)
+  }
+
+  state.prev.set(phase)
+  state.synPrev.set(p)
+  return { mag, phase: p }
+}
+
+export default function pvocLock(data, opts) {
+  if (!(data instanceof Float32Array)) return writer(stftStream(process, stretchOpts(data)))
+  if ((opts?.factor ?? 1) === 1) return new Float32Array(data)
+  return stftBatch(data, process, stretchOpts(opts))
+}