Dynamics¶

Compression, limiting, noise gate, and automatic gain control.

Usage examples¶

Compression¶

from nanodsp.effects import dynamics
from nanodsp.buffer import AudioBuffer

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

# Gentle compression (4:1, -20 dB threshold)
compressed = dynamics.compress(buf, ratio=4.0, threshold=-20.0)

# Aggressive compression with fast attack
squashed = dynamics.compress(
    buf, ratio=8.0, threshold=-30.0, attack=0.001, release=0.05
)

# With makeup gain
loud = dynamics.compress(
    buf, ratio=4.0, threshold=-20.0, makeup=6.0
)

# Auto makeup gain
auto = dynamics.compress(
    buf, ratio=4.0, threshold=-20.0, auto_makeup=True
)

Limiting¶

# Brick-wall limiter
limited = dynamics.limit(buf, pre_gain=1.0)

# Boost into limiter for loudness
hot = dynamics.limit(buf, pre_gain=2.0)

Noise gate¶

# Gate signal below -40 dB
gated = dynamics.noise_gate(buf, threshold_db=-40.0)

# Tight gate for drums
tight = dynamics.noise_gate(
    buf, threshold_db=-30.0, attack=0.001, release=0.05, hold_ms=10.0
)

Automatic gain control¶

# Normalize speech to consistent level
level = dynamics.agc(buf, target_level=1.0, max_gain_db=60.0)

# Faster response for dynamic material
fast = dynamics.agc(buf, attack=0.005, release=0.005, average_len=50)

API reference¶

dynamics ¶

Dynamics -- compression, limiting, noise gate, AGC, sidechain, transient shaper, lookahead limiter.

compress ¶

compress(
    buf: AudioBuffer,
    ratio: float = 4.0,
    threshold: float = -20.0,
    attack: float = 0.01,
    release: float = 0.1,
    makeup: float = 0.0,
    auto_makeup: bool = False,
) -> AudioBuffer

Apply compression per channel.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`ratio`	Compression ratio, >= 1.0 (e.g. 4.0 = 4:1). Typical range: 2--20. TYPE: `float` DEFAULT: `4.0`
`threshold`	Threshold in dB, typically -60 to 0. TYPE: `float` DEFAULT: `-20.0`
`attack`	Attack time in seconds, > 0. Typical range: 0.001--0.1. TYPE: `float` DEFAULT: `0.01`
`release`	Release time in seconds, > 0. Typical range: 0.01--1.0. TYPE: `float` DEFAULT: `0.1`
`makeup`	Makeup gain in dB. Typical range: 0--30. TYPE: `float` DEFAULT: `0.0`
`auto_makeup`	If True, automatically compensate for gain reduction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`AudioBuffer`	Compressed audio.

limit ¶

limit(
    buf: AudioBuffer, pre_gain: float = 1.0
) -> AudioBuffer

Apply limiter per channel.

PARAMETER	DESCRIPTION
`buf`	Input audio. TYPE: `AudioBuffer`
`pre_gain`	Linear gain applied before limiting, > 0. 1.0 = unity. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`AudioBuffer`	Limited audio.

sidechain_compress ¶

sidechain_compress(
    buf: AudioBuffer,
    sidechain: AudioBuffer,
    ratio: float = 4.0,
    threshold: float = -20.0,
    attack: float = 0.01,
    release: float = 0.1,
) -> AudioBuffer

Compress buf using the envelope of sidechain as the detector.

The gain reduction is computed from the sidechain signal but applied to buf. Common use: duck a bass synth under a kick drum.

PARAMETER	DESCRIPTION
`sidechain`	Signal whose level drives the compressor. Must have the same frame count as buf. TYPE: `AudioBuffer`
`ratio`	Compression ratio, >= 1.0. Typical: 2--20. TYPE: `float` DEFAULT: `4.0`
`threshold`	Threshold in dB, typically -60 to 0. TYPE: `float` DEFAULT: `-20.0`
`attack`	Attack time in seconds, > 0. Typical: 0.001--0.05. TYPE: `float` DEFAULT: `0.01`
`release`	Release time in seconds, > 0. Typical: 0.01--0.5. TYPE: `float` DEFAULT: `0.1`

noise_gate ¶

noise_gate(
    buf: AudioBuffer,
    threshold_db: float = -40.0,
    attack: float = 0.001,
    release: float = 0.05,
    hold_ms: float = 10.0,
) -> AudioBuffer

Gate signal below threshold_db, silencing quiet passages.

PARAMETER	DESCRIPTION
`threshold_db`	Gate threshold in dB. Signal below this is attenuated. Typical: -60 to -20. TYPE: `float` DEFAULT: `-40.0`
`attack`	Gate open time in seconds, > 0. Typical: 0.001--0.01. TYPE: `float` DEFAULT: `0.001`
`release`	Gate close time in seconds, > 0. Typical: 0.01--0.1. TYPE: `float` DEFAULT: `0.05`
`hold_ms`	Hold time in milliseconds (>= 0) after signal drops below threshold before the gate starts closing. TYPE: `float` DEFAULT: `10.0`

transient_shape ¶

transient_shape(
    buf: AudioBuffer,
    attack_gain: float = 1.0,
    sustain_gain: float = 1.0,
    fast_attack: float = 0.005,
    fast_release: float = 0.02,
    slow_attack: float = 0.05,
    slow_release: float = 0.2,
) -> AudioBuffer

Shape transients by independently scaling attack and sustain components.

Uses two envelope followers at different speeds. The fast envelope tracks transients; the slow envelope tracks the sustained level. When attack_gain > 1 transients are emphasized; when sustain_gain < 1 the body between transients is reduced.

PARAMETER	DESCRIPTION
`attack_gain`	Gain multiplier for transient (attack) component, >= 0. 1.0 = unchanged. TYPE: `float` DEFAULT: `1.0`
`sustain_gain`	Gain multiplier for sustain component, >= 0. 1.0 = unchanged. TYPE: `float` DEFAULT: `1.0`
`fast_attack`	Fast envelope follower times in seconds. Typical: 0.001--0.01 / 0.01--0.05. TYPE: `float` DEFAULT: `0.005`
`fast_release`	Fast envelope follower times in seconds. Typical: 0.001--0.01 / 0.01--0.05. TYPE: `float` DEFAULT: `0.005`
`slow_attack`	Slow envelope follower times in seconds. Typical: 0.02--0.1 / 0.1--0.5. TYPE: `float` DEFAULT: `0.05`
`slow_release`	Slow envelope follower times in seconds. Typical: 0.02--0.1 / 0.1--0.5. TYPE: `float` DEFAULT: `0.05`

agc ¶

agc(
    buf: AudioBuffer,
    target_level: float = 1.0,
    max_gain_db: float = 60.0,
    average_len: int = 100,
    attack: float = 0.01,
    release: float = 0.01,
) -> AudioBuffer

Automatic Gain Control.

PARAMETER	DESCRIPTION
`target_level`	Desired RMS output level (linear), > 0. Typical: 0.1--1.0. TYPE: `float` DEFAULT: `1.0`
`max_gain_db`	Maximum gain in dB to prevent boosting silence to infinity. Typical: 20--60. TYPE: `float` DEFAULT: `60.0`
`average_len`	Number of samples for the moving-average power estimator, >= 1. Typical: 50--500. TYPE: `int` DEFAULT: `100`
`attack`	Attack time constant in seconds (fast gain reduction), >= 0. Typical: 0.001--0.05. TYPE: `float` DEFAULT: `0.01`
`release`	Release time constant in seconds (slow gain increase), >= 0. Typical: 0.01--0.1. TYPE: `float` DEFAULT: `0.01`

lookahead_limit ¶

lookahead_limit(
    buf: AudioBuffer,
    threshold_db: float = -1.0,
    lookahead_ms: float = 5.0,
    release: float = 0.1,
) -> AudioBuffer

Brick-wall limiter with lookahead for transparent peak control.

Delays the audio by lookahead_ms so the gain curve can begin reducing before a peak arrives, avoiding distortion on transients. The output should never exceed threshold_db.

PARAMETER	DESCRIPTION
`threshold_db`	Ceiling in dBFS, <= 0. Typical: -1 to 0. TYPE: `float` DEFAULT: `-1.0`
`lookahead_ms`	Lookahead time in milliseconds, > 0. Typical: 1--10. TYPE: `float` DEFAULT: `5.0`
`release`	Gain recovery time in seconds, > 0. Typical: 0.05--0.5. TYPE: `float` DEFAULT: `0.1`