Spectral Pitch Shifter — User Guide

Content-driven pitch modulation controlled by spectral flatness and a normalized local spectral-curvature descriptor.

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

Contents:

What this does Quick start Presets Parameters Spectral analysis Pitch modulation Analysis & resynthesis Visualization Output

What this does

Spectral Pitch Shifter analyzes a mono reference of the selected Sound at evenly distributed time positions. At each position it measures spectral flatness and a normalized local magnitude-curvature value. These features are interpolated over time and mapped to two controls: pitch-shift depth and modulation speed.

The resulting sinusoidal semitone shift is applied multiplicatively to the detected source F0. In voiced regions, the source pitch contour therefore remains the reference contour: the script moves it up and down by a time-varying number of semitones rather than replacing it with an unrelated absolute pitch trajectory.

Offline analysis: the script analyzes the complete selected Sound and then resynthesizes it. “Spectral-driven” refers to the control relationship between measured features and pitch modulation; it is not a real-time processor.

Quick start

Select exactly one Sound object in Praat.
Run Spectral_Pitch_Shifter.praat.
Choose a preset, or choose Custom and set the analysis and modulation parameters directly.
Click OK. The Info window reports the measured feature values and processing status.
The processed Sound is created as <source>_spectral_<preset>.

Presets

The four built-in presets override only the four pitch-modulation fields. Num_analysis_points, the analysis frequency range, and the output switches keep the values currently shown in the form.

Preset	Base depth (st)	Flatness ×	Base speed (Hz)	Roughness ×	Output suffix
Custom	Form value	Form value	Form value	Form value	`Custom`
Subtle Response	1	3	0.3	1.5	`Subtle`
Moderate Response	2	6	0.5	3.0	`Moderate`
Strong Response	4	10	1.0	5.0	`Strong`
Extreme Response	6	15	1.5	8.0	`Extreme`

Parameters

GUI field	Default	Meaning
Preset	Custom	Selects Custom or one of four response presets.
Num_analysis_points	8	Number of evenly distributed spectral-analysis positions. Valid range: 2–128.
Min_frequency	80 Hz	Lower frequency included in the spectral descriptors.
Max_frequency	5000 Hz	Upper frequency included in the descriptors. It must remain below 49% of the source sample rate.
Base_shift_depth	2 st	Minimum sinusoidal pitch-shift depth before the flatness contribution is added. May be 0.
Flatness_multiplier	6	Scales spectral flatness into additional semitone depth. May be 0.
Base_mod_speed	0.5 Hz	Base modulation frequency before the roughness contribution is added. May be 0.
Roughness_multiplier	3.0	Scales the script's normalized local spectral-curvature value into additional modulation speed. May be 0.
Draw_visualization	On	Draws the analysis and processing summary in the Picture window.
Play_result	On	Plays the processed Sound after completion.

Spectral analysis

Analysis windows

The script first creates a mono analysis reference. The requested analysis positions are evenly distributed from the beginning to the end of the Sound. Each position uses a Hamming-windowed excerpt with a nominal half-span of 100 ms; excerpts are clipped to the source boundaries, and the half-span automatically shrinks for sounds shorter than 200 ms.

Each excerpt is converted to a Spectrum. Only FFT bins between Min_frequency and Max_frequency contribute to the descriptors.

Spectral flatness

Flatness is calculated from FFT power, using the geometric mean divided by the arithmetic mean:

power[k] = real[k]^2 + imag[k]^2 flatness = exp(mean(ln(max(power, 1e-20)))) / mean(power)

The value is limited to 0–1. A larger value increases pitch-shift depth through Flatness_multiplier.

Roughness control descriptor

The quantity labelled Roughness in the script is a normalized local curvature of the FFT magnitude spectrum:

m[k] = sqrt(real[k]^2 + imag[k]^2) curvature[k] = |m[k] - (m[k-1] + m[k+1]) / 2| / max((m[k-1] + m[k] + m[k+1]) / 3, 1e-10) roughness = mean(curvature[k])

The result is limited to 0–4. A larger value increases modulation speed through Roughness_multiplier.

Descriptor meaning: this “Roughness” value is the script's spectral-irregularity control descriptor. It should not be interpreted as a standardized psychoacoustic roughness measure.

Pitch modulation

The measured flatness and roughness values are linearly interpolated between adjacent analysis positions onto a control grid with approximately 10 ms spacing and exact start/end coverage.

shiftDepth(t) = Base_shift_depth + Flatness(t) × Flatness_multiplier modSpeed(t) = Base_mod_speed + Roughness(t) × Roughness_multiplier phase(t) = continuously integrated from modSpeed(t) shift_st(t) = shiftDepth(t) × sin(phase(t)) newF0(t) = sourceF0(t) × 2^(shift_st(t) / 12)

The modulation phase is integrated continuously across the entire control grid, including times where no voiced F0 is available. When voiced pitch resumes, the oscillator therefore continues from its accumulated phase rather than restarting.

Pitch targets are limited independently of the analysis range to 20 Hz … 0.45 × source sample rate. The processed visualization reports the semitone shift after this synthesis safety limit.

Analysis & resynthesis

Pitch reference: Praat Manipulation/PitchTier analysis uses a 50 Hz floor and a ceiling of min(1000 Hz, 0.45 × sample rate).
Voiced regions: each detected source-F0 value is multiplied by the spectral-driven semitone shift. Undefined/unvoiced grid positions do not receive new PitchTier points.
Multichannel input: spectral and pitch analysis use one mono reference. Every original channel is then resynthesized independently with the same processed PitchTier.
Channel structure: the exact original channel count is reconstructed.
Time domain: original start time, end time, duration, and sample rate are preserved.
Resynthesis: each processed channel uses Praat overlap-add resynthesis.

Identity setting: when both Base_shift_depth and Flatness_multiplier are 0, pitch resynthesis is bypassed and the source is copied directly. The final peak-safety stage still applies if that copy exceeds 0.95 peak amplitude.

Visualization

When enabled, the Picture window contains:

Original waveform.
Spectral processed waveform. Original and result waveforms are drawn with Praat's automatic amplitude range separately; they are not a shared-amplitude comparison.
Shift (st) — the applied semitone displacement over time. Up to 500 control points are retained for display. After the visualization fix, this curve reflects the shift after synthesis-frequency limiting.
Flatness — the measured values at the spectral-analysis positions.
Roughness — the normalized local magnitude-curvature values at the same positions.
A legend showing the control mapping: Flatness → Shift Depth and Roughness → Modulation Speed.

Output

Object name: <source>_spectral_<preset>, using Custom, Subtle, Moderate, Strong, or Extreme.
Channels: original channel count preserved.
Duration / time domain: preserved.
Sample rate: preserved.
Peak handling: attenuation-only safety. If the final absolute peak exceeds 0.95, the result is scaled down to 0.95; quieter results are not normalized upward.
Info window: reports each analysis position with flatness and roughness, analysis and pitch-grid timing, any synthesis-limited pitch points, the created object, channel preservation, and whether peak safety was applied.