@audio/stretch

Time stretching algorithms — umbrella over @audio/stretch-* atoms.

| Atom | Algorithm | Domain | Quality | CPU | Best for | |---|---|---|---|---|---| | @audio/stretch-wsola | WSOLA | time | ★★★ | low | speech, real-time | | @audio/stretch-psola | PSOLA | time | ★★★★ | medium | speech, monophonic instruments | | @audio/stretch-pvoc | plain phase vocoder | freq | ★★ | medium | educational baseline | | @audio/stretch-pvoc-lock | phase-locked vocoder | freq | ★★★★ | medium | general music | | @audio/stretch-pghi | phase-gradient vocoder | freq | ★★★★ | medium | vibrato, glides, chirps | | @audio/stretch-transient | transient-aware vocoder | freq | ★★★★★ | medium | music with percussion | | @audio/stretch-hybrid | HPSS hybrid | freq+time | ★★★★ | high | full mixes — drums over tonal | | @audio/stretch-paulstretch | PaulStretch | freq | — | medium | extreme stretch (ambient, drones) | | @audio/stretch-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

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

import transient from '@audio/stretch-transient'
let out = transient(samples, { factor: 2 })

Float32Array in/out; a channel array [L, R] (or Float64Array) is accepted and processed per channel — parity with @audio/shift. 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.

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×). 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.

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×. 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.

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. Not for: General music — use pvoc-lock or 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.

import pvocLock from '@audio/stretch-pvoc-lock'
pvocLock(data, { factor: 2 })

Same options as pvoc.

Use when: General music — tonal/ambient material where transient resets aren't needed. Not for: Percussive material where attacks matter — use 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.

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. Not for: steady polyphony — 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.

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. Not for: Voice/speech — use psola. Extreme stretch — use 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.

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. Cost: separation + two stretches ≈ 4–6× the CPU of 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.

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. 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.

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. Not for: Noise-dominated material.

Quality metrics — @audio/quality

Every atom is self-contained (framing/OLA helpers inlined; the phase-locking engine lives in @audio/spectral-pvoc). Output quality is evaluated with @audio/quality:

import { lsd, spectralSim, chordBalance, chordRetention, modulationDepth } from '@audio/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 for a lightweight browser listening matrix.

See also

• fourier-transform — FFT + STFT kernels
• @audio/shift-* — pitch shifting family
• @audio/filter — audio filters
• 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).

MIT ॐ