Harmonic Resonance — User Guide

Three resonance engines in one tool: a true harmonic resonator bank tuned to F0, 2F0, 3F0..., a corrected geometric feed-forward comb cascade, and the preserved legacy feedback-comb texture.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 0.7 (2026) License: MIT License Repo: GitHub

What this does

Harmonic Resonance offers three distinct processing characters. The default character is a bank of tuned second-order resonators centred on integer multiples of a detected or fixed fundamental. Two historical delay-based characters are retained as alternative textures.

Character	Core process	What “harmonic” means
True harmonic resonators	Parallel causal all-pole resonators at F0, 2F0, 3F0...	Actual integer harmonic frequencies derived from a fundamental.
Geometric comb	Iterated frozen feed-forward difference stages using geometrically shorter delays.	Historical name only; the delays are geometric, not a true harmonic series.
Legacy feedback comb	Original in-place difference process, where the backward tap can read already-processed samples.	Historical texture; again not an F0-based harmonic bank.

Default: Character 1 — true harmonic resonators (pitch-derived).

Quick start

Select exactly one Sound object.
Run Harmonic_Resonance.praat.
Choose a preset or keep Custom.
Choose the processing Character.
For true harmonic resonators, choose pitch-derived or fixed fundamental, then set Q and wet mix.
For geometric/legacy comb modes, choose the harmonic-base range or a fixed base.
Set tail and fadeout as required, then run the script.

Character 1 — True harmonic resonators

This mode is the current main engine. It finds or accepts a fundamental frequency F0, then builds resonators at integer multiples below a 95% Nyquist limit:

f[k] = k × F0, k = 1 ... activeHarmonics activeHarmonics = min( Num_iterations, floor(0.95 × Nyquist / F0) )

Fundamental

Pitch-derived median: the input is folded to mono only for pitch analysis; Praat Pitch is computed between Pitch_floor_Hz and Pitch_ceiling_Hz, and the median voiced frequency is used.
Fallback: if no reliable voiced pitch is available, Fixed_fundamental_Hz is used.
Fixed Hz: bypasses pitch-derived F0 and uses the entered value directly.

Second-order resonator

For each harmonic, bandwidth is derived from Q:

bandwidth[k] = max(2 Hz, f[k] / Resonance_Q) r = exp(-π × bandwidth / sampleRate) p = -2r cos(2πf/sampleRate) q = r² y[n] = x[n] - p·y[n-1] - q·y[n-2]

This is a causal all-pole resonator. Because the source is first extended with silence, the recursive resonators can continue ringing into the tail.

Harmonic weights

rawWeight[k] = Decay_factor^(k-1) normalizedWeight[k] = rawWeight[k] / sqrt(Σ rawWeight²)

The weight vector is energy-normalized, so increasing the requested harmonic count mainly changes spectral colour rather than simply increasing total wet energy.

Dry/wet construction

dry = extendedSource × (1 - Resonance_mix) wet harmonic layer k: layerScale = Resonance_mix × normalizedWeight[k] × originalRMS / resonatorLayerRMS result = dry + Σ scaled harmonic layers

Resonance_mix is validated to 0–1. The original channel count is preserved throughout.

Characters 2–3 — Geometric comb textures

These modes preserve the older sound of the processor. A single geometric base is chosen once per run — either the fixed base or one random value drawn uniformly from Harmonic_base_min ... Harmonic_base_max. It is not re-randomized at every iteration.

shiftFactor[k] = base^k D[k] = round(totalExtendedSamples / shiftFactor[k]) halfD[k] = round(D[k] / 2) iterationWeight = 1 / k ampDecay = 1 - (k / Num_iterations) × Decay_factor

Because totalExtendedSamples includes the silent tail, Tail_duration_s changes the actual comb delays in Characters 2 and 3. As k increases, base^k grows and the delay becomes geometrically shorter.

Character 2 — corrected feed-forward

Each iteration first freezes the complete pre-iteration result. Both taps read that frozen snapshot:

if both taps are in range: y[n] = (xFrozen[n + D] - xFrozen[n - D/2]) × (1/k) else: y[n] = 0.5 × previousResult[n] then: y[n] = y[n] × ampDecay

This prevents accidental recursion within the same formula pass.

Character 3 — legacy feedback comb

The same formula uses self directly. Praat updates samples left-to-right, so the backward tap can read values that have already been processed during that pass. This creates the recursive/feedback-like character of the legacy version.

Presets

Presets set the resonance/comb parameters below, but they do not change Character, Fundamental mode, pitch bounds, fixed F0, Draw visualization, or Play result.

Preset	Tail	Iterations	Q	Wet	Base range	Decay	Peak	Fade
Subtle Harmonics	1.5 s	4	18	0.35	1.3–2.2	0.62	0.96	0.8 s
Medium Harmonics	2.0 s	7	24	0.50	1.5–4.0	0.72	0.95	1.0 s
Heavy Harmonics	2.8 s	10	30	0.65	2.0–4.8	0.78	0.93	1.4 s
Extreme Harmonics	4.0 s	15	36	0.75	2.5–6.0	0.84	0.91	1.8 s
Custom	2.0 s	7	24	0.55	1.5–4.0	0.72	0.95	1.0 s

Parameters & validation

Parameter	Default	Meaning
Character	True harmonic resonators	Selects the F0-based bank, corrected geometric comb, or legacy comb.
Tail_duration_s	2.0	Extra zero-valued duration appended before processing; may be 0.
Num_iterations	7	Requested harmonics in Character 1 or iterations in Characters 2–3; valid 1–64.
Resonance_Q	24	Resonator sharpness in Character 1; must be > 0.
Resonance_mix	0.55	Dry/wet control for Character 1; 0–1.
Fundamental_mode	Pitch-derived median	Median voiced Pitch or fixed F0.
Pitch_floor_Hz / ceiling	50 / 800	Bounds for pitch-derived F0 analysis.
Fixed_fundamental_Hz	110	Fixed F0 and fallback F0.
Harmonic_base_min / max	1.5 / 4.0	Random geometric-base range for Characters 2–3; must satisfy 1 < min ≤ max.
Use_fixed_base	Off	Use Fixed_harmonic_base instead of a random base.
Fixed_harmonic_base	2.5	Must be > 1.
Decay_factor	0.72	Harmonic weight decay in Character 1; historical per-iteration decay in Characters 2–3. Valid 0 ≤ value < 1.
Scale_peak	0.95	Character-dependent level handling; valid (0,1].
Fadeout_duration_s	1.0	Final cosine fade; may be 0 and is capped at total duration.
Draw_visualization	On	Draws waveform, process model, spectra and summary.
Play_result	On	Plays the created result.

Level handling & fadeout

Scale_peak has different semantics in the three characters:

True harmonic resonators: attenuation-only safety ceiling. The result is scaled down only if its Sinc70 peak exceeds Scale_peak. Quiet results are not amplified, preserving the requested dry/wet balance.
Geometric comb / Legacy comb: any non-silent result is peak-normalized to Scale_peak, so quiet results can be amplified.

The final fadeout is applied after this level stage:

effectiveFade = min(Fadeout_duration_s, totalDuration) gain(x) = 0.5 + 0.5 × cos( π × (x - fadeStart) / effectiveFade )

There is no second normalization after the fade.

Visualization

The Picture output uses the same Source/Output amplitude scale and shows four functional views:

Original waveform: neutral gray source waveform.
Processed waveform: blue result, including the silent-tail duration and resonance decay.
Process explanation: in Character 1, a stylized resonance field at F0, 2F0, 3F0... where peak height follows harmonic decay and visual width follows Q; in Characters 2–3, a delay ladder showing the geometrically shrinking stage delays.
Spectra: original spectrum in gray and processed spectrum in green, each displayed up to min(5 kHz, Nyquist).
Summary: F0/harmonic/Q/wet information for Character 1, or base/iterations/decay for comb modes.

The central process panel is explanatory, not a measured transfer-function plot. Its resonance peaks and delay ladder illustrate the implemented law without implying calibrated response magnitude.

Output behavior

Input channel count is preserved, including multichannel material.
The processing buffer is shifted to a zero-based time domain before the tail is added.
Result duration = source duration + Tail_duration_s.
Original Sound remains unchanged.

Object names depend on Character:

True harmonic: <source>_harmonicRes_<preset> Geometric comb: <source>_geoComb_<preset> Legacy comb: <source>_legacyComb_<preset>