Karplus-Strong Texture Generator — User Guide
An extended Karplus-Strong texture instrument with a fractional-delay feedback resonator at the voice level and a separate event scheduler for repeated plucks, Poisson streams, strums, cascades, drones, and spatial textures.
What this does
The generator has two independent levels:
Level 2 — texture scheduler: the script decides when KS events occur, what pitches they use, how long their modeled tails are allowed to ring, and how the events are mixed and spatialized.
This distinction matters: Texture mode does not change the basic feedback algorithm. It changes the schedule of individual KS voices. Conversely, Damping, Brightness, and Excitation fill change each resonator even when the event schedule stays the same.
The implementation is Karplus-Strong / digital-waveguide-like rather than a complete physical model of a string. It does not simulate string stiffness and dispersion, body resonances, pickup position, bridge nonlinearity, or instrument radiation.
Quick start
- Run
Karplus-Strong_Texture_Generator.praat. No input Sound is required. - Choose Custom or one of the nine presets.
- For Custom, set Duration, Sample rate, Base pitch, Texture mode, Damping, Brightness, Excitation fill, and Spatial mode.
- Open Edit texture details for event rate, voice count, pitch span/jitter, strum span, tail cap, stereo detune, micro-delay, and Random seed.
- Leave Peak protection on if you want only excessive peaks reduced to 0.92. This is not normalization.
Important: a non-Custom preset overrides the relevant main-form and advanced values after the form is submitted. The exact overrides are listed below.
The Karplus-Strong voice
Each event starts with a short white-noise section inside the initial delay buffer. After that excitation, the Sound is generated recursively from earlier samples. The loop combines two simple filters:
B(z) = (1 - S) + S z^-1 S = 0.5 × (1 - Brightness) F(z) = (1 - r) + r z^-1
B(z) controls brightness loss. At Brightness = 0, S = 0.5, giving the classic two-point averaging behavior. At Brightness = 1, S = 0, so that additional averaging loss disappears.
F(z) is an independent linear fractional-delay interpolator. Cascading the two filters gives a compact three-tap recurrence:
y[n] = Damping × (
a0 y[n-N]
+ a1 y[n-N-1]
+ a2 y[n-N-2])
a0 = (1-S)(1-r)
a1 = (1-S)r + S(1-r)
a2 = Sr
Pitch calculation
The script does not simply round Fs / pitch. It estimates the low-frequency phase delay contributed by the brightness filter and puts the remaining fractional delay into the interpolator:
N + r + S ≈ Fs / requestedPitch
This substantially reduces the pitch change that would otherwise occur when Brightness changes. It is still an approximate low-frequency tuning compensation, not an exact physical-string tuning law at every frequency.
Excitation fill
Excitation fill controls how much of the initial delay buffer contains random excitation. A value of 1.0 is closest to the classic fully randomized initial buffer. Smaller values excite only the first part of the buffer and leave the remainder initially at zero.
This parameter is deliberately described as buffer fill, not literal pluck position: the implementation does not model the spatial position at which a real string is plucked.
Main controls
| Control | Range / default | Meaning |
|---|---|---|
| Preset | Custom + 9 presets | Selects either manual control or a complete mechanism-oriented setup. |
| Duration | default 6 s; max 120 s | Exact final Sound duration. Event tails are clipped at the end of this duration. |
| Sample rate | 8–192 kHz; default 44.1 kHz | Direct synthesis and final output sample rate. |
| Base pitch | minimum 20 Hz; default 220 Hz | Reference pitch used directly or as the center of the texture's pitch distribution. |
| Texture mode | 6 modes | Controls event scheduling; it does not replace the KS resonator. |
| Damping | 0–1, exclusive; default 0.996 | Round-trip feedback multiplier. Values closer to 1 give slower decay. The script requires Damping < 1. |
| Brightness | 0–1; default 0.35 | Controls the extra averaging loss in the loop. Lower values suppress high-frequency loop energy more strongly. |
| Excitation fill | >0–1; default 1.0 | Fraction of the initial delay buffer filled with white-noise excitation. |
| Spatial mode | 4 modes | Mono, event spread, correlated detuned pair, or micro-delay stereo. |
| Peak protection | on by default | Down-only peak reduction to 0.92 when necessary. |
Texture modes
1. Single Pluck
One KS event starts at time 0 at exactly the Base pitch. Pitch span, pitch jitter, event rate, and voice count do not affect the schedule.
2. Regular Re-plucks
Events begin at time 0 and repeat at exactly 1 / Event rate. Each event receives independent pitch jitter and a small random weight variation.
3. Poisson Pluck Stream
Inter-onset intervals are exponentially distributed:
IOI = -ln(U) / EventRate
The first event therefore does not have to occur at time 0. Each event receives a random pitch across half the requested Pitch span above or below Base pitch, plus the separate cents-scale Pitch jitter.
4. Strummed Cluster
Voice/event count notes are spread across the Strum span. Their pitches move from half the Pitch span below Base pitch to half the span above it, with independent pitch jitter.
In v0.4.2 the effective strum span is:
actualStrumSpan = min(StrumSpan, Duration)
so no strummed onset is scheduled after the end of the Sound. This also keeps event-tail and overlap calculations valid for short Custom durations.
5. Ascending Cascade
Voice/event count events rise through the requested Pitch span. The cascade duration is derived from Event rate but is limited to 78% of the complete Sound, and the event weights increase gradually through the cascade.
6. Re-excited Drone
Repeated KS excitations begin at time 0 and continue at the requested Event rate. Each event remains near Base pitch with independent cents-scale pitch jitter. With a long Damping time, the overlapping decays create the sustained texture.
Event-count safety
Version 0.4.1 replaced the former silent 64-event truncation. Regular Re-plucks, Poisson Pluck Stream, and Re-excited Drone can now schedule up to 5000 events. If a requested Custom schedule would exceed that safety limit, the script stops with an explicit message instead of silently shortening the texture.
Texture / spatial details
| Control | Default | Use |
|---|---|---|
| Event rate | 2.0 events/s | Regular Re-plucks, Poisson Pluck Stream, Ascending Cascade timing, and Re-excited Drone. |
| Voice/event count | 7 | Number of events in Strummed Cluster and Ascending Cascade. |
| Pitch span | 12 semitones | Pitch range for Poisson, Strummed Cluster, and Ascending Cascade. |
| Pitch jitter | 4 cents | Independent random pitch offset used by every multi-event texture. |
| Strum span | 180 ms | Total onset spread of Strummed Cluster, capped by Duration in v0.4.2. |
| Maximum event tail | 6 s | Upper bound on each modeled KS event tail. |
| Stereo detune | 7 cents | Pitch offset of the right member in Stereo Detuned Pair. |
| Micro-delay | 8 ms | Right-channel delay in Stereo Micro-Delay. |
| Random seed | 0 | 0 = unpredictable; a positive seed reproduces stochastic schedules, pitch/weight variations, and excitation noise for the same settings. |
Tail estimation and overlap compensation
For every scheduled pitch, the script predicts the round-trip loop gain at the fundamental and converts that to an approximate T60. The event tail is then:
min( time remaining in the Sound, Maximum event tail, 1.05 × predicted fundamental T60 )
A minimum rendered tail of 0.20 s is used when enough output duration remains. Mixing gain is then compensated from the actual scheduled mean overlap:
meanOverlap = sum(event tails) / Duration eventMixGain = 0.72 / sqrt(max(1, meanOverlap))
This is an overlap-dependent gain heuristic, not loudness normalization.
Pitch headroom
The script limits the highest possible scheduled fundamental to 0.20 × Sample rate. Version 0.4.1 corrected this validation so it follows the actual scheduler:
- Single Pluck: Base pitch only.
- Regular Re-plucks / Re-excited Drone: Base pitch plus maximum Pitch jitter.
- Poisson / Strum / Cascade: Base pitch plus half Pitch span plus maximum Pitch jitter.
- Positive Stereo Detuned Pair offsets are included when they can raise the right-channel pitch.
This is a conservative validity check for the KS delay model. It should not be read as a statement that the output contains no spectral energy above 0.20 × Fs; a plucked-noise feedback loop naturally contains broadband and modal energy up to the digital Nyquist limit.
Presets
Non-Custom presets override the listed controls. Controls not listed retain their advanced defaults or the user's unaffected output options.
| Preset | Main overrides | Scheduler / spatial overrides |
|---|---|---|
| Canonical Single Pluck | 4 s; 220 Hz; Single Pluck; Damping .996; Brightness 0; Fill 1.0 | Mono; max tail 4 s |
| Warm Re-pluck Stream | 10 s; 110 Hz; Regular Re-plucks; Damping .995; Brightness .35; Fill .90 | 1.8 events/s; jitter 5 cents; Stereo Event Spread; max tail 4.5 s |
| Ascending String Cascade | 9 s; 220 Hz; Ascending Cascade; Damping .9975; Brightness .28; Fill 1.0 | 10 events; span 19 st; 1.5 events/s; jitter 2 cents; Stereo Event Spread; max tail 5 s |
| Long Metallic Pluck | 6 s; 330 Hz; Single Pluck; Damping .9993; Brightness .84; Fill .70 | Mono; max tail 6 s |
| Re-excited Low Drone | 14 s; 130 Hz; Re-excited Drone; Damping .9982; Brightness .32; Fill .85 | .72 events/s; jitter 2.5 cents; Stereo Detuned Pair; detune 3.5 cents; max tail 7 s |
| Bright Short Pluck | 3 s; 294 Hz; Single Pluck; Damping .990; Brightness .92; Fill .75 | Mono; max tail 3 s |
| Detuned Shimmer Pair | 8 s; 392 Hz; Single Pluck; Damping .9985; Brightness .42; Fill 1.0 | Stereo Detuned Pair; detune 8.6 cents; max tail 8 s |
| Prepared Detuned Cluster | 8 s; 185 Hz; Strummed Cluster; Damping .994; Brightness .55; Fill .62 | 8 events; span 9 st; strum 260 ms; jitter 8 cents; Stereo Event Spread; max tail 5 s |
| Sparse Resonant Cloud | 18 s; 261 Hz; Poisson Pluck Stream; Damping .9997; Brightness .22; Fill 1.0 | .42 events/s; span 7 st; jitter 14 cents; Stereo Micro-Delay; 11 ms delay; max tail 8 s |
Presets do not override Sample rate, Random seed, Peak protection, Draw visualization, or Play result unless explicitly listed in the script's preset block.
Spatial modes
| Mode | Implementation |
|---|---|
| Mono | All scheduled KS voices are summed into one channel. |
| Stereo Event Spread | Events are distributed from pan 0.05 to 0.95 by event index using equal-power gains sqrt(1-pan) and sqrt(pan). A single event is centered. |
| Stereo Detuned Pair | Each event creates two KS resonators. The right pitch is offset by Stereo detune cents. Both resonators use the same random excitation buffer, so the pair begins from correlated excitation rather than unrelated noise. |
| Stereo Micro-Delay | The original mono KS voice feeds the left channel immediately and the right channel after the requested delay. It does not recursively delay an already modified stereo channel. |
Mono creates a one-channel output. All three spatial modes create stereo. In Stereo Micro-Delay, the final Sound still has exactly the requested Duration, so a delayed right-channel tail that would extend beyond the end is truncated by the output boundary.
Output and level
| Property | Behavior |
|---|---|
| Input | No selected Sound is required. |
| Duration | Exactly the requested Duration. |
| Sample rate | Exactly the selected 8–192 kHz rate. |
| Channels | Mono for Mono spatial mode; stereo otherwise. |
| Voice edge | Each individual KS voice receives only a very short cosine taper at its final edge: at most 8 ms or 10% of that voice's rendered tail. |
| Peak protection | If enabled and the final mixed peak is above 0.92, Scale peak: 0.92 is applied once. |
| Normalization | No unconditional normalization. Signals at or below 0.92 retain their generated level. |
| Object name | KS_Texture_<preset name>; spaces are replaced by underscores. |
Visualization and QC
The Picture display is mechanism-focused and uses the actual schedule and measured output.
| Panel | What it shows |
|---|---|
| A — Actual Texture Schedule | Every scheduled event as onset + rendered tail at its actual fundamental pitch. Pitch is displayed on a logarithmic vertical coordinate. |
| B — Feedback Loop | Theoretical round-trip loop gain in dB/pass for the first event, including Damping, Brightness filter, and fractional-delay interpolator. Harmonic positions of the first event are overlaid as guides. |
| C — First Event Decay | Measured short-window RMS decay of the rendered first KS event compared with theoretical fundamental and fifth-partial decay slopes. |
| D — Texture → Measurement | Measured spectrogram of the final output with actual event-fundamental guides. |
For stereo output, Panel D analyzes whichever complete output channel has the higher RMS. Panel C uses a saved copy of the first rendered KS voice before it is mixed into the texture.
The QC strip reports the first event's integer delay N, fractional delay, brightness-filter delay S, three loop coefficients, predicted fundamental/fifth decay, fundamental T60, actual event count, mean overlap, overlap compensation gain, seed, pre/final peak, final RMS, synthesis time, and whether down-only peak protection was applied.
Further reading
These are the two directly relevant foundational sources cited by the script:
- Karplus, K., & Strong, A. (1983). “Digital Synthesis of Plucked-String and Drum Timbres.” Computer Music Journal, 7(2), 43–55. DOI: 10.2307/3680062.
- Jaffe, D. A., & Smith, J. O. (1983). “Extensions of the Karplus-Strong Plucked-String Algorithm.” Computer Music Journal, 7(2), 56–69. DOI: 10.2307/3680063.