Source code for audiodynamics

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Compression, limiting, expansion, gating and transient shaping.

`Dynamics` is one node that does the job of a compressor, a limiter, an
expander, a gate or a transient shaper, chosen by its mode. Hand it an audio
source with `play`, and the result is another audio source. Its detector can
run on the signal itself or on a separate key signal given to `key`, which is
how a sidechain compressor is made.

Beyond the usual settings it has a number of options, every one of them off by
default, so a node that sets none of them does what a plain compressor does:
an RMS detector, a feedback detector and an external key input with Key
Listen, a 4x true-peak reconstruction, a two-pole key band with both corners
settable, a settable expander and gate depth, a four-stage gate envelope with
hold and hysteresis, a relative-threshold gain computer, a program-dependent
attack, and the transient shaper's four detector time constants, a second
envelope pair and a hold on the slow one.

A level moved on a playing node walks to its new value over 20 ms instead of
stepping, so turning ``makeup_db`` in one call does not click. Every option
changes together or not at all, so a bad keyword leaves the node as it was.

The node takes and gives 16-bit audio in blocks of 256 frames, with 1 or 2
channels, and never reports itself finished: a chain with nothing left to
read gets silence.
"""

from __future__ import annotations
from types import TracebackType
from typing import Protocol, Self

__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""

DYN_COMPRESS: int
"""A mode: turn down what is above the threshold, by ``ratio``. This is 0."""
DYN_LIMIT: int
"""A mode: stop the level at the threshold. This is 1."""
DYN_EXPAND: int
"""A mode: turn down what is below the threshold, by ``ratio``. This is 2."""
DYN_GATE: int
"""A mode: shut off what is below the threshold. This is 3."""
DYN_TRANSIENT: int
"""A mode: reshape the start and the body of notes, by ``attack_gain_db`` and
``sustain_gain_db``. This is 4."""

class _AudioSample(Protocol):
    @property
    def sample_rate(self) -> int: ...
    @property
    def bits_per_sample(self) -> int: ...
    @property
    def channel_count(self) -> int: ...

[docs] class Dynamics: """A compressor, limiter, expander, gate or transient shaper. The mode is the one positional argument; everything else is a keyword. Args: mode: One of `DYN_COMPRESS`, `DYN_LIMIT`, `DYN_EXPAND`, `DYN_GATE` and `DYN_TRANSIENT`. The default is `DYN_COMPRESS`. sample_rate: Frames per second. The default is 48000. channel_count: 1 or 2. The default is 2. threshold_db: The level in dB where the effect starts, for every mode. The default is -24. ratio: The compression or expansion ratio, 1 or more (lower values are 1). The default is 4. knee_db: The width of the soft knee around the threshold, in dB, 0 or more. The default is 6. makeup_db: Gain added after the effect, in dB. A change walks to its new value over 20 ms. The default is 0. attack_ms: How fast the detector follows a rise, in milliseconds. The default is 10. release_ms: How fast the detector follows a fall, in milliseconds. The default is 120. attack_gain_db: `DYN_TRANSIENT` only: the gain in dB for the start of a note. The default is 0. sustain_gain_db: `DYN_TRANSIENT` only: the gain in dB for the body of a note. The default is 0. sidechain_hz: A high-pass corner in Hz on the signal the detector hears, so low notes do not pump the gain. 0 or less is off, the default. lookahead_ms: How far ahead of the output the detector looks, in milliseconds, 0 to 50. It adds that much latency. The default is 0. true_peak: How the detector finds peaks between samples. 0 or False reads the samples; 1 or True estimates the peak with a half-band filter; 2 or more reconstructs it at four times the rate. The default is 0. transient_fast_attack_ms: `DYN_TRANSIENT`: the fast envelope's attack time, in milliseconds. The default is 1. transient_fast_release_ms: `DYN_TRANSIENT`: the fast envelope's release time, in milliseconds. The default is 50. transient_slow_attack_ms: `DYN_TRANSIENT`: the slow envelope's attack time, in milliseconds. The default is 25. transient_slow_release_ms: `DYN_TRANSIENT`: the slow envelope's release time, in milliseconds. The default is 300. detector: What the detector measures: ``'peak'`` or ``'rms'``, or 0 or 1 for the same. The default is ``'peak'``. rms_ms: The averaging window of the RMS detector, in milliseconds. The default is 10. feedback_detector: Have the detector read the previous output frame instead of the input, the feedback arrangement of classic hardware compressors. The default is off. sidechain_lp_hz: A low-pass corner in Hz on the signal the detector hears, which with ``sidechain_hz`` makes a band. 0 or less is off, the default. sidechain_poles: How steep the key band's filters are: 1 pole (6 dB an octave) or 2 (12). The default is 1. key_listen: Put the detector's signal on the output instead of the audio, as a gate's Key Listen switch does. The default is off. depth_db: The floor `DYN_EXPAND` and `DYN_GATE` pull the level down to, in dB, zero or below. A positive value, the default, leaves it unset: -60 dB for the expander and -80 dB for the gate. hold_ms: `DYN_GATE`: how long the gate holds open after the level falls below the threshold, in milliseconds, which makes the gate's envelope four-stage. 0 is no hold, the default. hysteresis_db: `DYN_GATE`: the gap in dB between the level that opens the gate and the one that closes it. The default is 0. relative_threshold: Drive the gain computer by the key band's level minus the full-band level, so a fixed spectral balance gets the same reduction wherever it sits in the level range. The default is off. program_attack: Scale the attack by how far the level overshoots the envelope, so a bigger overshoot is caught faster. The default is off. transient_dual: `DYN_TRANSIENT`: apply the attack and sustain gains together, the sustain section reading its own, slower pair of envelopes. The default is off. sustain_fast_attack_ms: `DYN_TRANSIENT`, with ``transient_dual``: the sustain section's fast attack, in milliseconds. The default is 1. sustain_fast_release_ms: `DYN_TRANSIENT`, with ``transient_dual``: the sustain section's fast release, in milliseconds. The default is 200. sustain_slow_attack_ms: `DYN_TRANSIENT`, with ``transient_dual``: the sustain section's slow attack, in milliseconds. The default is 25. sustain_slow_release_ms: `DYN_TRANSIENT`, with ``transient_dual``: the sustain section's slow release, in milliseconds. The default is 1200. slow_hold_ms: `DYN_TRANSIENT`: how long the slow envelope holds its peak before it releases, in milliseconds. 0 is no hold, the default. gain_smooth_ms: Smooth the computed gain with a one-pole filter of this time, in milliseconds. 0 or less is off, the default. feedback_gain_corrected: With ``feedback_detector`` in `DYN_COMPRESS`, make the loop land on the ratio you asked for. Off, the loop reduces its own input and settles near 2:1 whatever the ratio. The default is off. Raises: ValueError: ``channel_count`` is not 1 or 2, or ``detector`` is not ``'peak'`` or ``'rms'``. TypeError: An unknown option was given. """ def __init__( self, mode: int = 0, *, sample_rate: int = 48000, channel_count: int = 2, threshold_db: float = ..., ratio: float = ..., knee_db: float = ..., makeup_db: float = ..., attack_ms: float = ..., release_ms: float = ..., attack_gain_db: float = ..., sustain_gain_db: float = ..., sidechain_hz: float = ..., lookahead_ms: float = ..., true_peak: float = ..., transient_fast_attack_ms: float = ..., transient_fast_release_ms: float = ..., transient_slow_attack_ms: float = ..., transient_slow_release_ms: float = ..., detector: str | float = ..., rms_ms: float = ..., feedback_detector: bool = ..., sidechain_lp_hz: float = ..., sidechain_poles: float = ..., key_listen: bool = ..., depth_db: float = ..., hold_ms: float = ..., hysteresis_db: float = ..., relative_threshold: bool = ..., program_attack: bool = ..., transient_dual: bool = ..., sustain_fast_attack_ms: float = ..., sustain_fast_release_ms: float = ..., sustain_slow_attack_ms: float = ..., sustain_slow_release_ms: float = ..., slow_hold_ms: float = ..., gain_smooth_ms: float = ..., feedback_gain_corrected: bool = ..., ) -> None: ... sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream to process, replacing the last one."""
[docs] def key(self, source: _AudioSample | None, /) -> None: """Set the key signal the detector listens to instead of the stream itself, or None to go back to the stream. The key has to match the stream's channel count."""
[docs] def set( self, *, sample_rate: int = ..., channel_count: int = ..., threshold_db: float = ..., ratio: float = ..., knee_db: float = ..., makeup_db: float = ..., attack_ms: float = ..., release_ms: float = ..., attack_gain_db: float = ..., sustain_gain_db: float = ..., sidechain_hz: float = ..., lookahead_ms: float = ..., true_peak: float = ..., transient_fast_attack_ms: float = ..., transient_fast_release_ms: float = ..., transient_slow_attack_ms: float = ..., transient_slow_release_ms: float = ..., detector: str | float = ..., rms_ms: float = ..., feedback_detector: bool = ..., sidechain_lp_hz: float = ..., sidechain_poles: float = ..., key_listen: bool = ..., depth_db: float = ..., hold_ms: float = ..., hysteresis_db: float = ..., relative_threshold: bool = ..., program_attack: bool = ..., transient_dual: bool = ..., sustain_fast_attack_ms: float = ..., sustain_fast_release_ms: float = ..., sustain_slow_attack_ms: float = ..., sustain_slow_release_ms: float = ..., slow_hold_ms: float = ..., gain_smooth_ms: float = ..., feedback_gain_corrected: bool = ..., ) -> None: """Change options while the node plays. Takes the same options as the constructor. All of them change together or not at all, and a change to ``lookahead_ms`` or ``channel_count`` allocates what it needs before anything changes. Raises: ValueError: As for the constructor. TypeError: An unknown option was given. """
[docs] def gain_reduction_db(self) -> float: """How much the node is turning the level down now, in dB, for a meter."""
[docs] def deinit(self) -> None: """Release the node. Later calls other than `deinit` raise `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...