# Modulation and distortion

> Shape control motion, pitch motion, nonlinear colour and reduced-resolution textures.

Canonical: https://maru.audio/docs/dsp-modulation-and-distortion
Documentation index: https://maru.audio/llms.txt

Modulation changes a signal or control over time. Distortion changes the
amplitude transfer, adding harmonics and colour. Combine the shared motion,
filtering and nonlinear stages to make a tremolo, animated filter, tape echo,
drive pedal or reduced-resolution texture.

## Separate control motion from audio effects

`modulation/lfo` generates a waveform; `modulation/slew` smooths a changing
value. They do not by themselves process your audio. Tremolo changes amplitude,
vibrato changes delay/pitch, chorus combines detuned delay with dry material,
and phaser mixes an allpass network with the original signal.

For paired mono effects, prepare separate channel histories and use the
provided phase-offset controls if you want related stereo motion. Stereo
adapters supply their own defined relationship. Advancing one shared LFO once
per channel doubles its rate; advance it once per frame and reuse its output.

## Choose the nonlinear stage

| Sound | Start with | Integration choice |
| --- | --- | --- |
| Immediate soft drive | `distortion/direct-overdrive`, `distortion/tone-shape` | Simple transfer; add product tone/mix/trim as needed. |
| Oversampled shaping | `distortion/drive`, `distortion/oversampled-waveshaper`, `distortion/chebyshev` | Fixed 4× stages; account for their filter histories/alignment. |
| Folded or clipped colour | `distortion/wavefolder`, `distortion/color-shaper` | Hard corners add high-frequency energy; audition at high pitch/drive. |
| Complete voiced stage | `distortion/voiced-overdrive`, `distortion/voiced-wavefolder` | Shared shaping with tone/DC treatment and output trim. |
| Tape or amp character | `distortion/taper`, `distortion/classic-amp` | Multi-stage composition rather than one transfer curve. |
| Coarse digital texture | `distortion/bitcrusher`, `distortion/decimator`, `distortion/sample-rate-reducer` | Different hold, quantization and smoothing laws. |

A normalizer or hard clip is not a substitute for choosing headroom. Compare
at matched output levels and test sustained, transient and silent input.
Raw wavefold offsets can create DC; the voiced adapter includes DC removal.
`triode-stage` prepares a static transfer table, rather than solving a complete
dynamic amplifier circuit in the callback. A sample-rate reducer creates a
sound at the existing host rate; it does not change the host’s processing rate.

Physical controls and normalized product macros are different. Map the schema
value into Hz, dB, seconds or the documented ratio before calling a leaf.
The [DSP overview](https://maru.audio/docs/dsp.md#effect-apis-and-operating-limits) gives ranges
and storage notes for the newer effect profiles.

## 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.

### Modulation

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `modulation/flanger` | Short sine-modulated fractional delay with signed feedback, phase-locked stereo support, and staged lifecycle clearing. | `initFlangerNode`, `flangerNodeTick` |
| `modulation/tremolo` | Sine amplitude modulation with depth and phase offset; does not amplify above the dry peak by its modulation law. | `initTremoloNode`, `tremoloNodeTick` |
| `modulation/vibrato` | Fully wet sine-swept fractional-delay vibrato state, DelayNode-ordered tick and fresh-instance-identical reset semantics. | `initVibratoNode`, `vibratoNodeTick` |
| `modulation/lfo` | Audio-rate low-frequency oscillator producing offset + depth * wave over the shared voice oscillator stages, so an LFO wave and an audio wave are the same curve at different rates. | `initLfoNode`, `lfoNodeTick` |
| `modulation/chorus` | Mono chorus: a sine-modulated bounded fractional delay over the fractional-delay line, with optional regeneration, a dry/wet mix and a degrees-authored static LFO rotation for phase-locked stereo fields. | `initChorusNode`, `chorusNodeTick` |
| `modulation/phaser` | Four swept first-order allpass sections summed against dry, with a live relative phase-offset control for paired stereo lanes; four f32 histories are allocated once at initialization. | `initPhaserNode`, `phaserAllpassStageTick` |
| `modulation/stereo-ring-modulator` | Stereo ring modulation with related carrier frequencies and phase. Multiplication produces sidebands; carrier band-limiting does not remove all aliasing. | `initStereoRingModulatorNode`, `stereoRingModulatorNodeTick` |
| `modulation/glide` | Amplitude-dependent pitch glide as a per-quantum frequency multiplier: the Duffing-backbone initial detune, the reciprocal per-mode falloff, the one-pole envelope coefficient/step and the settled-glide activity test. | `glideInitialDetune`, `glideModeFalloff` |
| `modulation/slew` | Shared one-pole parameter smoothing and bounded scalar slew limiter for click-sensitive controls such as delay read positions. | `onePoleSmoothingCoefficient`, `onePoleSmoothingStep` |
| `modulation/stereo-auto-panner` | Shared sine-LFO motion of a stereo input through the constant-power stereo pan law; exact identity at zero depth | `initStereoAutoPannerNode`, `stereoAutoPannerNodeTick` |
| `modulation/auto-panner` | Mono-to-stereo equal-power sine auto-pan with prepared oscillator state. | `initAutoPannerNode`, `autoPannerNodeTick` |
| `modulation/retune` | Pitch-correction control: retune speed, amount, humanize, transition dwell, unvoiced hold and delayed vibrato to a per-sample shift ratio. | `initRetune`, `retuneTick` |
| `modulation/f32-slew` | DaisySP one-pole and stmlib asymmetric rise/fall control smoothing with float32 arithmetic. | `f32OnePoleStep`, `f32AsymmetricSlewStep` |
| `modulation/warble` | Firmware-derived seeded tape-wow motion over paired interpolated delay lines. | `initWarbleNode`, `warbleNodeTick` |
| `modulation/borrowed-rotary` | Two-rotor speaker approximation with independent motor inertia and caller-owned Doppler rings. | `initBorrowedRotary`, `borrowedRotaryTick` |

### Distortion

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `distortion/bitcrusher` | Sample-rate and bit-depth reducer: anti-imaging one-pole, held-sample phase accumulator, quantization steps, boost and dry/wet with boost compensation. | `initBitcrusherNode`, `bitcrusherNodeTick` |
| `distortion/decimator` | Wet-only DaisySP Decimator port: raw sample-and-hold cadence and defined fixed-point bit clearing without filtering or added latency. | `initDecimatorNode`, `decimatorNodeTick` |
| `distortion/chebyshev` | Chebyshev first-kind polynomial waveshaper over the shared fixed-4x oversampled interpolation and FIR decimation stage. | `initChebyshevNode`, `chebyshevNodeTick` |
| `distortion/drive` | Fixed-4x rational-drive transfer, FIR state, tick and reset semantics. | `initDriveNode`, `driveNodeTick` |
| `distortion/oversampled-waveshaper` | Fixed 4× oversampled nonlinear transfer with prepared FIR histories. | `initOversampledWaveshaperNode`, `oversampledWaveshaperNodeTick` |
| `distortion/taper` | Tape processor: nine-control cook, companding encode/decode, flutter fractional delay, bias slew, mid/sub split, head-bump resonators and stereo soft clip. | `initTaperNode`, `taperNodeTick` |
| `distortion/direct-overdrive` | Direct zero-latency DaisySP overdrive with bounded drive-dependent gain and soft clipping. | `initDirectOverdriveNode`, `directOverdriveNodeTick` |
| `distortion/tone-shape` | Bounded rational drive transfer with silence gating. | `initDistortionNode`, `distortionNodeTick` |
| `distortion/voiced-overdrive` | Wet voiced drive composing transfer, input low-cut, tone filtering and output trim. | `initVoicedOverdriveNode`, `voicedOverdriveNodeTick` |
| `distortion/wavefolder` | DaisySP periodic triangular wavefold with signed pre-gain and offset; raw offset can produce DC and the fold intentionally aliases. | `initWavefolderNode`, `wavefolderNodeTick` |
| `distortion/voiced-wavefolder` | Wet wavefolder composed from the Daisy fold, post-fold RBJ DC blocker, ToneFilter and output trim. | `initVoicedWavefolderNode`, `voicedWavefolderNodeTick` |
| `distortion/rational-soft-clip` | Rational soft-limit curve x(27 + x²)/(27 + 9x²), plus its ±3-bounded soft-clip variant. | `rationalSoftLimit`, `rationalSoftClip` |
| `distortion/sample-rate-reducer` | Fractional sample-rate reduction with interpolated crossings and PolyBLEP step smoothing; ratio is relative to host rate. | `initSampleRateReducerNode`, `sampleRateReducerTick` |
| `distortion/triode-stage` | Bounded static triode load-line solver and prepared tone/DC filtering. | `initTriodeStage`, `triodeStageTick` |
| `distortion/octave-divider` | Thresholded zero-crossing octave divider with envelope, tone and DC filtering. | `initOctaveDivider`, `octaveDividerTick` |
| `distortion/jitter-reducer` | Deterministic sample-and-hold reducer with sampling-clock jitter. | `initJitterReducer`, `jitterReducerTick` |
| `distortion/color-shaper` | Wet hard clipping, asymmetric saturation and rectification with tone/DC filtering. | `initColorShaper`, `colorShaperTick` |
| `distortion/classic-amp` | Pre-cabinet amp voice: high-pass/pre-emphasis, 4× oversampled preamp/power shaping and three-band tone stack. | `initClassicAmpStage`, `classicAmpStageTick` |

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