# Delays and reverbs

> Build echoes, parallel alignment, modulation-ready delay lines and reverberation.

Canonical: https://maru.audio/docs/dsp-delays-and-reverbs
Documentation index: https://maru.audio/llms.txt

A delay stores earlier samples; feedback writes part of the delayed signal
back into the line. Reverb combines delays, filters and diffusion into a tail.
The toolkit offers small line primitives and complete stereo structures so
you can choose the amount of composition your product needs.

## Choose the time structure

| Need | Start with | Why |
| --- | --- | --- |
| Exact parallel alignment | `delays/alignment` | Whole frames, no interpolation, clipping or feedback. |
| Short movable read time | `delays/fractional` | Fractional reads for modulation; prepare capacity first. |
| Repeating echo | `delays/feedback`, `delays/saturated-feedback` | Explicit regeneration, with optional coloured feedback. |
| Alternating stereo repeats | `delays/ping-pong`, `delays/cross-feed` | Choose strict alternating repeats or flexible cross-feed. |
| Rhythmic taps or reverse windows | `delays/tap-pattern`, `delays/reverse-delay` | Prepared rings plus the selected tap/window policy. |
| Algorithmic space | `reverbs/stereo-room-fdn`, `reverbs/stereo-dattorro`, `reverbs/stereo-schroeder` | Stereo adapters with defined decay, predelay and control behavior. |
| Convolution room | `acoustics/room-convolver` | Play a prepared IR; see [room acoustics](https://maru.audio/docs/dsp-acoustics-and-models.md). |

## Storage and live changes

Prepare the maximum delay storage outside rendering. Read delay in samples or
milliseconds according to the setter; convert tempo divisions with
`control/musical-clock`. A nominal “delay” control is not a universal unit.
The basic fractional-delay leaf caps its non-feedback line at 50 ms and its
fractional-feedback line at 1000 ms; select another owner for a larger capacity.

Changing a read position immediately can click or change pitch. Use the leaf’s
slew, dual-read crossfade or staged transition where appropriate. Clearing a
large ring during a callback creates a work spike: use the staged-clear API
for live transitions, with a bounded shared budget.

Leaves named `borrowed-*` and several tap/pitch algorithms use caller-owned
rings. Their scalar reset and storage clear must happen together. A hall needs
at least sampleRate + two frames per borrowed ring; other leaves have their
own requirements. Do not assume that all delay/reverb APIs allocate their own
storage or mix in dry audio. True ping-pong and the stereo reverb adapters
listed as wet-only need an explicit product mix.

## Check tails and parallel paths

Decide whether bypass preserves a tail, fades it or clears it. Test feedback,
maximum decay and repeated changes for finite output and adequate headroom.
Use exact alignment for delayed parallel dry/wet paths, and check Haas widening
in mono. A decay parameter describes the algorithm’s law; it does not establish
that the result reproduces a measured room or spring tank.

## Toolkit reference

Import paths below are suffixes of `maruaudio/dsp/`. Use the exported types
and setters in your installed version for complete signatures and defaults.

### Delays

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `delays/cross-feed` | Stereo delay with same-side/cross-side feedback, tone filtering, modulation, read-time crossfades and feedback saturation. | `initCrossFeedDelayNode`, `crossFeedDelayNodeTick` |
| `delays/fractional` | Fractional delay and feedback delay with linear interpolation and prepared ring storage. | `initFractionalFeedbackDelayNode`, `fractionalFeedbackDelayNodeTick` |
| `delays/saturated-feedback` | Tape-style feedback delay with damping, soft clipping and dry/wet mixing. | `initSaturatedFeedbackDelayNode`, `saturatedFeedbackDelayNodeTick` |
| `delays/ping-pong` | True ping-pong delay: two cross-feeding fixed lines producing structurally alternating L/R repeats, 100% wet. | `initPingPongDelayNode`, `setPingPongFeedback` |
| `delays/primitives` | Milliseconds-to-frames, dry/wet and bounded feedback-write helpers. | `delayFrameCount`, `delayDryWetMix` |
| `delays/feedback` | Fixed feedback delay over a prepared line with a bounded active length. | `initFeedbackDelayNode`, `feedbackDelayNodeTick` |
| `delays/bounded` | Non-regenerating fixed delay: the feedback delay's sibling, writing through the same bounded store with the regeneration term exactly zero so all three delay behaviors share one implementation. | `initBoundedDelayNode`, `boundedDelayNodeTick` |
| `delays/alignment` | Exact whole-frame alignment without clipping, interpolation or feedback; preserves over-unity dry carriers for parallel effects. | `initAlignmentDelay`, `alignmentDelayTick` |
| `delays/pcm16-interpolated` | Firmware-derived stereo delay with PCM16 storage and interpolated reads. | `initPcm16InterpolatedDelay`, `pcm16InterpolatedDelayTickWritePointer` |
| `delays/pcm16-ping-pong` | Firmware-derived PCM16 ping-pong delay with glided time/feedback and its variant-specific dry/wet law. | `initPcm16PingPongNode`, `pcm16PingPongNodeTick` |
| `delays/clocked-glitch` | Clocked stereo delay with seeded retrigger/reverse/pitch/pan changes, crossfades and a frozen-loop buffer. | `initClockedGlitchDelay`, `clockedGlitchDelayTick` |
| `delays/tap-pattern` | Four-tap, Haas and damped feedback-comb compositions over caller-owned stereo rings. | `initTapPattern`, `tapPatternTick` |
| `delays/reverse-delay` | Windowed reverse delay over caller-owned stereo rings with edge fades. | `initReverseDelay`, `reverseDelayTick` |

### Reverbs

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `reverbs/schroeder` | Four-comb/two-allpass Schroeder/Freeverb network with damping and full-tail reset. | `initReverbNode`, `reverbNodeTick` |
| `reverbs/dattorro` | True-stereo Dattorro diffusion/tank reverb. | `initDattorroNode`, `dattorroNodeTick` |
| `reverbs/stereo-room-fdn` | Wet-only stereo four-line FDN with physical decay time, live room-size slew and bounded staged clearing. | `initStereoRoomFdnNode`, `stereoRoomFdnNodeTick` |
| `reverbs/stereo-dattorro` | Wet-only Dattorro adapter with bounded live predelay and normalized decay/damping controls. | `initStereoDattorroNode`, `stereoDattorroNodeTick` |
| `reverbs/stereo-schroeder` | Wet-only dual-core Schroeder adapter with explicit right-channel decorrelation and bounded live predelay. | `initStereoSchroederNode`, `stereoSchroederNodeTick` |
| `reverbs/griesinger` | Firmware-derived Griesinger figure-eight reverb with input diffusion, selectable storage precision and a freeze variant. | `initGriesingerReverb`, `griesingerReverbTick` |
| `reverbs/borrowed-spring` | Dispersive spring-style waveguide with coupled caller-owned delay loops. | `initBorrowedSpring`, `borrowedSpringTick` |
| `reverbs/borrowed-hall-fdn` | Hall feedback-delay network over caller-owned delay storage. | `initBorrowedHallFdn`, `borrowedHallFdnTick` |

Return to [DSP fundamentals](https://maru.audio/docs/dsp-fundamentals.md) for I/O, lifecycle,
units and the category map.