Karplus-Strong Modulator — User Guide

A continuously excited Karplus–Strong-style feedback resonator that uses the selected Sound as the excitation source, with optional sinusoidal modulation of the tuned resonance.

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

Contents:

What this does How it works Presets Parameters Channels & output Visualization

What this does

Karplus-Strong Modulator turns the selected Sound into the continuous excitation of a tuned feedback resonator. The resonator feeds earlier output samples back into the current sample through the classic two-sample averaging loss filter, producing pitched ringing whose center frequency is set by KS base frequency.

The resonant frequency can remain static or move continuously under a sinusoidal control expressed in semitones. Because the source keeps exciting the loop throughout the recording, the result follows the timing and activity of the original material while adding a tuned, decaying resonance around it.

Core idea: every output sample contains the current input sample plus a decayed, filtered contribution from the resonator's own earlier output. This makes the processing a true causal feedback system rather than a bank of delayed copies.

KS Mix controls how much of that resonant feedback is added. The direct source remains at unity gain: at 0 the result is an exact dry bypass; at higher values progressively more of the feedback resonance is heard.

How it works

1. The source continuously excites the loop

The selected Sound is copied to the output object and remains unchanged as the excitation source. Processing then proceeds causally through the output from earlier to later samples.

For each output channel: wet[t] = input[t] + decay × ( wet[t − D] + wet[t − D − 1 sample] ) / 2

The average of two adjacent delayed samples is the Karplus–Strong loss filter. It damps high frequencies on every trip through the loop, so the feedback does not behave like an undamped digital echo.

2. Resonance tuning

For a requested target frequency f, the nominal round-trip delay is approximately 1/f. The two-sample averaging filter contributes about an additional half-sample of phase delay, so v0.4 compensates for it in the explicit delay:

explicit delay = 1 / target_frequency − 0.5 × sample_period

This half-sample correction keeps the feedback resonance closer to the requested frequency than an uncompensated delay would.

3. Optional sinusoidal frequency modulation

When both modulation rate and depth are non-zero, the target resonance follows:

target_frequency(t) = base_frequency × 2 ^ [ depth_semitones × sin(2π × rate × local_time) / 12 ] delay(t) = 1 / target_frequency(t) − 0.5 × sample_period

The LFO uses local Sound time: its phase begins from the start of the selected Sound rather than from the Sound's absolute position on the Praat time axis. Moving an otherwise identical Sound to a different xmin therefore does not change the modulation trajectory.

Dynamic modulation is calculated once in a shared mono control Sound and reused by every audio channel. If the modulation rate is 0 Hz, or the depth is effectively zero, the script switches to a constant-delay fast path.

4. Mix behavior

final = mix × wet + (1 − mix) × input because wet = input + feedback: final = input + mix × feedback

This is an important property of the implementation: KS Mix scales the added resonant contribution. It does not attenuate the direct source as the value rises.

5. Output safety

After processing, the script measures the absolute peak. If processing is active, Safety peak is above 0, and the output exceeds that ceiling, Praat scales the Sound down to the requested ceiling. Quiet material is never boosted.

Safety peak is attenuation-only. It is not target normalization. A result whose peak is already below the ceiling keeps its existing level.

Presets

Preset selection replaces the resonator, modulation, feedback, and mix values shown in the Custom fields.

Preset	Base	Mod rate	Depth	Decay	Mix
Custom	form value	form value	form value	form value	form value
Deep Bass Pluck	80 Hz	0.2 Hz	1.0 st	0.85	0.60
Sci-Fi Siren	440 Hz	0.3 Hz	12 st	0.96	0.50
Metallic Chime	880 Hz	6.0 Hz	0.5 st	0.99	0.40
Warp Drive Engine	150 Hz	8.0 Hz	24 st	0.92	0.80

Preset names describe intended processing characters; the actual result still depends strongly on the spectrum, transients, level, and duration of the selected source.

Parameters

Parameter	Default	What it controls	Runtime handling
KS base frequency Hz	220	Nominal resonance frequency before modulation.	Clamped to 0.001 Hz … 0.49 × sample rate.
KS mod rate Hz	0.5	Sinusoidal resonance-motion rate.	Negative values are clamped to 0. At 0, the resonator is static.
KS mod depth semitones	12	Peak excursion above and below the base frequency on a musical ratio scale.	Sign is preserved; magnitude is reduced automatically if necessary so the highest target remains below 0.49 × sample rate.
KS decay	0.95	Feedback coefficient applied once per loop traversal.	Clamped to 0 … 0.9999.
KS mix	0.5	Amount of resonant feedback added to the full-level source.	Clamped to 0 … 1. A value of 0 is an exact bypass.
Safety peak	0.99	Maximum permitted processed-output peak.	Clamped to 0 … 1. 0 disables safety scaling. It never boosts.
Draw visualization	yes	Draw the AudioTools analysis/processing figure.	Does not change the audio.
Play result	yes	Play the processed Sound after completion.	Does not change the audio.

Frequency range created by modulation

minimum target = base × 2^(−|depth| / 12) maximum target = base × 2^(+|depth| / 12)

The script reports this resolved target range in the Info window and uses the same range for the visualization.

Channels & output

Every source channel is processed independently by the same feedback-resonator settings. The dynamic delay trajectory is shared across channels, but each channel feeds back its own previous output samples; channels are not summed or cross-fed.

Property	Behavior
Channel count	Preserved, including multichannel Sounds.
Sample rate	Preserved.
Duration / sample count	Preserved.
Start time	Preserved.
Randomness	None. Processing is deterministic for the same source and settings.
Mix = 0	Exact copied bypass; Safety peak is deliberately skipped.
Output safety	Attenuation only when the active result exceeds Safety peak.

The feedback memory is the output Sound itself. Praat evaluates a Sound formula from the first column toward later columns, so delayed references to earlier times read samples that have already been processed. This is what makes the loop causal and recursive.

Visualization

When Draw visualization is enabled, v0.4 creates an AudioTools figure with four main information areas:

Input / Output

Side-by-side waveforms of the original Sound and the final processed Sound.

Target resonance

The resolved resonance-frequency trajectory over the first up to 3 seconds. A dotted horizontal reference marks the base frequency.

Tuned feedback delay

The actual explicit delay trajectory in milliseconds after the half-sample tuning correction.

Summary

Base frequency, modulation rate/depth, loop decay, wet value, target range, safety ceiling, duration, sample rate, and channel count.

The two trajectory panels are control displays. They show the resonator target and its compensated delay; they are not measurements extracted from the output audio.

Practical reading of the controls

Base frequency establishes the tuned feedback-loop region.
Decay controls how much of each previous loop traversal survives into the next one.
Mod depth determines the frequency-ratio excursion around the base; Mod rate determines how quickly that excursion cycles.
Mix determines how much feedback resonance is added while leaving the direct source present.
Transient-rich material can excite clearly articulated ringing, while sustained or dense material continuously drives the loop and can produce a more persistent resonant texture.