@audio/stretch 2.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,297 @@
+# @audio/stretch [![test](https://github.com/audiojs/stretch/actions/workflows/test.yml/badge.svg)](https://github.com/audiojs/stretch/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@audio/stretch)](https://www.npmjs.com/package/@audio/stretch) [![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/audiojs/stretch/blob/main/LICENSE)
+
+Time stretching algorithms — umbrella over `@audio/stretch-*` atoms.
+
+| Atom | Algorithm | Domain | Quality | CPU | Best for |
+|---|---|---|---|---|---|
+| [`@audio/stretch-wsola`](#wsola) | WSOLA | time | ★★★ | low | speech, real-time |
+| [`@audio/stretch-psola`](#psola) | PSOLA | time | ★★★★ | medium | speech, monophonic instruments |
+| [`@audio/stretch-pvoc`](#pvoc) | plain phase vocoder | freq | ★★ | medium | educational baseline |
+| [`@audio/stretch-pvoc-lock`](#pvoc-lock) | phase-locked vocoder | freq | ★★★★ | medium | general music |
+| [`@audio/stretch-pghi`](#pghi) | phase-gradient vocoder | freq | ★★★★ | medium | vibrato, glides, chirps |
+| [`@audio/stretch-transient`](#transient) | transient-aware vocoder | freq | ★★★★★ | medium | music with percussion |
+| [`@audio/stretch-hybrid`](#hybrid) | HPSS hybrid | freq+time | ★★★★ | high | full mixes — drums over tonal |
+| [`@audio/stretch-paulstretch`](#paulstretch) | PaulStretch | freq | — | medium | extreme stretch (ambient, drones) |
+| [`@audio/stretch-sms`](#sms) | Sinusoidal Modeling | sinusoidal | ★★★★ | high | harmonic / tonal material |
+
+For pitch shifting, see the `@audio/shift-*` family.
+
+
+## Usage
+
+Install the umbrella (all atoms):
+
+```
+npm install @audio/stretch
+```
+
+```js
+import { transient, wsola } from '@audio/stretch'
+
+let slower = transient(samples, { factor: 2 })          // 2× slower, same pitch
+let fast   = wsola(samples, { factor: 0.75 })           // 1.33× faster
+
+let write = transient({ factor: 1.5 })                  // real-time streaming
+write(block1)
+write(block2)
+write()                                                  // → remaining samples
+```
+
+Or install just the atom you need — each is self-contained:
+
+```
+npm install @audio/stretch-transient
+```
+
+```js
+import transient from '@audio/stretch-transient'
+let out = transient(samples, { factor: 2 })
+```
+
+> Mono `Float32Array` in/out. For stereo, process channels independently. Output sizes may be variable — small or empty early chunks are normal in streaming.
+
+## Time domain
+
+### `wsola` — `@audio/stretch-wsola`
+
+Waveform Similarity Overlap-Add. Divides signal into overlapping frames and places them at new synthesis positions, but before placing each frame searches ±delta samples for the read position that maximizes cross-correlation with the natural progression of the previous grain through the input — eliminating the phase cancellation (flanging) of plain OLA. No FFT overhead.
+
+```js
+import wsola from '@audio/stretch-wsola'
+
+wsola(data, { factor: 1.5 })
+wsola(data, { factor: 0.5, delta: 512 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | Window size |
+| `hopSize` | `frameSize/4` | Hop between frames |
+| `delta` | `frameSize/4` | Search range (±samples) |
+
+**Use when:** Speech, real-time with tight CPU budgets, moderate ratios (0.5–2×).<br>
+**Not for:** Polyphonic music with sustained tones — frequency-domain methods handle harmonics better.
+
+
+### `psola` — `@audio/stretch-psola`
+
+Pitch-Synchronous Overlap-Add. Detects pitch period via autocorrelation, then windows grains at pitch cycle boundaries. Because grains align with the pitch cycle there are no phase discontinuities at overlaps — cleaner than WSOLA for monophonic pitched signals.
+
+```js
+import psola from '@audio/stretch-psola'
+
+psola(data, { factor: 1.5 })
+psola(data, { factor: 0.75, sampleRate: 48000 })
+psola(data, { factor: 2, minFreq: 100, maxFreq: 400 })  // male voice range
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `sampleRate` | `44100` | For pitch detection frequency range |
+| `minFreq` | `80` | Lowest expected pitch (Hz) |
+| `maxFreq` | `500` | Highest expected pitch (Hz) |
+
+**Use when:** Speech, solo vocals, monophonic instruments, factors 0.5–2×.<br>
+**Not for:** Polyphonic material — autocorrelation finds one pitch period so chords get mangled. Extreme ratios (>2×) cause gaps.
+
+
+## Frequency domain
+
+### `pvoc` — `@audio/stretch-pvoc`
+
+Plain phase vocoder. Each bin's phase advances at its instantaneous frequency independently. Magnitudes are preserved but incoherent inter-harmonic phase relationships give complex signals a diffuse, "underwater" quality.
+
+```js
+import pvoc from '@audio/stretch-pvoc'
+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:** Educational baseline, simple tonal signals.<br>
+**Not for:** General music — use [`pvoc-lock`](#pvoc-lock) or [`transient`](#transient).
+
+
+### `pvoc-lock` — `@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, eliminating phasiness.
+
+```js
+import pvocLock from '@audio/stretch-pvoc-lock'
+pvocLock(data, { factor: 2 })
+```
+
+Same options as [`pvoc`](#pvoc).
+
+**Use when:** General music — tonal/ambient material where transient resets aren't needed.<br>
+**Not for:** Percussive material where attacks matter — use [`transient`](#transient).
+
+
+### `pghi` — `@audio/stretch-pghi`
+
+Phase Gradient Heap Integration — "Phase Vocoder Done Right" (Průša & Holighaus, 2017). Synthesis phase is integrated from the analysis phase gradients, visiting bins in magnitude order via a max-heap: no peak picking, no transient heuristics; chirps, vibrato and glides stay coherent by construction.
+
+```js
+import pghi from '@audio/stretch-pghi'
+
+pghi(data, { factor: 2 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT size (power of 2) |
+| `hopSize` | `frameSize/8` | Hop — gradient integration wants dense frames |
+| `tolerance` | `1e-6` | Bins below `tolerance×max` get random phase |
+
+**Use when:** modulated material — vibrato, glissandi, pitch-unstable sources.<br>
+**Not for:** steady polyphony — [`pvoc-lock`](#pvoc-lock)'s identity locking reproduces intra-partial phases exactly where gradient integration only approximates them.
+
+
+### `transient` — `@audio/stretch-transient`
+
+Transient-aware phase-locked vocoder (Röbel, 2003). Measures spectral flux between frames; on a sharp onset it resets to the original analysis phase instead of propagating it, preserving attack sharpness on drums and plucks. Implies phase locking.
+
+```js
+import transient from '@audio/stretch-transient'
+
+transient(data, { factor: 2 })
+transient(data, { factor: 1.5, transientThreshold: 2.0 })  // less sensitive detection
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT size (power of 2) |
+| `hopSize` | `frameSize/4` | Hop between frames |
+| `transientThreshold` | `1.5` | Spectral flux threshold (higher = fewer resets) |
+
+**Use when:** The right default for most music — percussion, mixed sources.<br>
+**Not for:** Voice/speech — use [`psola`](#psola). Extreme stretch — use [`paulstretch`](#paulstretch).
+
+
+### `hybrid` — `@audio/stretch-hybrid`
+
+Harmonic/percussive hybrid (Driedger & Müller). Median-filter HPSS splits the spectrogram into two layers; the harmonic layer goes through the phase-locked vocoder, the percussive layer through short-frame OLA — chords stay coherent and attacks stay sharp, where one algorithm must trade one for the other.
+
+```js
+import hybrid from '@audio/stretch-hybrid'
+
+hybrid(data, { factor: 2 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT size for HPSS + harmonic path |
+| `percFrame` | `512` | OLA frame for the percussive layer |
+| `harmMedian` | `17` | Median filter across time (frames) |
+| `percMedian` | `17` | Median filter across frequency (bins) |
+
+**Use when:** full mixes — drums over tonal material.<br>
+**Cost:** separation + two stretches ≈ 4–6× the CPU of [`pvoc-lock`](#pvoc-lock) alone.
+
+
+### `paulstretch` — `@audio/stretch-paulstretch`
+
+Extreme time stretching via phase randomization (Nasca, 2006). Preserves magnitudes but replaces all phases with random values, producing smooth, dreamlike textures. Designed for large factors.
+
+```js
+import paulstretch from '@audio/stretch-paulstretch'
+
+paulstretch(data, { factor: 8 })
+paulstretch(data, { factor: 100, frameSize: 8192 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `8` | Time stretch ratio (best >2×) |
+| `frameSize` | `4096` | FFT size (larger = smoother) |
+| `seed` | `0x1f123bb5` | PRNG seed (deterministic output) |
+
+**Use when:** Ambient music, sound design, drone generation, 8×–1000× stretch.<br>
+**Not for:** Small ratios (<2×) — sounds washed out. Not for preserving rhythm or transients.
+
+
+## Sinusoidal
+
+### `sms` — `@audio/stretch-sms`
+
+Sinusoidal Modeling Synthesis (Serra 1989, McAulay-Quatieri 1986). Decomposes audio into individually tracked sinusoidal partials and resynthesizes at the new time rate. Each partial's frequency and magnitude are interpolated independently — no phase spreading or bin-by-bin artifacts.
+
+```js
+import sms from '@audio/stretch-sms'
+
+sms(data, { factor: 2 })
+sms(data, { factor: 0.5, maxTracks: 80 })
+sms(data, { factor: 3, frameSize: 4096 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT frame size |
+| `hopSize` | `frameSize/4` | Hop between frames |
+| `maxTracks` | `60` | Max simultaneous sinusoidal tracks |
+| `minMag` | `1e-4` | Peak detection threshold (linear) |
+| `freqDev` | `3` | Max frequency deviation (bins) for track continuation |
+| `residualMix` | `1` | Stochastic residual blended into the sinusoidal output |
+
+**Use when:** Harmonic / tonal content — instruments, chords, vocals — where the phase vocoder introduces smearing. Default `residualMix=1` blends breath, noise, and transient energy alongside the sinusoidal model.<br>
+**Not for:** Noise-dominated material.
+
+
+## Shared — `@audio/stretch-core`
+
+Helpers and quality metrics shared across atoms:
+
+```js
+import { hannWindow, wrapPhase, resample, writer, makeStreamBufs } from '@audio/stretch-core'
+import { lsd, spectralSim, chordBalance, chordRetention, modulationDepth } from '@audio/stretch-core/quality'
+```
+
+`lsd` (log-spectral distance), `spectralSim` (cosine similarity), `chordBalance`, `chordRetention`, and `modulationDepth` (AM depth per partial) evaluate algorithm output against a reference.
+
+
+## Research & comparison
+
+| Command | What it does |
+|---|---|
+| `node scripts/compare.js` | writes `compare.html` — interactive waveforms, playback, internal-vs-external comparisons |
+| `node scripts/bench.js` | throughput and ×realtime numbers for batch and streaming |
+| `node scripts/diagnose.js` | targeted diagnostics for specific algorithm behaviors |
+
+[Demo](https://audiojs.github.io/time-stretch/) for a lightweight browser listening matrix.
+
+
+## See also
+
+* [fourier-transform](https://github.com/audiojs/fourier-transform) — FFT + STFT kernels
+* [@audio/shift-*](https://github.com/audiojs/shift) — pitch shifting family
+* [@audio/filter](https://github.com/audiojs/filter) — audio filters
+* [digital-filter](https://github.com/audiojs/digital-filter) — filter design
+
+
+## References
+
+* Verhelst, W. & Roelands, M. (1993). "An overlap-add technique based on waveform similarity (WSOLA)." _ICASSP_.
+* Laroche, J. & Dolson, M. (1999). "Improved phase vocoder time-scale modification of audio." _IEEE Trans. Speech Audio Processing_.
+* Röbel, A. (2003). "A new approach to transient processing in the phase vocoder." _DAFx_.
+* Nasca, P. (2006). "PaulStretch — extreme time stretching." _paulnasca.com_.
+* Moulines, E. & Charpentier, F. (1990). "Pitch-synchronous waveform processing techniques for text-to-speech synthesis using diphones." _Speech Communication_, 9(5-6).
+* Driedger, J. & Müller, M. (2016). "A review of time-scale modification of music signals." _Applied Sciences_, 6(2).
+* Serra, X. (1989). "A System for Sound Analysis/Transformation/Synthesis Based on a Deterministic plus Stochastic Decomposition." PhD thesis, Stanford.
+* McAulay, R.J. & Quatieri, T.F. (1986). "Speech analysis/synthesis based on a sinusoidal representation." _IEEE Trans. ASSP_, 34(4).
+
+
+<div align="center">
+
+[MIT](https://github.com/audiojs/stretch/blob/main/LICENSE) [ॐ](https://github.com/krishnized/license)
+
+</div>

package/index.d.ts

@@ -0,0 +1,26 @@
+export { default as wsola } from '@audio/stretch-wsola'
+export type { WsolaOpts } from '@audio/stretch-wsola'
+
+export { default as pvoc } from '@audio/stretch-pvoc'
+export type { PvocOpts } from '@audio/stretch-pvoc'
+
+export { default as pvocLock } from '@audio/stretch-pvoc-lock'
+export type { PvocLockOpts } from '@audio/stretch-pvoc-lock'
+
+export { default as pghi } from '@audio/stretch-pghi'
+export type { PghiOpts } from '@audio/stretch-pghi'
+
+export { default as transient } from '@audio/stretch-transient'
+export type { TransientOpts } from '@audio/stretch-transient'
+
+export { default as hybrid } from '@audio/stretch-hybrid'
+export type { HybridOpts } from '@audio/stretch-hybrid'
+
+export { default as paulstretch } from '@audio/stretch-paulstretch'
+export type { PaulstretchOpts } from '@audio/stretch-paulstretch'
+
+export { default as psola } from '@audio/stretch-psola'
+export type { PsolaOpts } from '@audio/stretch-psola'
+
+export { default as sms } from '@audio/stretch-sms'
+export type { SmsOpts } from '@audio/stretch-sms'

package/index.js

@@ -0,0 +1,12 @@
+// @audio/stretch — umbrella re-exporting every sub-package.
+// For smaller bundles, depend directly on the individual @audio/stretch-* atom.
+
+export { default as wsola } from '@audio/stretch-wsola'
+export { default as pvoc } from '@audio/stretch-pvoc'
+export { default as pvocLock } from '@audio/stretch-pvoc-lock'
+export { default as pghi } from '@audio/stretch-pghi'
+export { default as transient } from '@audio/stretch-transient'
+export { default as hybrid } from '@audio/stretch-hybrid'
+export { default as paulstretch } from '@audio/stretch-paulstretch'
+export { default as psola } from '@audio/stretch-psola'
+export { default as sms } from '@audio/stretch-sms'

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@audio/stretch",
+  "version": "2.0.0",
+  "type": "module",
+  "types": "index.d.ts",
+  "description": "Time stretching — umbrella for @audio/stretch-* atoms (WSOLA, phase vocoder variants, PaulStretch, PSOLA, SMS)",
+  "sideEffects": false,
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "test:browser": "node test/browser.js",
+    "test:all": "npm test --workspaces --if-present && npm test && npm run test:browser",
+    "publish:all": "npm publish --workspaces && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/stretch.git"
+  },
+  "keywords": [
+    "time-stretch",
+    "time-stretching",
+    "wsola",
+    "phase-vocoder",
+    "phase-locking",
+    "pghi",
+    "transient",
+    "hpss",
+    "hybrid",
+    "paulstretch",
+    "psola",
+    "sms",
+    "sinusoidal",
+    "tempo",
+    "audio",
+    "dsp",
+    "signal-processing"
+  ],
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/audiojs/stretch/issues"
+  },
+  "homepage": "https://github.com/audiojs/stretch#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@audio/stretch-core": "^1.0.0",
+    "@audio/stretch-hybrid": "^1.0.0",
+    "@audio/stretch-paulstretch": "^1.0.0",
+    "@audio/stretch-pghi": "^1.0.0",
+    "@audio/stretch-psola": "^1.0.0",
+    "@audio/stretch-pvoc": "^1.0.0",
+    "@audio/stretch-pvoc-lock": "^1.0.0",
+    "@audio/stretch-sms": "^1.0.0",
+    "@audio/stretch-transient": "^1.0.0",
+    "@audio/stretch-wsola": "^1.0.0"
+  },
+  "devDependencies": {
+    "audio-lena": "^3.0.0",
+    "playwright": "^1.59.1",
+    "tst": "^9.4.0",
+    "wavefont": "^3.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}