Gizmo Pitch Shift — Phase Vocoder

Vectorised phase vocoder pitch shifting with presets, FFT frame control, window selection, dry/wet mix, bin-transposition map, spectrum comparison, and pitch verification.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 1.0 (2026) License: MIT License Repo: https://github.com/ShaiCohen-ops/Praat-plugin_AudioTools

Contents:

What this does Quick start 7 Presets Theory Controls Applications

What this does

This script implements a vectorised phase vocoder pitch shifter — a full-featured, pure-Praat pitch shifting engine with presets, FFT frame control, window selection, dry/wet mix, and comprehensive visualisation. It uses a phase vocoder with phase-locked bin transposition: each source bin is mapped to a target bin by k → round(k × ratio), magnitudes are summed at target bins, and the synthesis phase is integrated from the scaled instantaneous frequency of each source bin.

What is a phase vocoder? A phase vocoder analyses sound in overlapping FFT frames, tracking the phase evolution of each frequency bin to estimate instantaneous frequency. This allows pitch shifting by remapping bins to new frequencies while preserving the phase coherence of the original sound. Unlike simple resampling, a phase vocoder can shift pitch without changing duration (or with controlled duration changes). This script implements a bin-transposition phase vocoder: source bins are mapped to target bins by a fixed frequency ratio.

Key Features:

7 Presets — Fifth up, Octave up, Octave down, Minor third up, Detune shimmer, Smeared drone, Transient safe
Full phase vocoder — magnitude-preserving bin transposition, phase accumulation
3 Window types — Hann, Hamming, Gaussian
Dry/wet mix — blend original and pitch-shifted signals
COLA weight normalisation — correct overlap-add scaling
Visualisation — input/output waveforms, bin transposition map, spectrum overlay, window overlap, pitch track verification

Pure Praat — no Python: The entire algorithm runs inside Praat using vectorised Formula operations. The FFT is performed via Praat's native To Spectrum, and phase accumulation is done per bin with Formula across frames. This is a self-contained, platform-independent pitch shifter.

Quick start

In Praat, select exactly one Sound object.
Run script… → Gizmo_Pitch_Shift.praat.
Choose a preset from the dropdown (7 options, plus Custom).
If Custom, adjust Semitones (range ±12), Frame_length_s, Hop_fraction, Window_type, Dry_wet_mix.
Click OK — script processes the sound using the vectorised phase vocoder, creates output original_gizmo_shift_+Xst.

Quick tip: Start with Fifth up (+7 st) for a classic pitch shift with good transient preservation. Octave down (-12 st) uses a long frame (120 ms) and fine hop (12.5%) for good frequency resolution. Transient safe (23 ms frame, 87.5% overlap) preserves attacks. Detune shimmer applies a 0.2 st shift at 50% wet for chorus-like thickening. Enable Draw_visualization to see the bin transposition map and spectrum comparison.

Important: The phase vocoder maps source bins to target bins by round(k × ratio). For up-shifts (ratio > 1), source bins above Nyquist / ratio are discarded (no content survives). For down-shifts (ratio < 1), multiple source bins map to the same target bin — their magnitudes are summed. The COLA weight normalisation ensures correct overlap-add gain. No post-normalisation is applied; output peak may exceed 1.0. The algorithm is designed for monophonic sources (voice, solo instruments); polyphonic material may produce phase artifacts.

7 Presets

Preset	Shift (st)	Frame (ms)	Hop	Window	Dry/Wet	Character
Fifth up	+7.0	80	25%	Hann	1.0	Classic perfect fifth, balanced transients
Octave up	+12.0	40	25%	Hann	1.0	Short frame keeps transients tight
Octave down	−12.0	120	12.5%	Hann	1.0	Long frame, fine hop for frequency resolution
Minor third up	+3.0	80	25%	Hamming	1.0	Lower sidelobes, less taper
Detune shimmer	+0.2	60	25%	Hann	0.5	Subtle detune, chorus-like thickening
Smeared drone	−5.0	250	50%	Gaussian	1.0	Deliberate time blur, drone texture
Transient safe	+7.0	23	12.5%	Hann	1.0	Short frame, 87.5% overlap preserves attacks

Theory — Phase Vocoder Bin Transposition

Frequency mapping

ratio = 2^semitones/12

Each source bin k (0-based) maps to target bin t = round(k × ratio).

ratio > 1 (up-shift): source content above Nyquist / ratio is discarded.
ratio < 1 (down-shift): multiple source bins map to the same target bin; magnitudes are summed.
ratio = 1: identity (no change).

Phase vocoder algorithm (per channel)

Analysis: Windowed STFT → magnitude M and phase φ per frame.
Instantaneous frequency: ω = (φ - φ_prev - 2π·round((φ - φ_prev - expct·k)/(2π))) / hop
Transposition: For each target bin t, gather source bin k where round(k × ratio) = t.
Synthesis magnitude: M_t = Σ M_k (sum of magnitudes from all source bins mapping to t).
Synthesis frequency: ω_t = ω_k × ratio (scaled instantaneous frequency).
Phase accumulation: θ_t += ω_t × hop
Reconstruction: M_t · exp(j·θ_t) → IFFT → windowed overlap-add.

COLA (Constant Overlap-Add) normalisation:

The overlap-add weight buffer accumulates w² (window squared) at each sample position. After all frames are added, the output is divided by this weight buffer, ensuring unity gain regardless of the window shape or hop size.

y[n] = (Σ frame_i[n] · w[n - i·hop]) / Σ w²[n - i·hop]

The COLA ripple (max/min weight ratio) is reported — a ripple < 10% indicates good overlap-add behaviour.

Controls

Core parameters

Parameter	Range	Default	Description
Semitones	−12 to +12	7.0	Pitch shift amount (clamped)
Frame_length_s	>0	0.08	FFT window length (snapped to power of two)
Hop_fraction	0.03125–1.0	0.25	Hop size as fraction of frame (lower = more overlap)
Window_type	Hann / Hamming / Gaussian	Hann	Analysis/synthesis window shape
Dry_wet_mix	0–1	1.0	Blend of dry (original) and wet (shifted) signals

Frame length and transients: Longer frames (120 ms) give better frequency resolution for low-pitched sounds and down-shifts. Shorter frames (23 ms) preserve transient attacks but may have slightly rougher frequency resolution. The "Transient safe" preset uses a 23 ms frame with 87.5% overlap for the best transient preservation.

Applications

Classic pitch shifting (Fifth up, Octave up/down)

Use case: Shift the pitch of a voice or instrument by a fixed interval.

Settings: Fifth up (+7 st) for a perfect fifth; Octave up/down for ±12 st shifts. The phase vocoder preserves timing while changing pitch.

Detune / chorus (Detune shimmer)

Use case: Create a thickening, chorus-like effect by mixing a slightly detuned copy with the original.

Settings: Detune shimmer preset (0.2 st, 50% wet). The small shift and 50% mix create a subtle shimmer.

Smeared / drone textures (Smeared drone)

Use case: Create a smeared, drone-like texture from any sound.

Settings: Smeared drone preset (−5 st, 250 ms Gaussian frame, 50% hop). The long Gaussian frame intentionally smears the time domain.

Transient preservation (Transient safe)

Use case: Pitch shift percussive or plucked sounds while preserving attacks.

Settings: Transient safe preset (23 ms frame, 87.5% overlap). The short frame and high overlap keep transients sharp.

Workflow: Vocal → Fifth up

Source: Sung melody.
Settings: Fifth up preset (+7 st, 80 ms Hann, 25% hop).
Result: The vocal is shifted up by a perfect fifth while preserving timing and articulation.

Workflow: Guitar → Octave down

Source: Guitar recording.
Settings: Octave down preset (−12 st, 120 ms frame, 12.5% hop).
Result: The guitar is shifted down an octave, creating a bass-like texture.

Workflow: Drum loop → Transient safe shift

Source: Drum loop.
Settings: Transient safe preset (+7 st, 23 ms frame, 87.5% overlap).
Result: The drum loop is pitch-shifted while preserving the attacks and transients.

Troubleshooting:
• Output has phasiness / warbling: Increase overlap (lower hop_fraction) or adjust frame length. The phase vocoder can produce phase artifacts with highly inharmonic or noisy material. Try Hann window with 50% overlap.
• Output peak exceeds 1.0: The script does not apply post-normalisation by design. Reduce input gain or use a lower dry/wet mix. The visualisation reports peak levels.
• COLA ripple is high (>20%): This indicates poor overlap-add behaviour. Use a window that satisfies COLA at this hop (Hann with 50% or 25% hop is generally safe). The script reports the ripple percentage.
• Pitch verification shows wrong shift: The pitch tracker (Praat's To Pitch) is used only for visualisation and report. The phase vocoder's shift is measured from the median F0 of voiced frames. For stable sources, this should match the requested shift closely.
• Long sounds take time to process: The algorithm processes each channel frame by frame. For long, multichannel sounds, processing may take several seconds to a minute. Use shorter frame lengths for faster processing (but this may reduce quality).

Visualisation (8-wide canvas)

When Draw_visualization is enabled, the script generates:

Input / Output waveforms — peak-normalised views showing amplitude envelopes.
Bin transposition map — staircase showing source → target bin mapping. The grey diagonal is identity; the staircase shows how bins are remapped. For up-shifts, bins beyond the survival frequency are discarded.
Spectrum comparison — log-frequency band energies of input vs output (shared reference, no gain rescaling).
Window overlap and accumulated envelope — individual w² windows and the accumulated weight envelope (green) that is divided out.
Pitch verification — F0 tracks of input (blue) and output (red) over time, with median shift measurement.

The bin transposition map is the key diagnostic: it shows exactly how the algorithm remaps frequencies.