Base Classes

Base Processor

class diffFx_pytorch.processors.base.EffectParam(min_val, max_val, default=None)[source]

Bases: object

Parameters:
min_val: float
max_val: float
default: float = None
__init__(min_val, max_val, default=None)
Parameters:
class diffFx_pytorch.processors.base.ProcessorsBase(sample_rate=44100, param_range=None)[source]

Bases: Module

Base class for differentiable audio effect processors.

This class provides the foundation for implementing audio effects processors with support for both normalized (0-1) and direct DSP parameter control. It handles parameter registration, validation, and mapping between normalized and DSP value ranges.

The class supports two parameter interfaces:

  1. Normalized parameters (0-1 range) for neural network control

  2. Direct DSP parameters with actual audio processing values

Parameters:

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

  • param_range (Dict[str, EffectParam], optional) – Optional parameter definitions to override or extend default parameters.

sample_rate

Sampling rate in Hz

Type:

int

params

Registered effect parameters

Type:

Dict[str, EffectParam]

Parameter Management:
Parameters are defined using EffectParam dataclass with:

  • min_val: Minimum DSP value

  • max_val: Maximum DSP value

  • default: Optional default value

Example

Basic Implementation:
>>> class MyEffect(ProcessorsBase):
...     def _register_default_parameters(self):
...         self.params = {
...             'frequency': EffectParam(min_val=20.0, max_val=20000.0),
...             'gain_db': EffectParam(min_val=-24.0, max_val=24.0)
...         }
...
...     def process(self, x, norm_params, dsp_params):
...         # Implement effect processing here
...         pass
Parameter Usage:
>>> effect = MyEffect(sample_rate=44100)
>>> # Using DSP parameters
>>> output = effect(input_audio, dsp_params={
...     'frequency': 1000.0,  # Direct Hz value
...     'gain_db': -6.0       # Direct dB value
... })
>>>
>>> # Using normalized parameters (e.g., from neural network)
>>> norm_params = torch.tensor([[0.5, 0.3]])  # [batch, num_params]
>>> output = effect(input_audio, norm_params=norm_params)
__init__(sample_rate=44100, param_range=None)[source]

Initialize the processor base.

Parameters:

  • sample_rate (int) – Audio sample rate in Hz

  • param_range (Optional[Dict[str, EffectParam]]) – Optional parameter definitions to override defaults

_register_default_parameters()[source]

Register default parameters for the processor.

Override this method to define processor-specific parameters using EffectParam dataclass instances.

_tensor_to_dict(tensor)[source]

Convert parameter tensor to dictionary

Parameters:

tensor (Tensor) –

Return type:

Dict[str, Tensor]

map_parameters(norm_params)[source]

Maps normalized parameters (0-1) to DSP parameter ranges.

Parameters:

norm_params (Dict[str, Tensor]) – Dictionary of normalized parameter values

Return type:

Dict[str, Tensor]

Returns:

Dictionary of mapped DSP parameter values

Note

Linear interpolation is used for mapping: dsp_value = min_val + (max_val - min_val) * norm_value

demap_parameters(dsp_params)[source]

Maps DSP parameters back to normalized range (0-1).

Parameters:

dsp_params (Dict[str, Tensor]) – Dictionary of DSP parameter values

Return type:

Dict[str, Tensor]

Returns:

Dictionary of normalized parameter values

create_dsp_params_batch(params_dict, batch_size=1, device='cpu')[source]

Creates batched tensor parameters from scalar DSP values.

Parameters:

  • params_dict (Dict[str, float]) – Dictionary of parameter names and scalar values

  • batch_size (int) – Number of copies in batch

  • device (Union[str, device]) – Target device for tensors

Return type:

Dict[str, Tensor]

Returns:

Dictionary of batched parameter tensors

Raises:

  • KeyError – If parameter name not registered

  • ValueError – If value outside valid range

forward(x, norm_params=None, dsp_params=None)[source]

Process input with either normalized or DSP parameters.

Parameters:

  • x (Tensor) – Input audio tensor [batch, channels, samples]

  • norm_params (Optional[Tensor]) – Optional normalized parameters tensor [batch, num_params]

  • dsp_params (Optional[Dict[str, Union[float, Tensor]]]) – Optional DSP parameters dictionary Each parameter can be: - float/int: Single value for all batch items - 0D tensor: Single value for all batch items - 1D tensor: Batch-specific values

Return type:

Tensor

Returns:

Processed audio tensor

Raises:

  • KeyError – If unknown parameter name provided

  • TypeError – If parameter has invalid type

  • ValueError – If tensor parameter shape invalid

Note

Only one of norm_params or dsp_params should be provided.

process(x, norm_params=None, dsp_params=None)[source]

Process audio with the effect (to be implemented by subclasses).

Parameters:
Return type:

Tensor

Returns:

Processed audio tensor

count_num_parameters()[source]

Returns the number of effect parameters.

Returns:

Number of registered parameters

Utility Functions

diffFx_pytorch.processors.base_utils.check_params(norm_params, dsp_params)[source]

Check parameters validity: 1. At least one parameter should not be None 2. Both parameters cannot be not None simultaneously

Parameters:

  • norm_params – Dictionary of normalized parameters or None

  • dsp_params – Dictionary of DSP parameters or None

Raises:

ValueError – If both parameters are None or both are not None

Return type:

None

diffFx_pytorch.processors.base_utils.create_dsp_params_batch(params_dict, batch_size, device='cpu')[source]

Convert scalar DSP parameters to batched tensor parameters.

Parameters:

  • params_dict (Dict[str, float]) – Dictionary of parameter names and their scalar values

  • batch_size (int) – Number of copies to create in batch

  • device (str) – Target device for tensors

Return type:

Dict[str, Tensor]

Returns:

Dictionary of parameter names and their batched tensor values