Dynamics Processors

This section covers dynamics processors including compressors, limiters, and their multi-band variants.

Compressor

class diffFx_pytorch.processors.dynamics.Compressor(*args: Any, **kwargs: Any)

Bases: ProcessorsBase

Differentiable feedforward dynamic range compressor.

This processor implements a feedforward compressor with configurable knee curves and envelope following methods. The compressor uses level detection, smoothing, and gain computation stages to reduce dynamic range.

Implementation is based on the following papers:

[1]

Giannoulis, Dimitrios, Michael Massberg, and Joshua D. Reiss. “Digital dynamic range compressor design—A tutorial and analysis.” Journal of the Audio Engineering Society 60.6 (2012): 399-408.

[2]

Lee, Sungho, et al. “GRAFX: an open-source library for audio processing graphs in PyTorch.” arXiv preprint arXiv:2408.03204 (2024).

[3]

Reiss, Joshua D., and Andrew McPherson. Audio effects: theory, implementation and application. CRC Press, 2014.

[4]

Yu, Chin-Yun, et al. “Differentiable all-pole filters for time-varying audio systems.” arXiv preprint arXiv:2404.07970 (2024).

Processing Chain:

1. Level Detection: RMS energy → dB

2. Envelope Following: Attack/release smoothing

3. Gain Computation: Apply compression curve

4. Gain Application: Convert to linear gain and apply

The compressor implements the following gain computation:

Hard Knee:

\[\begin{split}g(x) = \begin{cases} 0, & \text{if } x \leq T \\ (T + \frac{x - T}{R}) - x, & \text{if } x > T \end{cases}\end{split}\]

Quadratic Knee:

\[\begin{split}g(x) = \begin{cases} 0, & \text{if } x \leq T - W/2 \\ (\frac{1}{R} - 1)\frac{(x - T + W/2)^2}{4W}, & \text{if } T - W/2 < x \leq T + W/2 \\ (T + \frac{x - T}{R}) - x, & \text{if } x > T + W/2 \end{cases}\end{split}\]

Exponential Knee:

\[g(x) = (\frac{1}{R} - 1) \frac{\text{softplus}(k(x - T))}{k}\]

where k = exp(W) is the knee factor

Variables:

• x: input level in dB

• T: threshold in dB

• R: ratio

• W: knee width in dB

Parameters:

• sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.

• knee_type (str, optional) – Type of compression knee curve. Must be one of: “hard”, “quadratic”, “exponential”. Defaults to “quadratic”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

knee_type

Current knee characteristic type

Type:

str

smoothing_type

Current envelope follower type

Type:

str

ballistics

Envelope follower for attack/release

Type:

Ballistics

iir_filter

IIR filter for smoothing

Type:

TruncatedOnePoleIIRFilter

Parameters Details:

threshold_db: Level at which compression begins

• Controls where compression starts to take effect

• More negative values compress more of the signal

ratio: Amount of gain reduction above threshold

• 2:1 means for every 2 dB increase in input, output increases by 1 dB

• Higher ratios mean more compression

• 1:1 means no compression

knee_db: Width of the transition region around threshold

• 0 dB creates a hard knee (sudden transition)

• Larger values create smoother transitions

• Affects how gradually compression is applied

attack_ms: Time taken to react to increases in level

• Shorter times mean faster response to transients

• Longer times let more of the transient through

release_ms: Time taken to react to decreases in level

• Controls how quickly compression is reduced

• Affects the “movement” of the compression

makeup_db: Gain applied after compression

• Compensates for level reduction from compression

Note

The processor supports the following parameter ranges:

• threshold_db: Threshold level in dB (-60 to 0)

• ratio: Compression ratio (1 to 20)

• knee_db: Knee width in dB (0 to 12)

• attack_ms: Attack time in ms (0.1 to 100)

• release_ms: Release time in ms (10 to 1000)

• makeup_db: Makeup gain in dB (-12 to 12)

Warning

When using with neural networks:

• norm_params must be in range [0, 1]

• Parameters will be automatically mapped to their DSP ranges

• Ensure your network output is properly normalized (e.g., using sigmoid)

• Parameter order must match _register_default_parameters()

Examples

Basic DSP Usage:

>>> # Create a compressor with quadratic knee
>>> compressor = Compressor(
...     sample_rate=44100,
...     knee_type="quadratic",
...     smooth_type="ballistics"
... )
>>> # Process audio with dsp parameters
>>> output = compressor(input_audio, dsp_params={
...     'threshold_db': -20.0,
...     'ratio': 4.0,
...     'knee_db': 6.0,
...     'attack_ms': 5.0,
...     'release_ms': 50.0,
...     'makeup_db': 0.0
... })

Neural Network Control:

>>> # 1. Simple parameter prediction
>>> class CompressorController(nn.Module):
...     def __init__(self, input_size, num_params):
...         super().__init__()
...         self.net = nn.Sequential(
...             nn.Linear(input_size, 32),
...             nn.ReLU(),
...             nn.Linear(32, num_params),
...             nn.Sigmoid()  # Ensures output is in [0,1] range
...         )
...
...     def forward(self, x):
...         return self.net(x)
>>>
>>> # Initialize controller
>>> num_params = compressor.count_num_parameters()  # 6 parameters
>>> controller = CompressorController(input_size=16, num_params=num_params)
>>>
>>> # Process with features
>>> features = torch.randn(batch_size, 16)  # Audio features
>>> norm_params = controller(features)
>>> output = compressor(input_audio, norm_params=norm_params)

A feedforward dynamic range compressor with three knee types (hard, quadratic, exponential) and two smoothing options (ballistics, IIR).

__init__(sample_rate=44100, param_range=None, knee_type='quadratic', smooth_type='ballistics')

Initialize the compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• knee_type (str) – Type of compression knee curve

• smooth_type (str) – Type of envelope follower

Raises:

ValueError – If knee_type or smooth_type is invalid

_register_default_parameters()

Register default parameter ranges for the compressor.

Sets up the following parameters with their ranges:

• threshold_db: Threshold level (-60 to 0 dB)

• ratio: Compression ratio (1 to 20)

• knee_db: Knee width (0 to 12 dB)

• attack_ms: Attack time (0.1 to 100 ms)

• release_ms: Release time (10 to 1000 ms)

• makeup_db: Makeup gain (-12 to 12 dB)

process(x, norm_params=None, dsp_params=None)

Process input signal through the compressor.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys: - ‘threshold_db’: Level at which compression begins (-60 to 0 dB) - ‘ratio’: Amount of gain reduction above threshold (1 to 20) - ‘knee_db’: Width of transition region around threshold (0 to 12 dB) - ‘attack_ms’: Time to react to level increases (0.1 to 100 ms) - ‘release_ms’: Time to react to level decreases (10 to 1000 ms) - ‘makeup_db’: Gain applied after compression (-12 to 12 dB) Each value should be a tensor of shape (batch_size,) Values will be mapped to their respective ranges

• dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify parameters as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

_compute_gain(level_db, threshold_db, ratio, knee_db)

Compute compression gain based on knee type.

Implementation based on [1], [2] with different knee characteristics.

Parameters:

• level_db (torch.Tensor) – Input level in dB. Shape: (batch, time)

• threshold_db (torch.Tensor) – Threshold in dB. Shape: (batch,)

• ratio (torch.Tensor) – Compression ratio. Shape: (batch,)

• knee_db (torch.Tensor) – Knee width in dB. Shape: (batch,)

Returns:

Gain reduction in dB. Shape: (batch, time)

Return type:

torch.Tensor

Note

The gain computation depends on the knee_type: - “hard”: Sharp transition at threshold - “quadratic”: Smooth quadratic transition around threshold - “exponential”: Continuous transition using softplus

Multi-band Compressor

class diffFx_pytorch.processors.dynamics.MultiBandCompressor(*args: Any, **kwargs: Any)

Bases: ProcessorsBase

Differentiable multi-band dynamic range compressor.

This processor splits the input signal into multiple frequency bands using Linkwitz-Riley crossover filters and applies independent compression to each band. The processed bands are then summed to produce the final output.

Implementation is based on the following references:

[1]

MATLAB Audio Toolbox. “Multiband Dynamic Range Compression.” https://www.mathworks.com/help/audio/ug/multiband-dynamic-range-compression.html

[2]

Giannoulis, D., Massberg, M., & Reiss, J. D. (2012). “Digital dynamic range compressor design—A tutorial and analysis.” Journal of the Audio Engineering Society, 60(6), 399-408.

Processing Chain:

1. Band Splitting: Split input into frequency bands using Linkwitz-Riley filters

2. Per-band Processing:

   1. Level Detection: Compute RMS energy and convert to dB

   2. Envelope Following: Smooth level using attack/release ballistics

   3. Gain Computation: Apply compression curve based on knee type

   4. Gain Application: Convert to linear gain and apply to band

3. Band Summation: Sum all processed bands to create final output

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

• knee_type (str, optional) – Type of compression knee curve. Must be one of: “hard”, “quadratic”, “exponential”. Defaults to “quadratic”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

Parameters Details:

For each band i (0 to num_bands-1):

band{i}_threshold_db: Level at which compression begins

• Controls where compression starts for this band (-60 to 0 dB)

band{i}_ratio: Amount of gain reduction above threshold

• Higher ratios mean more compression (1 to 20)

band{i}_knee_db: Width of transition region around threshold

• Controls how gradually compression is applied (0 to 12 dB)

band{i}_attack_ms: Time to react to level increases

• Controls response to transients (1 to 500 ms)

band{i}_release_ms: Time to react to level decreases

• Controls recovery time (10 to 2000 ms)

band{i}_makeup_db: Gain applied after compression

• Compensates for level reduction (-24 to 24 dB)

Crossover frequencies:

crossover{i}_freq: Split frequency between bands i and i+1

• Logarithmically spaced between bands

• Range varies based on position (20 Hz to 20 kHz)

Note

• Uses 4th-order Linkwitz-Riley crossover filters

• Band splitting is done in series for proper phase alignment

• Each band has independent compression parameters

• Parameters can be controlled via normalized (0-1) or DSP values

• Total parameters = num_bands * 6 + (num_bands - 1)

Examples

Basic Usage:

>>> # Create a 3-band compressor
>>> mb_comp = MultiBandCompressor(
...     sample_rate=44100,
...     num_bands=3
... )
>>> # Process with DSP parameters
>>> output = mb_comp(input_audio, dsp_params={
...     'band0_threshold_db': -24.0,  # Low band
...     'band0_ratio': 4.0,
...     'band0_knee_db': 6.0,
...     'band0_attack_ms': 10.0,
...     'band0_release_ms': 100.0,
...     'band0_makeup_db': 3.0,
...     'band1_threshold_db': -18.0,  # Mid band
...     'band1_ratio': 3.0,
...     'band1_knee_db': 6.0,
...     'band1_attack_ms': 5.0,
...     'band1_release_ms': 50.0,
...     'band1_makeup_db': 2.0,
...     'band2_threshold_db': -12.0,  # High band
...     'band2_ratio': 2.0,
...     'band2_knee_db': 6.0,
...     'band2_attack_ms': 1.0,
...     'band2_release_ms': 20.0,
...     'band2_makeup_db': 1.0,
...     'crossover0_freq': 200.0,     # Low-Mid split
...     'crossover1_freq': 2000.0     # Mid-High split
... })

Neural Network Control:

>>> # Create parameter prediction network
>>> class MultiBandCompressorNet(nn.Module):
...     def __init__(self, input_size, num_bands):
...         super().__init__()
...         num_params = num_bands * 6 + (num_bands - 1)
...         self.net = nn.Sequential(
...             nn.Linear(input_size, 32),
...             nn.ReLU(),
...             nn.Linear(32, num_params),
...             nn.Sigmoid()  # Ensures output is in [0,1] range
...         )
...
...     def forward(self, x):
...         return self.net(x)
>>>
>>> # Process with predicted parameters
>>> controller = MultiBandCompressorNet(input_size=16, num_bands=3)
>>> norm_params = controller(features)  # Shape: [batch_size, 21]
>>> output = mb_comp(input_audio, norm_params=norm_params)

A multi-band compressor that splits the input into frequency bands and applies independent compression to each band.

__init__(sample_rate, param_range=None, num_bands=3, knee_type='quadratic', smooth_type='ballistics')

Initialize the multi-band compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

• knee_type (str, optional) – Type of compression knee curve. Must be one of: “hard”, “quadratic”, “exponential”. Defaults to “quadratic”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

Raises:

• ValueError – If knee_type is not one of “hard”, “quadratic”, or “exponential”

• ValueError – If smooth_type is not one of “ballistics” or “iir”

Note

Initializes crossover filters as a ModuleList with (num_bands - 1) filters to split the input into num_bands frequency bands.

_register_default_parameters()

Register default parameter ranges for the multi-band compressor.

Sets up the following parameters for each band i (0 to num_bands-1):

• band{i}_threshold_db: Threshold level (-60 to 0 dB)

• band{i}_ratio: Compression ratio (1 to 20)

• band{i}_knee_db: Knee width (0 to 12 dB)

• band{i}_attack_ms: Attack time (1 to 500 ms)

• band{i}_release_ms: Release time (10 to 2000 ms)

• band{i}_makeup_db: Makeup gain (-24 to 24 dB)

Also registers crossover frequencies:

• crossover{i}_freq: Split frequency between bands i and i+1

  with logarithmic spacing between 20 Hz and 20 kHz

Note

Parameter ranges are stored in self.params dictionary and used for mapping normalized parameters to DSP values.

_compute_gain(level_db, threshold_db, ratio, knee_db)

Compute compression gain based on knee type.

Implementation based on [2] with different knee characteristics.

Parameters:

• level_db (torch.Tensor) – Input level in dB. Shape: (batch, time)

• threshold_db (torch.Tensor) – Threshold in dB. Shape: (batch,)

• ratio (torch.Tensor) – Compression ratio. Shape: (batch,)

• knee_db (torch.Tensor) – Knee width in dB. Shape: (batch,)

Returns:

Gain reduction in dB. Shape: (batch, time)

Return type:

torch.Tensor

Note

Implements three knee types:

• “hard”: Sharp transition at threshold

• “quadratic”: Smooth quadratic transition around threshold

• “exponential”: Continuous transition using softplus

All input tensors are automatically broadcast to match dimensions.

_process_band(x, band_params)

Process a single frequency band with compression.

Parameters:

• x (torch.Tensor) – Input audio for this band. Shape: (batch, channels, samples)

• band_params (Dict[str, torch.Tensor]) –

  Compression parameters for this band. Must contain:

  • threshold_db: Threshold level in dB

  • ratio: Compression ratio

  • knee_db: Knee width in dB

  • attack_ms: Attack time in ms

  • release_ms: Release time in ms

  • makeup_db: Makeup gain in dB

Returns:

Processed audio for this band.

Shape: (batch, channels, samples)

Return type:

torch.Tensor

Note

Processing steps: 1. Compute RMS level in dB 2. Apply envelope following using attack/release 3. Compute gain using knee characteristic 4. Apply gain and makeup

process(x, norm_params=None, dsp_params=None)

Process input signal through the multi-band compressor.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys for each band i (0 to num_bands-1): - f’band{i}_threshold_db’: Level at which compression begins (-60 to 0 dB) - f’band{i}_ratio’: Amount of gain reduction above threshold (1 to 20) - f’band{i}_knee_db’: Width of transition region around threshold (0 to 12 dB) - f’band{i}_attack_ms’: Time to react to level increases (1 to 500 ms) - f’band{i}_release_ms’: Time to react to level decreases (10 to 2000 ms) - f’band{i}_makeup_db’: Gain applied after compression (-24 to 24 dB) And crossover frequencies between bands: - f’crossover{i}_freq’: Split frequency between bands i and i+1 Each value should be a tensor of shape (batch_size,) Values will be mapped to their respective ranges

• dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify parameters as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

Limiter

class diffFx_pytorch.processors.dynamics.Limiter(*args: Any, **kwargs: Any)

Bases: Compressor

Differentiable feedforward peak limiter.

A specialized compressor with high ratio and fast attack time to prevent audio signals from exceeding a specified threshold.

Parameters:

• sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.

• param_range (Dict[str, EffectParam]) – Parameter ranges for the limiter.

• threshold_db – Level at which limiting begins (-60 to 0 dB)

• ratio – Amount of gain reduction above threshold (20 to 100)

• knee_db – Width of the transition region (0 to 1 dB)

• attack_ms – Time taken to react to increases in level (0.1 to 1.0 ms)

• release_ms – Time taken to react to decreases in level (5 to 500 ms)

• makeup_db – Gain applied after limiting (-24 to 24 dB)

Note

• Uses hard-knee characteristic for precise limiting

• Employs extremely fast attack times (< 1ms)

• Uses very high ratios (>20:1) for “brick wall” limiting

• Has very narrow knee width for sharp transitions

• Optimized for peak control rather than dynamic range control

Warning

When using with neural networks: - norm_params must be in range [0, 1] - Parameters will be automatically mapped to their DSP ranges - Parameter ranges are more extreme than standard compression - Ensure network output dimension matches total parameters - Parameter order must match _register_default_parameters()

A specialized compressor configured for limiting with fast attack times and high ratios.

__init__(sample_rate=44100, param_range=None)

Initialize the compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• knee_type (str) – Type of compression knee curve

• smooth_type (str) – Type of envelope follower

Raises:

ValueError – If knee_type or smooth_type is invalid

_register_default_parameters()

Register default parameter ranges for the limiter.

Sets up the following parameters with their ranges:

• threshold_db: Threshold level (-60 to 0 dB)

• ratio: Limiting ratio (20 to 100)

• knee_db: Knee width (0 to 1 dB)

• attack_ms: Attack time (0.1 to 1.0 ms)

• release_ms: Release time (5 to 500 ms)

• makeup_db: Makeup gain (-12 to 12 dB)

Note

Parameter ranges are more extreme than standard compression to achieve limiting behavior.

process(x, norm_params=None, dsp_params=None)

Process audio through the limiter.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1)

• dsp_params (Dict[str, torch.Tensor], optional) – Direct DSP parameters. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

Note

Uses parent Compressor class processing with specialized parameter ranges for limiting behavior.

Multi-band Limiter

class diffFx_pytorch.processors.dynamics.MultiBandLimiter(*args: Any, **kwargs: Any)

Bases: MultiBandCompressor

Differentiable multi-band peak limiter with frequency-dependent threshold control.

A specialized limiter that splits the input signal into multiple frequency bands and applies limiting independently to each band.

Parameters:

• sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.

• num_bands (int) – Number of frequency bands. Defaults to 4.

• param_range (Dict[str, EffectParam]) – Parameter ranges for the limiter.

• crossover_freqs – Crossover frequencies between bands in Hz - Shape: (num_bands-1,) - Range: 20 to 20000 Hz

• threshold_db – Level at which limiting begins for each band - Shape: (num_bands,) - Range: -60 to 0 dB

• ratio – Amount of gain reduction above threshold for each band - Shape: (num_bands,) - Range: 20 to 100

• knee_db – Width of the transition region for each band - Shape: (num_bands,) - Range: 0 to 1 dB

• attack_ms – Time taken to react to increases in level for each band - Shape: (num_bands,) - Range: 0.1 to 1.0 ms

• release_ms – Time taken to react to decreases in level for each band - Shape: (num_bands,) - Range: 5 to 500 ms

• makeup_db – Gain applied after limiting for each band - Shape: (num_bands,) - Range: -12 to 12 dB

Note

• Uses hard-knee characteristic for precise limiting

• Employs extremely fast attack times (< 1ms)

• Uses very high ratios (>20:1) for “brick wall” limiting

• Has very narrow knee width for sharp transitions

• Optimized for peak control rather than dynamic range control

• Each band can be controlled independently

Warning

When using with neural networks: - norm_params must be in range [0, 1] - Parameters will be automatically mapped to their DSP ranges - Parameter ranges are more extreme than standard compression - Ensure network output dimension matches total parameters - Parameter order must match _register_default_parameters()

A multi-band limiter that applies independent limiting to different frequency bands.

__init__(sample_rate, param_range=None, num_bands=3)

Initialize the multi-band limiter.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

Note

Configures the processor with fixed hard-knee and ballistics smoothing for optimal limiting behavior across all bands.

_register_default_parameters()

Register default parameter ranges for the multi-band limiter.

Sets up parameters for each band with ranges optimized for limiting:

• threshold_db: Threshold level (-60 to 0 dB)

• ratio: Limiting ratio (20 to 100)

• knee_db: Knee width (0 to 1 dB)

• attack_ms: Attack time (0.1 to 1.0 ms)

• release_ms: Release time (5 to 500 ms)

• makeup_db: Makeup gain (-12 to 12 dB)

Also registers crossover frequencies with logarithmic spacing.

Note

Parameter ranges are more extreme than compression to achieve true limiting behavior in each band.

_process_band(x, band_params)

Process a single frequency band with limiting.

Parameters:

• x (torch.Tensor) – Input audio for this band. Shape: (batch, channels, samples)

• band_params (Dict[str, torch.Tensor]) –

  Limiting parameters for this band. Must contain:

  • threshold_db: Threshold level in dB

  • ratio: Limiting ratio

  • knee_db: Knee width in dB

  • attack_ms: Attack time in ms

  • release_ms: Release time in ms

  • makeup_db: Makeup gain in dB

Returns:

Processed audio for this band.

Shape: (batch, channels, samples)

Return type:

torch.Tensor

Note

Uses hard-knee limiting with very fast attack times for precise peak control in each frequency band.

_compute_gain(level_db, threshold_db, ratio, knee_db)

Compute limiting gain using hard-knee characteristic.

Parameters:

• level_db (torch.Tensor) – Input level in dB. Shape: (batch, time)

• threshold_db (torch.Tensor) – Threshold in dB. Shape: (batch,)

• ratio (torch.Tensor) – Limiting ratio. Shape: (batch,)

• knee_db (torch.Tensor) – Knee width in dB. Shape: (batch,)

Returns:

Gain reduction in dB. Shape: (batch, time)

Return type:

torch.Tensor

Note

Implements hard-knee limiting with high ratio for “brick wall” style gain reduction.

process(x, norm_params=None, dsp_params=None)

Process audio through the multi-band limiter.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1)

• dsp_params (Dict[str, torch.Tensor], optional) – Direct DSP parameters. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

Note

Uses parent MultiBandCompressor processing chain with parameters optimized for limiting behavior in each band.

Expander

class diffFx_pytorch.processors.dynamics.Expander(*args: Any, **kwargs: Any)

Bases: Compressor

Differentiable expander based on compressor implementation.

An expander increases the dynamic range of the signal by reducing the level of signals that fall below the threshold. The amount of reduction is determined by the ratio parameter.

A feedforward expander with three knee types (hard, quadratic, exponential) and two smoothing options (ballistics, IIR).

process(x, norm_params=None, dsp_params=None)

Process input signal through the compressor.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys: - ‘threshold_db’: Level at which compression begins (-60 to 0 dB) - ‘ratio’: Amount of gain reduction above threshold (1 to 20) - ‘knee_db’: Width of transition region around threshold (0 to 12 dB) - ‘attack_ms’: Time to react to level increases (0.1 to 100 ms) - ‘release_ms’: Time to react to level decreases (10 to 1000 ms) - ‘makeup_db’: Gain applied after compression (-12 to 12 dB) Each value should be a tensor of shape (batch_size,) Values will be mapped to their respective ranges

• dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify parameters as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

Multi-band Expander

class diffFx_pytorch.processors.dynamics.MultiBandExpander(*args: Any, **kwargs: Any)

Bases: MultiBandCompressor

Differentiable multi-band dynamic range expander.

A multi-band expander that applies independent expansion to different frequency bands.

__init__(sample_rate, param_range=None, num_bands=3)

Initialize the multi-band compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

• knee_type (str, optional) – Type of compression knee curve. Must be one of: “hard”, “quadratic”, “exponential”. Defaults to “quadratic”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

Raises:

• ValueError – If knee_type is not one of “hard”, “quadratic”, or “exponential”

• ValueError – If smooth_type is not one of “ballistics” or “iir”

Note

Initializes crossover filters as a ModuleList with (num_bands - 1) filters to split the input into num_bands frequency bands.

_compute_gain(level_db, threshold_db, ratio, knee_db)

Compute expansion gain based on knee type.

Parameters:

• level_db (Tensor) –

• threshold_db (Tensor) –

• ratio (Tensor) –

• knee_db (Tensor) –

Return type:

Tensor

_process_band(x, band_params)

Process a single frequency band with expansion.

Parameters:

• x (Tensor) –

• band_params (Dict[str, Tensor]) –

Return type:

Tensor

Noise Gate

class diffFx_pytorch.processors.dynamics.NoiseGate(*args: Any, **kwargs: Any)

Bases: Compressor

Differentiable feedforward noise gate.

This processor implements a feedforward noise gate with configurable knee curves and envelope following methods. The noise gate reduces the level of signals that fall below the threshold, effectively removing background noise and unwanted low-level signals.

Implementation is based on the following papers:

[1]

Giannoulis, Dimitrios, Michael Massberg, and Joshua D. Reiss. “Digital dynamic range compressor design—A tutorial and analysis.” Journal of the Audio Engineering Society 60.6 (2012): 399-408.

[2]

Reiss, Joshua D., and Andrew McPherson. Audio effects: theory, implementation and application. CRC Press, 2014.

Processing Chain:

1. Level Detection: RMS energy → dB

2. Envelope Following: Attack/release smoothing

3. Gain Computation: Apply gating curve

4. Gain Application: Convert to linear gain and apply

The noise gate implements the following gain computation:

Hard Knee:

\[\begin{split}g(x) = \begin{cases} R, & \text{if } x \leq T \\ 0, & \text{if } x > T \end{cases}\end{split}\]

Variables:

• x: input level in dB

• T: threshold in dB

• R: range in dB (negative value)

• W: knee width in dB

Parameters:

• sample_rate (int) – Audio sample rate in Hz. Defaults to 44100.

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• knee_type (str, optional) – Type of gating knee curve. Must be one of: “hard”, “quadratic”. Defaults to “hard”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

knee_type

Current knee characteristic type

Type:

str

smoothing_type

Current envelope follower type

Type:

str

ballistics

Envelope follower for attack/release

Type:

Ballistics

iir_filter

IIR filter for smoothing

Type:

TruncatedOnePoleIIRFilter

Parameters Details:

threshold_db: Level at which gating begins

• Controls where gating starts to take effect

• More negative values gate more of the signal

range_db: Amount of attenuation below threshold

• Controls how much the signal is reduced when below threshold

• More negative values mean more attenuation

knee_db: Width of the transition region around threshold

• 0 dB creates a hard knee (sudden transition)

• Larger values create smoother transitions

• Affects how gradually gating is applied

attack_ms: Time taken to react to increases in level

• Shorter times mean faster response to transients

• Longer times let more of the transient through

release_ms: Time taken to react to decreases in level

• Controls how quickly gating is reduced

• Affects the “movement” of the gating

Note

The processor supports the following parameter ranges:

• threshold_db: Threshold level in dB (-90 to -20)

• range_db: Attenuation range in dB (-90 to 0)

• knee_db: Knee width in dB (0 to 6)

• attack_ms: Attack time in ms (0.1 to 20)

• release_ms: Release time in ms (5 to 1000)

Warning

When using with neural networks:

• norm_params must be in range [0, 1]

• Parameters will be automatically mapped to their DSP ranges

• Ensure your network output is properly normalized (e.g., using sigmoid)

• Parameter order must match _register_default_parameters()

Examples

Basic DSP Usage:

>>> # Create a noise gate with hard knee
>>> gate = NoiseGate(
...     sample_rate=44100,
...     knee_type="hard",
...     smooth_type="ballistics"
... )
>>> # Process audio with dsp parameters
>>> output = gate(input_audio, dsp_params={
...     'threshold_db': -40.0,
...     'range_db': -60.0,
...     'knee_db': 0.0,
...     'attack_ms': 1.0,
...     'release_ms': 50.0
... })

Neural Network Control:

>>> # 1. Simple parameter prediction
>>> class NoiseGateController(nn.Module):
...     def __init__(self, input_size, num_params):
...         super().__init__()
...         self.net = nn.Sequential(
...             nn.Linear(input_size, 32),
...             nn.ReLU(),
...             nn.Linear(32, num_params),
...             nn.Sigmoid()  # Ensures output is in [0,1] range
...         )
...
...     def forward(self, x):
...         return self.net(x)
>>>
>>> # Initialize controller
>>> num_params = gate.count_num_parameters()  # 5 parameters
>>> controller = NoiseGateController(input_size=16, num_params=num_params)
>>>
>>> # Process with features
>>> features = torch.randn(batch_size, 16)  # Audio features
>>> norm_params = controller(features)
>>> output = gate(input_audio, norm_params=norm_params)

A noise gate that reduces the volume of quiet audio signals.

__init__(sample_rate, param_range=None)

Initialize the compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• knee_type (str) – Type of compression knee curve

• smooth_type (str) – Type of envelope follower

Raises:

ValueError – If knee_type or smooth_type is invalid

_compute_gain(level_db, threshold_db, range_db, knee_db)

Compute noise gate gain.

Parameters:

• level_db (Tensor) –

• threshold_db (Tensor) –

• range_db (Tensor) –

• knee_db (Tensor) –

Return type:

Tensor

process(x, norm_params=None, dsp_params=None)

Process input signal through the compressor.

Parameters:

• x (torch.Tensor) – Input audio tensor. Shape: (batch, channels, samples)

• norm_params (Dict[str, torch.Tensor]) – Normalized parameters (0 to 1) Dictionary with keys: - ‘threshold_db’: Level at which compression begins (-60 to 0 dB) - ‘ratio’: Amount of gain reduction above threshold (1 to 20) - ‘knee_db’: Width of transition region around threshold (0 to 12 dB) - ‘attack_ms’: Time to react to level increases (0.1 to 100 ms) - ‘release_ms’: Time to react to level decreases (10 to 1000 ms) - ‘makeup_db’: Gain applied after compression (-12 to 12 dB) Each value should be a tensor of shape (batch_size,) Values will be mapped to their respective ranges

• dsp_params (Dict[str, Union[float, torch.Tensor]], optional) – Direct DSP parameters. Can specify parameters as: - float/int: Single value applied to entire batch - 0D tensor: Single value applied to entire batch - 1D tensor: Batch of values matching input batch size Parameters will be automatically expanded to match batch size and moved to input device if necessary. If provided, norm_params must be None.

Returns:

Processed audio tensor of same shape as input

Return type:

torch.Tensor

Multi-band Noise Gate

class diffFx_pytorch.processors.dynamics.MultiBandNoiseGate(*args: Any, **kwargs: Any)

Bases: MultiBandCompressor

Differentiable multi-band noise gate.

This processor splits the input signal into multiple frequency bands using Linkwitz-Riley crossover filters and applies independent noise gating to each band. The processed bands are then summed to produce the final output.

Implementation is based on the following references:

[1]

MATLAB Audio Toolbox. “Multiband Dynamic Range Compression.” https://www.mathworks.com/help/audio/ug/multiband-dynamic-range-compression.html

[2]

Giannoulis, D., Massberg, M., & Reiss, J. D. (2012). “Digital dynamic range compressor design—A tutorial and analysis.” Journal of the Audio Engineering Society, 60(6), 399-408.

Processing Chain:

1. Band Splitting: Split input into frequency bands using Linkwitz-Riley filters

2. Per-band Processing:

   1. Level Detection: Compute RMS energy and convert to dB

   2. Envelope Following: Smooth level using attack/release ballistics

   3. Gain Computation: Apply gating curve based on knee type

   4. Gain Application: Convert to linear gain and apply to band

3. Band Summation: Sum all processed bands to create final output

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• param_range (Dict[str, EffectParam], optional) – Parameter ranges.

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

• knee_type (str, optional) – Type of gating knee curve. Must be one of: “hard”, “quadratic”. Defaults to “hard”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

Parameters Details:

For each band i (0 to num_bands-1):

band{i}_threshold_db: Level at which gating begins

• Controls where gating starts for this band (-90 to -20 dB)

band{i}_range_db: Amount of attenuation below threshold

• Controls how much the signal is reduced (-90 to 0 dB)

band{i}_knee_db: Width of transition region around threshold

• Controls how gradually gating is applied (0 to 6 dB)

band{i}_attack_ms: Time to react to level increases

• Controls response to transients (0.1 to 20 ms)

band{i}_release_ms: Time to react to level decreases

• Controls recovery time (5 to 1000 ms)

Crossover frequencies:

crossover{i}_freq: Split frequency between bands i and i+1

• Logarithmically spaced between bands

• Range varies based on position (20 Hz to 20 kHz)

Note

• Uses 4th-order Linkwitz-Riley crossover filters

• Band splitting is done in series for proper phase alignment

• Each band has independent gating parameters

• Parameters can be controlled via normalized (0-1) or DSP values

• Total parameters = num_bands * 5 + (num_bands - 1)

Examples

Basic Usage:

>>> # Create a 3-band noise gate
>>> mb_gate = MultiBandNoiseGate(
...     sample_rate=44100,
...     num_bands=3
... )
>>> # Process with DSP parameters
>>> output = mb_gate(input_audio, dsp_params={
...     'band0_threshold_db': -50.0,  # Low band
...     'band0_range_db': -60.0,
...     'band0_knee_db': 0.0,
...     'band0_attack_ms': 1.0,
...     'band0_release_ms': 50.0,
...     'band1_threshold_db': -45.0,  # Mid band
...     'band1_range_db': -60.0,
...     'band1_knee_db': 0.0,
...     'band1_attack_ms': 0.5,
...     'band1_release_ms': 30.0,
...     'band2_threshold_db': -40.0,  # High band
...     'band2_range_db': -60.0,
...     'band2_knee_db': 0.0,
...     'band2_attack_ms': 0.1,
...     'band2_release_ms': 20.0,
...     'crossover0_freq': 200.0,     # Low-Mid split
...     'crossover1_freq': 2000.0     # Mid-High split
... })

Neural Network Control:

>>> # Create parameter prediction network
>>> class MultiBandNoiseGateNet(nn.Module):
...     def __init__(self, input_size, num_bands):
...         super().__init__()
...         num_params = num_bands * 5 + (num_bands - 1)
...         self.net = nn.Sequential(
...             nn.Linear(input_size, 32),
...             nn.ReLU(),
...             nn.Linear(32, num_params),
...             nn.Sigmoid()  # Ensures output is in [0,1] range
...         )
...
...     def forward(self, x):
...         return self.net(x)
>>>
>>> # Process with predicted parameters
>>> controller = MultiBandNoiseGateNet(input_size=16, num_bands=3)
>>> norm_params = controller(features)  # Shape: [batch_size, 17]
>>> output = mb_gate(input_audio, norm_params=norm_params)

A multi-band noise gate that applies independent noise gating to different frequency bands.

__init__(sample_rate, param_range=None, num_bands=3)

Initialize the multi-band compressor.

Parameters:

• sample_rate (int) – Audio sample rate in Hz

• num_bands (int, optional) – Number of frequency bands. Defaults to 3.

• knee_type (str, optional) – Type of compression knee curve. Must be one of: “hard”, “quadratic”, “exponential”. Defaults to “quadratic”.

• smooth_type (str, optional) – Type of envelope follower. Must be one of: “ballistics”, “iir”. Defaults to “ballistics”.

Raises:

• ValueError – If knee_type is not one of “hard”, “quadratic”, or “exponential”

• ValueError – If smooth_type is not one of “ballistics” or “iir”

Note

Initializes crossover filters as a ModuleList with (num_bands - 1) filters to split the input into num_bands frequency bands.

_compute_gain(level_db, threshold_db, range_db, knee_db)

Compute noise gate gain for each band.

Parameters:

• level_db (Tensor) –

• threshold_db (Tensor) –

• range_db (Tensor) –

• knee_db (Tensor) –

Return type:

Tensor

_process_band(x, band_params)

Process a single frequency band with noise gating.

Parameters:

• x (Tensor) –

• band_params (Dict[str, Tensor]) –

Return type:

Tensor

Transient Shaper