Waveguide Klangmaschine — v2.4.2 User Guide

What this does

The script creates a new four-voice SATB chord. Each voice is synthesized by one to three detuned digital-waveguide strings. The four voices are summed, processed through a global eight-resonator soundboard model, resampled to the requested output rate, split into overlapping left/right spectral bands, and finally passed through two independently generated convolution reverbs.

If Use selected sound is enabled and one Sound is selected, that Sound is analyzed only. Its waveform is not mixed into the Klangmaschine output. Analysis measurements instead modify synthesis and reverb parameters.

Quick start

1. Run the script with no selected Sound for a manually controlled stochastic SATB realization, or select one Sound and leave Use selected sound enabled to derive controller parameters from it.
2. Choose a reverb Preset and Randomize depth.
3. For manual operation, set Duration and Transpose.
4. Enable Edit reverb / render details to change internal/output rates, reverb values, Output peak, or Random seed.
5. Run the script. The final result is a stereo Sound; optional process visualization and playback follow.

Selected-Sound analysis

When exactly one Sound is selected and Use selected sound is enabled, the analysis pipeline replaces several manual or stochastic controller values.

How pitch anchors affect SATB ranges

With two or more distinct anchors, the anchors are sorted low-to-high and used to construct voice ranges of approximately ±5 semitones, then clamped to broad physical SATB limits. No second transposition is added after this absolute-range placement.

With zero or one anchor, the standard manual ranges remain in place and the detected pitch class shifts them by the shortest signed interval from C. This can move the soprano range upward; the Internal-rate safety check is evaluated after that shift.

SATB generation

Without multi-anchor analysis, MIDI notes are drawn from these default ranges before manual or detected pitch-class transposition:

Across the whole chord, the script also draws:

• Strings per note: 1–3.
• Detune: 0.1–2.5 Hz.
• Body resonance amount: 0.2–0.95.
• Velocity: random 0.4–0.95 in manual mode, or analysis-derived when a Sound controls the patch.

Each voice then receives a small ±0.05 velocity variation and an independent onset micro-delay from 0 to 30 ms.

Waveguide string model

Each active string runs sample-by-sample at the Internal waveguide rate. The loop contains a fractional-delay allpass, a stiffness-dispersion allpass, one-pole damping, loop feedback, and a small stability-derived bridge-feedback term.

Phase-compensated tuning

Version 2.4 no longer uses a fixed half-sample correction. For each target string frequency, the script estimates the phase delay contributed by the stiffness allpass and loop low-pass at that F0. It then solves the remaining fractional delay with a first-order allpass so that the total loop phase delay predicts the requested frequency.

The visualization and QC retain the predicted tuning error in cents for each voice.

Excitation and string geometry

The excitation is a short half-sine pulse whose amplitude and spectral shape depend on voice velocity. Contact time shortens for high notes. Strike position, pickup position, damping, stiffness, and excitation parameters can be perturbed by Randomize depth.

For two or three strings, frequency offsets are distributed around the voice fundamental. The outer three-string voices use f-detune, f, and f+detune.

Randomization depth

Randomize depth controls the additional character variation, not whether the whole patch is stochastic.

Eight-mode soundboard model

After the four waveguide voices are averaged, the mono master is processed through eight parallel second-order resonators.

Subtle/Wild modes randomize each mode's frequency, bandwidth, and gain. The actual randomized body is then validated: its highest mode must remain below 45% of the Internal waveguide rate. The script rejects an unsafe body rather than silently moving a resonant frequency.

The soundboard output is the direct string sum at gain .25 plus the eight resonator outputs scaled by the chord's randomized Body resonance amount.

Spectral-split stereo stage

After the internal mono model is normalized and resampled to Final output rate, two overlapping filtered copies are created:

The two filtered copies are combined as left and right channels. This is spectral separation, not position panning; the large overlap intentionally preserves shared mid-band energy.

When audio analysis is active, spectral centroid controls High cutoff between 2000 and 8000 Hz. Otherwise the Details/preset value is used.

Independent-L/R Poisson convolution reverb

The reverb is stereo because the left and right channels receive different independently generated impulse responses. It is not four-IR true-stereo convolution.

Left IR

A Poisson point process is converted to a pulse-train Sound, multiplied by an exponential decay and a mild sinusoidal/chirp modulation, convolved with the left dry channel, then Hann-band filtered.

Right IR

The right process is deliberately decorrelated: IR duration is 0.93×, density 0.95×, decay base 0.95×, and the pulse-train and modulation/filter constants differ slightly from the left side.

Wet scaling and mix

The two wet channels are scaled jointly using the larger of their peaks, so their relative left/right level is preserved. They are then mixed with the corresponding extended dry channels according to Wet mix. A final cosine fade is applied over the requested Fadeout duration.

Preset values

Custom uses the Details-page values. With selected-Sound analysis, the chosen preset still sets density, low cutoff, smoothing and fadeout, but the analyzed high cutoff, wet mix, decay base, tail and IR duration are restored afterward.

Controls

Main page

Reverb / Render Details

Validation and runtime guards

Core parameter ranges

• Duration: >0 to 120 s.
• Internal rate: 8000–96000 Hz.
• Final rate: 8000–192000 Hz.
• Transpose: −12 to +12 semitones.
• Poisson density: >0 to 20000 events/s before preset/analysis overrides.
• Wet mix: 0–100%.
• Output peak: >0 to 1.
• Random seed: 0 or positive.

Waveguide temporal-resolution guard

The highest possible string in the active SATB ranges is checked before rendering. The check includes the maximum +2.5 Hz outer-string detune and requires at least eight Internal-rate samples per string period:

If the condition fails, the script prints the minimum required Internal rate and exits. The v2.4.2 default of 12000 Hz was chosen specifically to cover the legitimate single-anchor analysis path that can shift the soprano range as high as MIDI 90.

Soundboard-rate guard

After Randomize depth has produced the actual eight body-mode frequencies, the highest mode must remain below 45% of Internal rate.

Final reverb workload guards

Version 2.4.1 added workload checks after all preset and analysis overrides, but before allocating the tail or IR Sounds:

If a Custom configuration exceeds a limit, the script exits with an approximate maximum Tail duration, Impulse duration, or Density appropriate to the current render rate.

Duration and normalization

Internal dry stage

After the soundboard model, the internal mono signal is peak-scaled to .88, then receives an approximately 60 ms linear fade-out before Sound creation and resampling.

Final duration

The dry stereo chord is extended by Tail duration before convolution. The final result is trimmed to:

Final stereo normalization

After left/right wet+dry mixing and fadeout, the two channels are combined to stereo and one final:

This is joint stereo target normalization. It does not normalize left and right independently, so the spectral split and reverb balance are preserved. It is also not a down-only ceiling: a non-silent output can be raised or lowered to reach the requested peak.

Visualization and QC

Version 2.4 replaces the old decorative two-panel display with a process-oriented visualization.

A — SATB string realization

Shows the four realized voices and their string geometry, including hammer/strike position, pickup position, strings-per-note and detune.

B — Representative waveguide loop

Uses the realized Tenor as a representative loop and displays target period, phase-compensated core delay, damping, stiffness and feedback.

C — Exact soundboard transfer model

Plots the normalized frequency response of the actual eight randomized resonators and marks their realized mode frequencies.

D — Realized Poisson reverb

Shows the left IR decay reference together with a decimated display of actual generated Poisson event times. The text reports actual L/R event counts, target density, Decay base and Wet percentage.

E — Measured stereo output

Draws the final left and right waveforms on the same −1…1 amplitude scale and reports measured peak, RMS and Final output rate.

QC strip

The bottom strip summarizes the realized chord, Internal rate and maximum predicted tuning error, eight-mode body amount, reverb preset/wet percentage, stereo architecture, Random seed and measured final peak.