Saturation¶

Saturation, distortion, and antialiased waveshaping.

Usage examples¶

Basic saturation¶

from nanodsp.effects import saturation
from nanodsp.buffer import AudioBuffer

buf = AudioBuffer.from_file("input.wav")

# Soft saturation (tanh) -- warm, symmetrical
warm = saturation.saturate(buf, drive=0.5, mode="soft")

# Hard clipping -- harsh, buzzy
hard = saturation.saturate(buf, drive=0.7, mode="hard")

# Tape saturation -- asymmetric, adds even harmonics
tape = saturation.saturate(buf, drive=0.4, mode="tape")

Antialiased waveshaping¶

These use antiderivative antialiasing (ADAA) to suppress aliasing artifacts that occur with naive waveshaping:

# Antialiased hard clipper (clean even at high drive)
clipped = saturation.aa_hard_clip(buf, drive=3.0)

# Antialiased soft clipper (sin-based saturation)
soft = saturation.aa_soft_clip(buf, drive=2.0)

# Antialiased wavefolder (Buchla 259 style, 2nd-order ADAA)
folded = saturation.aa_wavefold(buf, drive=4.0)

Comparison: naive vs. antialiased¶

# Naive hard clip introduces aliasing at high drive
naive = saturation.saturate(buf, drive=0.9, mode="hard")

# Antialiased version is much cleaner
clean = saturation.aa_hard_clip(buf, drive=10.0)

API reference¶

saturation ¶

Saturation and antialiased waveshaping.

saturate ¶

saturate(
    buf: AudioBuffer,
    drive: float = 0.5,
    mode: Literal["soft", "hard", "tape"] = "soft",
) -> AudioBuffer

Apply saturation/distortion.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`drive`	Drive intensity, 0.0 to 1.0 (maps to gain 1x-10x). TYPE: `float` DEFAULT: `0.5`
`mode`	Saturation type: 'soft' (tanh), 'hard' (clip), or 'tape' (asymmetric). TYPE: `str` DEFAULT: `'soft'`

RETURNS	DESCRIPTION
`AudioBuffer`	Saturated audio.

aa_hard_clip ¶

aa_hard_clip(
    buf: AudioBuffer, drive: float = 1.0
) -> AudioBuffer

Antialiased hard clipper using 1st-order antiderivative method.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`drive`	Input gain multiplier before clipping, > 0. 1.0 = unity; higher values push the signal harder into the clipper. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`AudioBuffer`	Clipped audio.

aa_soft_clip ¶

aa_soft_clip(
    buf: AudioBuffer, drive: float = 1.0
) -> AudioBuffer

Antialiased soft clipper (sin-based saturation) with 1st-order AA.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`drive`	Input gain multiplier before saturation, > 0. 1.0 = unity. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`AudioBuffer`	Saturated audio.

aa_wavefold ¶

aa_wavefold(
    buf: AudioBuffer, drive: float = 1.0
) -> AudioBuffer

Antialiased wavefolder (Buchla 259 style) with 2nd-order AA.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`drive`	Input gain multiplier before folding, > 0. 1.0 = unity; values > 1 create additional folds. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`AudioBuffer`	Wavefolded audio.