HPSS Phase Vocoder — v2.0 User Guide
High‑quality time‑stretching via Harmonic‑Percussive Source Separation (HPSS) + phase vocoder. Harmonic content is stretched with the phase vocoder; percussive/transient content is resampled – no metallic smearing.
What this does
HPSS Phase Vocoder performs time‑stretching that preserves the clarity of transients. Traditional phase vocoders smear attacks, producing metallic artefacts when stretching percussive material. This engine first separates the signal into harmonic (sustained tones) and percussive (transients) components using median‑filtering HPSS. The harmonic part is stretched with a high‑quality phase vocoder (instantaneous frequency accumulation), while the percussive part is resampled directly, preserving attack sharpness. The two are recombined into a clean, artefact‑free stretched result.
Quick start
- In Praat, select exactly one Sound object (mono or stereo).
- Run script… →
HPSS_Phase_Vocoder.praat. - Choose a Preset:
- Gentle (x1.3), Medium (x1.5), Extreme (x2.0), Half speed (x2.0, large window), Compress (x0.75), Fast preview (small window)
- For custom mode (preset = Custom), set:
- Stretch_factor – ratio (0.1–10, <1 = compress, >1 = stretch)
- FFT_size – STFT window size (256–8192)
- HPSS_margin – separation sharpness (1–10)
- Click OK. Praat exports WAV, runs Python engine, and imports the result as
originalname_hpss_xN.NN.
numpy, scipy, soundfile. No librosa required.
The engine uses a custom STFT/ISTFT implementation with Hann window and overlap‑add normalisation.
The 6 presets (+ Custom)
| Preset | Stretch | FFT size | Margin | Description |
|---|---|---|---|---|
| Gentle (x1.3) | 1.3 | 4096 | 3.0 | Mild stretch, good for speech. |
| Medium (x1.5) | 1.5 | 4096 | 3.0 | Moderate stretch, balanced. |
| Extreme (x2.0) | 2.0 | 4096 | 3.0 | Double speed – obvious but clean. |
| Half speed (x2.0, large window) | 2.0 | 8192 | 4.0 | Double length, large FFT for smoother harmonics. |
| Compress (x0.75) | 0.75 | 4096 | 3.0 | Shorten duration while preserving pitch. |
| Fast preview (small window) | 1.5 | 2048 | 2.5 | Smaller FFT for quicker processing (lower quality). |
Pipeline — HPSS + phase vocoder
Stage 2 – HPSS (median filtering) – separate magnitude spectrogram into harmonic (horizontal smoothing) and percussive (vertical smoothing).
Stage 3 – Masks – soft Wiener‑style masks with margin exponent
p: mask_H = H^p / (H^p + P^p).Stage 4 – Harmonic path – phase vocoder with instantaneous frequency estimation; stretch factor applied.
Stage 5 – Percussive path – inverse STFT of percussive spectrogram → waveform, then resample to target length (preserves transients).
Stage 6 – Recombine – add harmonic and percussive waveforms, normalise to input peak, write output.
HPSS details
- Harmonic enhancement – median filter across time (size 1×31) – preserves horizontal (tonal) structures.
- Percussive enhancement – median filter across frequency (size 31×1) – preserves vertical (transient) structures.
- Margin – exponent applied to the median‑filtered magnitudes before mask calculation. Higher margin = more aggressive separation.
Phase vocoder details
- Computes instantaneous frequency from phase differences in the input spectrogram.
- Synthesis phase accumulator steps by the stretched instantaneous frequency.
- Magnitude is linearly interpolated between input frames.
Parameters & defaults
Custom parameters (when Preset = Custom)
| Parameter | Range | Default | Description |
|---|---|---|---|
| Stretch_factor | 0.1–10 | 1.5 | Ratio of output duration to input. <1 = compress, >1 = stretch. |
| FFT_size | 256–8192 | 4096 | STFT window size. Larger = better frequency resolution, slower. |
| HPSS_margin | 1–10 | 3.0 | Separation sharpness. Higher = more aggressive HPSS masks. |
Output
| Parameter | Default | Description |
|---|---|---|
| Draw_visualization | yes | Show waveforms, spectrograms, and summary in Praat picture. |
| Play_result | yes | Auto‑play after processing. |
Visualization (Praat picture)
When Draw_visualization = 1, the script draws:
- Original and stretched waveforms – for comparison.
- Original and stretched spectrograms (0–5 kHz).
- Summary panel with:
- Preset name, stretch factor, input/output durations.
- FFT size, HPSS margin, harmonic/percussive RMS, H/P ratio.
- RMS and peak values.
FAQ / troubleshooting
Install: pip install numpy scipy soundfile. On Windows, the script uses py (Python launcher).
Try increasing HPSS_margin (e.g., 4.0 or 5.0) to separate harmonic/percussive more aggressively.
Also ensure FFT_size is large enough (4096 or 8192) to capture low‑frequency detail.
For very percussive material, the percussive resampling path should preserve attacks – if not, check that the
HPSS masks are capturing transients correctly (the hp_ratio stat gives a clue).
The engine normalises the output to the input peak level. If the stretched signal has higher instantaneous peaks due to phase alignment, clipping may occur. Reduce the input level slightly before processing.
The phase vocoder and HPSS median filters are the main cost. Reduce FFT_size for faster processing (at the cost of quality). The “Fast preview” preset uses FFT=2048 for quicker iteration.
The stats file (temp_hpss_stats.txt) contains detailed information: stretch factor, FFT size, hop,
margin, durations, RMS values (input, output, harmonic, percussive), output peak, and H/P ratio. This is used in
the visualisation and can be inspected for quality assessment.
How the HPSS margin works
The margin parameter p appears in the mask formula: mask_H = H^p / (H^p + P^p). When p=1, it's a
simple ratio; as p increases, the mask becomes a “hard” decision: if H > P, mask_H → 1; if H < P, mask_H → 0.
This gives sharper separation but may introduce artefacts. The default 3.0 is a good balance.