@audio/stretch-pvoc 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
+
+Plain phase vocoder. Each FFT bin's phase advances at its instantaneous frequency. Magnitudes preserved, but inter-harmonic phase coherence is lost — complex signals get a diffuse, "underwater" character. Educational baseline.
+
+```js
+import pvoc from '@audio/stretch-pvoc'
+let out = pvoc(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:** learning the phase-vocoder algorithm, simple tonal signals.<br>
+**Not for:** general music — use [`@audio/stretch-pvoc-lock`](../stretch-pvoc-lock) or [`@audio/stretch-transient`](../stretch-transient).
+
+Part of [`@audio/stretch`](../..).
+
+## License
+
+[MIT](./LICENSE) · [ॐ](https://github.com/krishnized/license/)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@audio/stretch-pvoc",
+  "version": "1.0.0",
+  "description": "Phase vocoder time stretching — educational baseline without phase locking",
+  "type": "module",
+  "sideEffects": false,
+  "main": "pvoc.js",
+  "types": "pvoc.d.ts",
+  "exports": {
+    ".": "./pvoc.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "pvoc.js",
+    "pvoc.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",
+    "stft"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "homepage": "https://github.com/audiojs/stretch/tree/main/packages/stretch-pvoc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/stretch.git",
+    "directory": "packages/stretch-pvoc"
+  },
+  "bugs": "https://github.com/audiojs/stretch/issues",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pvoc.d.ts

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

package/pvoc.js

@@ -0,0 +1,47 @@
+// Plain phase vocoder. Each bin's phase advances at its instantaneous frequency,
+// independently of the rest. Magnitudes preserved but incoherent inter-harmonic
+// phase relationships give complex signals a diffuse, "underwater" quality.
+//
+// For harmonic coherence use @audio/stretch-pvoc-lock.
+// For transient preservation use @audio/stretch-transient.
+
+import { stftBatch, stftStream } from 'fourier-transform/stft'
+import { writer, wrapPhase, stretchOpts } from '@audio/stretch-core'
+
+function process(mag, phase, state, ctx) {
+  let { half, anaHop, synHop, freqPerBin, frameStart } = ctx
+
+  if (!state.prev) {
+    state.prev = new Float64Array(half + 1)
+    state.sum = new Float64Array(half + 1)
+    state.p = new Float64Array(half + 1)
+    state.first = true
+  }
+
+  // stftBatch pre-pads with N zeros; propagating phase through those partial
+  // frames drifts the accumulator. Pass them through untouched (preserves the
+  // onset), then anchor once the analysis frame sits fully inside the signal.
+  if (state.first) {
+    if (frameStart < 0) return { mag, phase }
+    state.sum.set(phase)
+    state.prev.set(phase)
+    state.first = false
+    return { mag, phase }
+  }
+
+  let p = state.p
+  for (let k = 0; k <= half; k++) {
+    let dp = wrapPhase(phase[k] - state.prev[k] - k * freqPerBin * anaHop)
+    state.sum[k] += (k * freqPerBin + dp / anaHop) * synHop
+    p[k] = state.sum[k]
+  }
+
+  state.prev.set(phase)
+  return { mag, phase: p }
+}
+
+export default function pvoc(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))
+}