Skip to content

Waveguide

Tier: Primitives | ComponentType: 40 | Params: 9

Bidirectional delay line physical model with reflective boundaries and Friedlander bow friction.

Overview

The Waveguide models a vibrating string as two opposing traveling wave delay lines (forward and backward) with configurable reflection boundaries at each end. Unlike Karplus-Strong's single delay loop, the bidirectional topology accurately simulates standing waves, supports continuous excitation via bowing, and allows independent control of each string termination.

Each boundary has its own reflection coefficient (controlling energy return) and one-pole lowpass filter (simulating frequency-dependent absorption). The Friedlander bow friction model enables sustained tones by injecting energy through a nonlinear stick-slip interaction between bow and string.

File Locations

Path
Header Sources/FolioDSP/include/FolioDSP/Primitives/Waveguide.h
Implementation Sources/FolioDSP/src/Primitives/Waveguide.cpp
Tests Tests/FolioDSPTests/WaveguideTests.swift
Bridge Sources/FolioDSPBridge/src/FolioDSPBridge.mm (WaveguideBridge)

Parameters

Index Name Description Min Max Default Min Default Max Default Unit
0 Frequency Fundamental frequency of the string 20.0 8000.0 60.0 2000.0 220.0 Hz
1 Left Reflect Left boundary reflection coefficient (-1=rigid, 0=open) -1.0 1.0 -1.0 1.0 -1.0
2 Right Reflect Right boundary reflection coefficient -1.0 1.0 -1.0 1.0 -1.0
3 Left Filter Left boundary absorption filter cutoff 20.0 20000.0 200.0 15000.0 5000.0 Hz
4 Right Filter Right boundary absorption filter cutoff 20.0 20000.0 200.0 15000.0 5000.0 Hz
5 Decay Energy loss per cycle 0.9 1.0 0.99 1.0 0.998
6 Excite Position Where along the string excitation is injected (0–1) 0.0 1.0 0.0 1.0 0.5
7 Bow Velocity Speed of the virtual bow (-1 to +1) -1.0 1.0 -1.0 1.0 0.0
8 Bow Force Pressure of the bow against the string 0.0 1.0 0.0 1.0 0.0

Processing Algorithm

1. Half-Delay Calculation

\[d_{\text{half}} = \frac{f_s}{2f}\]

Two 2048-sample delay lines represent forward and backward traveling waves. The round-trip period is \(2 \cdot d_{\text{half}}\).

2. Read from Both Lines

\[f_{\text{out}} = \text{forward}[\text{write}_f - d_{\text{half}}]\]
\[b_{\text{out}} = \text{backward}[\text{write}_b - d_{\text{half}}]\]

3. Boundary Reflection

Each boundary applies a one-pole LP filter and reflection coefficient:

\[\text{filt}_R \mathrel{+}= (1 - c_R)(f_{\text{out}} - \text{filt}_R)\]
\[r_R = \text{filt}_R \cdot R_{\text{coeff}} \cdot \text{decay}\]

Similarly for the left boundary on the backward wave.

4. Bow Friction (Friedlander Model)

\[v_{\text{string}} = f_{\text{out}} - b_{\text{out}}\]
\[\Delta v = v_{\text{bow}} - v_{\text{string}}\]
\[F = F_{\text{bow}} \cdot \Delta v \cdot e^{-3 \Delta v^2}\]

The exponential term creates stick-slip: maximum friction when \(\Delta v \approx 0\) (stick), exponential falloff during slip.

5. Write Back (asymmetric injection)

\[\text{forward}[\text{write}_f] = r_L + F + x\]
\[\text{backward}[\text{write}_b] = r_R - F + x\]

Bow force injects with opposite signs (+forward, -backward) to create traveling waves.

6. Output

\[y_{\text{raw}} = f_{\text{out}} + b_{\text{out}}\]

7. DC Blocker

\[y[n] = y_{\text{raw}}[n] - y_{\text{raw}}[n-1] + R \cdot y[n-1]\]

Core Equations

\[F = F_{\text{bow}} \cdot \Delta v \cdot e^{-3\Delta v^2}, \quad \Delta v = v_{\text{bow}} - (f_{\text{out}} - b_{\text{out}})\]

Snapshot Fields

Field Type Range Unit Description
Frequency Float 20–8000 Hz Current frequency
Left Reflect Float -1–1 Left reflection
Right Reflect Float -1–1 Right reflection
Decay Float 0.9–1.0 Current decay
Output Level Float 0–1 Smoothed output
Forward Energy Float 0–1 Forward wave energy
Backward Energy Float 0–1 Backward wave energy
Total Energy Float 0–1 Combined energy
Bowing Bool 0–1 Whether bow is active
Bow Velocity Float -1–1 Current bow speed
Bow Force Float 0–1 Current bow pressure
Ringing Bool 0–1 Whether string is sounding

Implementation Notes

  • Two 2048-sample delay lines (forward and backward) -- max half-delay supports frequencies down to ~10.7 Hz
  • Reflection coefficient -1.0 = rigid boundary (phase inversion, like a wall); 0.0 = open end (no reflection)
  • Bow friction K=3 provides realistic stick-slip behavior
  • Bow force MUST inject asymmetrically (+forward, -backward) to create traveling waves; equal injection creates DC that the DC blocker removes
  • Excitation via excite(amplitude, position) splits energy 50/50 into opposing traveling waves
  • ParamSmoother on all 9 parameters for stable real-time modulation

Equation Summary

F = bowForce·Δv·e^(-3·Δv²); bidir delay