Processors

Collection of processors for audio signals.

This module is part of the libdamp package.

class libdamp.processors.Processor(*args: Any, **kwargs: Any)

Bases: ABC, Module

Abstract base class for stateful audio processors in libdamp.

Child classes must implement three core methods: - process(): process a given input signal - update(): set parameters of the processor - clear(): reset internal states to initial state

abstractmethod process(*args, **kwargs) → Tensor

Process an audio signal.

Receives an audio signal x as input and should return a processed audio signal y, where the appropriate processing depends on the set parameters in update().

abstractmethod update(*args, **kwargs) → None

Update processor parameters.

Change the parameters that influence how the signal is processed in process(). Actual arguments depend on the implemented functionality and should be documented in derived classes.

abstractmethod clear() → None

Reset processor internal state.

If the processor has state (i.e., a call to process() depends on previous calls), this method should reset any state variables so that the processor behaves as if process() was never called on that instance before.

forward(*args, **kwargs) → Tensor

Process audio (implements torch.nn.Module forward pass).

Calls process() with the provided arguments.

Returns:

Processed audio signal.

Return type:

torch.Tensor

class libdamp.processors.GainEnvelope(interp_mode: Literal['const', 'center_linear', 'end_linear', 'half_linear', 'const_smooth'] = 'const')

Bases: Processor

Multiply audio with a prescribed gain envelope

process(x: Tensor) → Tensor

Process audio with the gain envelope.

Parameters:

x (torch.Tensor or array-like) – Input audio signal(s). Shape can be (batch, length) or (batch, channels, length).

Returns:

Processed audio signal with envelope applied, same shape as input.

Return type:

torch.Tensor

update(g, initial_g=None)

Update the gain envelope.

Parameters:

• g (torch.Tensor or array-like) – Gain envelope, shape (batch, frames) or (batch, channels, frames).

• initial_g (torch.Tensor or array-like, optional) – Initial gain value for state continuity from previous processing, shape (batch, frames) or (batch, channels, frames) (default: None).

clear()

Reset processor internal state.

If the processor has state (i.e., a call to process() depends on previous calls), this method should reset any state variables so that the processor behaves as if process() was never called on that instance before.

class libdamp.processors.ButterworthLowPassFilter(frame_len: int, fs: float, order: int = 2, cascades: int = 1)

Bases: Processor

Butterworth low-pass filter processor.

Processes signal with cascaded Butterworth low-pass filters using IIR frequency sampling design.

process(x: Tensor) → Tensor

Process audio with the cascaded Butterworth low-pass filters.

Parameters:

x (torch.Tensor) – Input audio signal(s). Shape can be (batch, length) or (batch, channels, length).

Returns:

Processed audio signal, same shape as input.

Return type:

torch.Tensor

update(fc: Tensor) → None

Update the filter cutoff frequency.

Parameters:

fc (torch.Tensor or array-like) – Cutoff frequency in Hz, shape (batch, frames).

clear()

Reset processor internal state.

If the processor has state (i.e., a call to process() depends on previous calls), this method should reset any state variables so that the processor behaves as if process() was never called on that instance before.

class libdamp.processors.ResonantFilter(frame_len: int, fs: float)

Bases: Processor

Parallel processing with biquad filters that represent individual resonances (or “formants”)

process(x: Tensor) → Tensor

Process audio with the parallel resonant filters.

Parameters:

x (torch.Tensor) – Input audio signal(s). Shape can be (batch, length) or (batch, channels, length).

Returns:

Processed audio signal, same shape as input.

Return type:

torch.Tensor

update(f, r)

Update the resonant filter parameters.

Parameters:

• f (torch.Tensor or array-like) – Center frequencies in Hz, shape (batch, num_filters, frames).

• r (torch.Tensor or array-like) – Resonance radii between 0 and 1, shape (batch, num_filters, frames).

clear()

Reset processor internal state.

If the processor has state (i.e., a call to process() depends on previous calls), this method should reset any state variables so that the processor behaves as if process() was never called on that instance before.

class libdamp.processors.TVFIRFilter(frame_len: int, filt_len: int, with_crossfade: bool = False, crossfade_len: int | None = None)

Bases: Processor

Time-varying FIR filter processor.

Applies blockwise processing of audio with time-varying FIR filters. Supports optional crossfading for smooth transitions between filters.

process(x: Tensor) → Tensor

Process audio with time-varying FIR filters.

Parameters:

x (torch.Tensor) – Input audio signal(s). Shape must be (batch, length) or (batch, channels, length). The length must be divisible by the frame length N given at initialization.

Returns:

Processed audio signal with time-varying FIR filtering applied.

Return type:

torch.Tensor

update(h) → None

Update the FIR filter coefficients.

Parameters:

h (torch.Tensor or array-like) – Filter coefficients, shape (batch, num_filters, filter_length). The filters are repeated across frames if fewer filters than signal frames are provided.

clear()

Reset processor internal state.

If the processor has state (i.e., a call to process() depends on previous calls), this method should reset any state variables so that the processor behaves as if process() was never called on that instance before.

class libdamp.processors.TVMagnitudesFilter(frame_len: int, filt_len: int, fs: float, center_freqs: Tensor = tensor([31.2500, 62.5000, 125.0000, 250.0000, 500.0000, 1000.0000, 2000.0000, 4000.0000, 8000.0000, 16000.0000]), with_crossfade: bool = False, crossfade_len: int | None = None, filter_phase: Literal['linear', 'minimum'] = 'minimum')

Bases: TVFIRFilter

Time-varying FIR filter processor based on a given magnitude response.

Applies blockwise processing of audio with time-varying FIR filters defined by magnitude specifications using design_fir_filter. This is a specialization of [TVFIRFilter][libdamp.processors.tv_fir_filter.TVFIRFilter] that derives the filter taps from a magnitude response instead of taking them directly. process() is inherited unchanged.

update(magnitudes)

Update the filter magnitude response.

Parameters:

magnitudes (torch.Tensor or array-like) – Desired magnitude response at center frequencies, shape (batch, num_filters, num_freqs) where num_freqs matches the number of center frequencies.