class flamo.processor.dsp.Transform(transform: callable = <function Transform.<lambda>>, device: str | None = None)

Base class for all transformations.

The transformation is a callable (e.g. lambda expression, function, or nn.Module).

Arguments / Attributes:

  • transform (callable): The transformation function to be applied to the input. Default: lambda x: x

  • device (str): The device of the constructed tensor, if any. Default: None.

Examples:

>>> pow2 = Transform(lambda x: x**2)
>>> input = torch.tensor([1, 2, 3])
>>> pow2(input)
tensor([1, 4, 9])
forward(x: Tensor)

Calls transformation function on the input tensor.

Arguments:

x (Tensor): The input tensor.

Returns:

The transformed tensor.

class flamo.processor.dsp.FFT(nfft: int = 2048, norm: str = 'backward')

Bases: Transform

Real Fast Fourier Transform (FFT) class.

The FFT class is an instance of the Transform class in which transformation is the torch.fft.rfft() function. Computes the one dimensional Fourier transform of real-valued input. The input is interpreted as a real-valued signal in time domain. The output contains only the positive frequencies below the Nyquist frequency.

Arguments / Attributes:

  • nfft (int): The number of points to compute the FFT.

  • norm (str): The normalization mode for the FFT.

For details on the real FFT function, see torch.fft.rfft documentation.

class flamo.processor.dsp.iFFT(nfft: int = 2048, norm: str = 'backward')

Bases: Transform

Inverse Fast Fourier Transform (iFFT) class.

The iFFT class is an instance of the Transform class in which transformation is the torch.fft.irfft() function. Computes the inverse of the Fourier transform of a real-valued tensor. The input is interpreted as a one-sided Hermitian signal in the Fourier domain. The output is a real-valued signal in the time domain.

Arguments / Attributes:

  • nfft (int): The size of the FFT. Default: 2**11.

  • norm (str): The normalization mode. Default: “backward”.

For details on the inverse real FFT function, see torch.fft.irfft documentation.

class flamo.processor.dsp.FFTAntiAlias(nfft: int = 2048, norm: str = 'backward', alias_decay_db: float = 0.0, device: str | None = None)

Bases: Transform

Real Fast Fourier Transform (FFT) class with time-aliasing mitigation enabled.

Computes the one dimensional Fourier transform of real-valued tensor torch.fft.rfft() after multiplying it by an by an exponentially decaying envelope to mitigate time aliasing. The input is interpreted as a real-valued signal in time domain. The output contains only the positive frequencies below the Nyquist frequency.

Arg / Attributes:

  • nfft (int): The number of points to compute the FFT.

  • norm (str): The normalization mode for the FFT.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. Default: 0.0.

  • device (str): The device of the constructed tensors. Default: None.

For details on the FFT function, see torch.fft.rfft documentation.

class flamo.processor.dsp.iFFTAntiAlias(nfft: int = 2048, norm: str = 'backward', alias_decay_db: float = 0.0, device: str | None = None)

Bases: Transform

Inverse Fast Fourier Transform (iFFT) class with time-aliasing mitigation enabled.

Computes the inverse of the Fourier transform of a real-valued tensor torch.fft.irfft() to which anti time aliasing has been applied. The input is interpreted as a one-sided Hermitian signal in the Fourier domain evaluated outside of the unit circle to reduce time aliasing. The output of the inverse FFT is a real-valued signal in the time domain multiplied by the anti-aliasing exponentially rising envelope.

Arguments / Attributes:

  • nfft (int): The size of the FFT. Default: 2**11.

  • norm (str): The normalization mode. Default: “backward”.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. Default: 0.0.

  • device (str): The device of the constructed tensors. Default: None.

For details on the inverse FFT function, see torch.fft.irfft documentation.

class flamo.processor.dsp.DSP(size: tuple, nfft: int = 2048, map: callable = <function DSP.<lambda>>, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Processor core module consisting of learnable parameters representing a Linear Time-Invariant (LTI) system, which is then convolved with the input signal.

The parameters are stored in param tensor whose values at initialization are drawn from the normal distribution \(\mathcal{N}(0, 1)\) and can be modified using the assign_value() method.

The anti aliasing envelope is computed using the get_gamma() method from the alias_decay_db attribute which determines the decay in dB reached by the exponentially decaying envelope \(\gamma(n)\) after nfft samples. The envelope \(\gamma(n)\) is then applied to the time domain signal before computing the FFT

Arguments / Attributes:

  • size (tuple): The shape of the parameters before mapping.

  • nfft (int, optional): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • map (function, optional): The mapping function applied to the raw parameters. Default: lambda x: x.

  • requires_grad (bool, optional): Whether the parameters require gradients. Default: False.

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str): The device of the constructed tensor, if any. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the DSP module.

  • fft (function): The FFT function. Calls the torch.fft.rfft() function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft().

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

assign_value(new_value: Tensor, indx: tuple = (slice(None, None, None),))

Assigns new values to the parameters.

Arguments:

  • new_value (torch.Tensor): New values to be assigned.

  • indx (tuple, optional): Specifies the index of the values to be assigned. Default: tuple([slice(None)]).

Warning

the gradient calculation is disable when assigning new values to param.

forward(x, **kwArguments)

Forward method.

Input is returned. Forward method is to be implemented by the child class.

get_gamma()

Calculate the value of \(\gamma\) based on the alias decay in dB and the number of FFT points. The value of \(\gamma\) is computed as follows and saved in the attribute gamma:

\[\gamma = 10^{\frac{-|\alpha_{\text{dB}}|}{20 \cdot \texttt{nfft}}}\; \text{and}\; \gamma(n) = \gamma^{n}\]

where \(\alpha_{\textrm{dB}}\) is the alias decay in dB, \(\texttt{nfft}\) is the number of FFT points, and \(n\) is the discrete time index \(0\\leq n < N\), where N is the length of the signal.

init_param()

It uses the torch.nn.init.normal_() function to set the values of param by drawing from the normal distribution \(\mathcal{N}(0, 1)\).

class flamo.processor.dsp.Gain(size: tuple = (1, 1), nfft: int = 2048, map: callable = <function Gain.<lambda>>, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: DSP

A class representing a set of gains.

The input tensor is expected to be a complex-valued tensor representing the frequency response of the input signal. The input tensor is then multiplied with the gain to produce the output tensor.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, and \(N_{out}\) is the number of output channels. Ellipsis \((...)\) represents additional dimensions.

Arguments / Attributes:

  • size (tuple): The size of the gain parameters. Default: (1, 1).

  • nfft (int): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • map (function): A mapping function applied to the raw parameters. Default: lambda x: x.

  • requires_grad (bool): Whether the parameters requires gradients. Default: False.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str): The device of the constructed tensors. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the Gain module.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

check_input_shape(x)

Checks if the dimensions of the input tensor x are compatible with the module.

Arguments:

x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

check_param_shape()

Checks if the shape of the gain parameters is valid.

forward(x, ext_param=None)

Applies the Gain module to the input tensor x.

Arguments:

  • x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

  • ext_param (torch.Tensor, optional): Parameter values received from external modules (hyper conditioning). Default: None.

Returns:

torch.Tensor: Output tensor of shape \((B, M, N_{out}, ...)\).

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_io()

Computes the number of input and output channels based on the size parameter.

initialize_class()

Initializes the Gain module.

This method checks the shape of the gain parameters and computes the frequency convolution function.

class flamo.processor.dsp.Matrix(size: tuple = (1, 1), nfft: int = 2048, map: callable = <function Matrix.<lambda>>, matrix_type: str = 'random', requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Gain

A class representing a matrix.

The input tensor is expected to be a complex-valued tensor representing the frequency response of the input signal. The input tensor is multiplied with the matrix to produce the output tensor.

Arguments / Attributes:

  • size (tuple, optional): The size of the matrix. Default: (1, 1).

  • nfft (int, optional): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • map (function, optional): The mapping function to apply to the raw matrix elements. Default: lambda x: x.

  • matrix_type (str, optional): The type of matrix to generate. Default: “random”.

  • requires_grad (bool, optional): Whether the matrix requires gradient computation. Default: False.

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str, optional): The device of the constructed tensors. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the Matrix module.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • new_value (int): Flag indicating if new values have been assigned.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

initialize_class()

Initializes the Matrix module.

This method checks the shape of the matrix parameters, sets the matrix type, generates the matrix, and computes the frequency convolution function.

Generates the matrix based on the specified matrix type. The map attribute will be overwritten based on the matrix type.

class flamo.processor.dsp.HouseholderMatrix(size: tuple = (1, 1), nfft: int = 2048, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Gain

A class representing an Householder matrix.

An Householder matrix \(\mathbf{U}\) can be computed as follows

\[\mathbf{U} = \mathbf{I} - 2uu^T\]

where \(\mathbf{I}\) is the identity matrix and \(u\) is a unitary vector.

Arguments:

  • size (tuple, optional): Size of the matrix. Must be a square matrix. Defaults to (1, 1).

  • nfft (int, optional): Number of FFT points. Defaults to 2**11.

  • requires_grad (bool, optional): If True, gradients will be computed for the parameters. Defaults to False.

  • alias_decay_db (float, optional): Alias decay in decibels. Defaults to 0.0.

  • device (optional): Device on which to perform computations. Defaults to None.

Attributes:

  • param (nn.Parameter): The parameters u` used to construct the Householder matrix.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • map (function): A mapping function applied to the raw parameter vector \(u\) to make it unitary.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

check_input_shape(x)

Checks if the dimensions of the input tensor x are compatible with the module.

Arguments:

x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

forward(x, ext_param=None)

Applies the Householder to the input tensor x.

The multiplication is done more efficiently by using vector multiplications with \(u\) instead of matrix multiplications.

\[ \begin{align}\begin{aligned}u^T x = \sum_{m=1}^{M} u_m x_m\\\mathbf{U}x = uu^T x = \sum_{n=1}^{N} u_n (u^T x)_n\end{aligned}\end{align} \]
Arguments:

  • x (torch.Tensor): Input tensor of shape \((B, M, N, ...)\).

  • ext_param (torch.Tensor, optional): Parameter values received from external modules (hyper conditioning). Default: None.

Returns:

torch.Tensor: Output tensor of shape \((B, M, N, ...)\).

get_io()

Computes the number of input and output channels based on the size parameter.

class flamo.processor.dsp.Filter(size: tuple = (1, 1, 1), nfft: int = 2048, map: callable = <function Filter.<lambda>>, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: DSP

A class representing a set of FIR filters.

The input tensor is expected to be a complex-valued tensor representing the frequency response of the input signal. The input tensor is then convolved in frequency domain with the filter frequency responses to produce the output tensor. In case the mapping function is map=lambda x: x (default), the filter parameters correspond to the filter impulse responses.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((N_{taps}, N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, \(N_{out}\) is the number of output channels, and \(N_{taps}\) is the number of filter parameters per input-output channel pair. By default, \(N_{taps}\) correspond to the length of the FIR filters. Ellipsis \((...)\) represents additional dimensions.

Arguments / Attributes:

  • size (tuple): The size of the filter parameters. Default: (1, 1, 1).

  • nfft (int): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • map (function): A mapping function applied to the raw parameters. Default: lambda x: x.

  • requires_grad (bool): Whether the filter parameters require gradients. Default: False.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str): The device of the constructed tensors. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the Filter module.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • freq_response (torch.Tensor): The frequency response of the filter.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

check_input_shape(x)

Checks if the dimensions of the input tensor x are compatible with the module.

Arguments:

x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

check_param_shape()

Checks if the shape of the filter parameters is valid.

forward(x, ext_param=None)

Applies the Filter module to the input tensor x.

Arguments:

  • x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

  • ext_param (torch.Tensor, optional): Parameter values received from external modules (hyper conditioning). Default: None.

Returns:

torch.Tensor: Output tensor of shape \((B, M, N_{out}, ...)\).

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_freq_response()

Computes the frequency response of the filter.

The mapping function is applied to the filter parameters to obtain the filter impulse responses. Then, the time anti-aliasing envelope is computed and applied to the impulse responses. Finally, the frequency response is obtained by computing the FFT of the filter impulse responses.

get_io()

Computes the number of input and output channels based on the size parameter.

initialize_class()

Initializes the Filter module.

This method checks the shape of the gain parameters, computes the frequency response of the filter, and computes the frequency convolution function.

class flamo.processor.dsp.parallelFilter(size: tuple = (1, 1), nfft: int = 2048, map: callable = <function parallelFilter.<lambda>>, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Filter

Parallel counterpart of the Filter class. For information about attributes and methods see Filter.

Shape:

  • input: \((B, M, N, ...)\)

  • param: \((N_{taps}, N)\)

  • output: \((B, M, N, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N\) is the number of input channels, and \(N_{taps}\) is the number of filter parameters per input-output channel pair. Ellipsis \((...)\) represents additional dimensions.

check_param_shape()

Checks if the shape of the filter parameters is valid.

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_io()

Computes the number of input and output channels based on the size parameter.

class flamo.processor.dsp.ScatteringMatrix(size: tuple = (1, 1, 1), nfft: int = 2048, sparsity: int = 3, gain_per_sample: float = 0.9999, pulse_size: int = 1, m_L: tensor = None, m_R: tensor = None, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Filter

A class representing a set of Scattering Filter matrix.

The ScatteringMatrix was designed as filter feedback matrix of the

Feedback Delay Network (FDN) reverberator structure.

It is parameterized as a set of \(K\) orthogonal mixing matrices \(\mathbf{U}_k\) each followed by a set of parallel delays.

\[\mathbf{U}(z) = \mathbf{D}_{\mathbf{m}_K+1}(z)\mathbf{U}_K\cdots\mathbf{U}_2\mathbf{D}_{\mathbf{m}_2}(z)\mathbf{U}_1\mathbf{D}_{\mathbf{m}_1}(z)\mathbf{U}_0\mathbf{D}_{\mathbf{m}_0}(z),\]

where \(\mathbf{U}_1, \dots, \mathbf{U}_K\) are \(N \times N\) orthogonal matrices and \(\mathbf{m}_0, \dots, \mathbf{m}_{K+1}\) are vectors of \(N\) integer delays. This parameterization ensures that the scattering matrix is paraunitary and lossless.

For more details, refer to the paper Scattering in Feedback Delay Networks by Schlecht, S. J. et al.

The input tensor is expected to be a complex-valued tensor representing the frequency response of the input signal. The input tensor is then convolved in frequency domain with the filter frequency responses to produce the output tensor.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((N_{taps}, N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, \(N_{out}\) is the number of output channels, and \(N_{taps}\) is the number of filter parameters per input-output channel pair. By default, \(N_{taps}\) correspond to the length of the FIR filters. Ellipsis \((...)\) represents additional dimensions.

Arguments / Attributes:

  • size (tuple): The size of the filter parameters. Default: (1, 1, 1).

  • nfft (int): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • sparsity (int): The sparsity of the scattering matrix. Default: 3.

  • gain_per_sample (float): The gain per sample. This is useful when ensuring homogeneous decay in FDNs Default: 0.9999.

  • pulse_size (int): The size of the filter’s taps. Default: 1.

  • m_L (torch.tensor): The leftmost delay vector. Default: None.

  • m_R (torch.tensor): The rightmost delay vector. Default: None.

  • requires_grad (bool): Whether the filter parameters require gradients. Default: False.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str): The device of the constructed tensors. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the Filter module.

  • map (function): Mapping function to ensure orthogonality of \(\mathbf{U}_k\).

  • map_filter (ScatteringMapping): Mapping function to generate the filter matrix.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • freq_response (torch.Tensor): The frequency response of the filter.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_freq_response()

Computes the frequency response of the filter.

The mapping function is applied to the filter parameters to obtain the filter impulse responses. Then, the time anti-aliasing envelope is computed and applied to the impulse responses. Finally, the frequency response is obtained by computing the FFT of the filter impulse responses.

initialize_class()

Initializes the ScatteringMatrix module.

This method creates the mapping to generate the filter matrix, checks the shape of the gain parameters, computes the frequency response of the filter, and computes the frequency convolution function.

class flamo.processor.dsp.Biquad(size: tuple = (1, 1), n_sections: int = 1, filter_type: str = 'lowpass', nfft: int = 2048, fs: int = 48000, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Filter

A class representing a set of Biquad filters.

It supports class lowpass, highpass, and bandpass filters using RBJ cookbook formulas, which map the cut-off frequency \(f_{c}\) and gain \(g\) parameters to the \(\mathbf{b}\) and \(\mathbf{a}\) coefficients. The transfer function of the filter is given by

\[H(z) = \frac{b_0 + b_1 z^{-1} + b_2 z^{-2}}{a_0 + a_1 z^{-1} + a_2 z^{-2}}\]

The mapping from learnable parameters \(\mathbf{f_c}\) and \(\mathbf{g}\) are defined by flamo.functional.lowpass_filter(), flamo.functional.highpass_filter(), flamo.functional.bandpass_filter().

Shape:

  • input: \((B, M, N_{\text{in}}, ...)\)

  • param: \((K, P, N_{\text{out}}, N_{\text{in}})\)

  • freq_response: \((M, N_{\text{out}}, N_{\text{in}})\)

  • output: \((B, M, N_{\text{out}}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, and \(N_{\text{in}}\) is the number of input channels, and \(N_{\text{out}}\) is the number of output channels. The param attribute represent the biquad filter coefficents. The first dimension of the para’ tensor corresponds to the number of filters \(K\), the second dimension corresponds to the number of filter parameters \(P\). Ellipsis \((...)\) represents additional dimensions (not tested).

Arguments / Attributes:

  • size (tuple, optional): Size of the filter. Default: (1, 1).

  • n_sections (int, optional): Number of filters. Default: 1.

  • filter_type (str, optional): Type of the filter. Must be one of “lowpass”, “highpass”, or “bandpass”. Default: “lowpass”.

  • nfft (int, optional): Number of points for FFT. Default: 2048.

  • fs (int, optional): Sampling frequency. Default: 48000.

  • requires_grad (bool, optional): Whether the filter parameters require gradient computation. Default: True.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str, optional): The device of the constructed tensors. Default: None.

Attributes:

  • param (nn.Parameter): The parameters of the Filter module.

  • map (function): Mapping function generated by get_map according to filter_type.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • freq_response (torch.Tensor): The frequency response of the filter.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

check_param_shape()

Check the shape of the filter parameters.

get_freq_response()

Compute the frequency response of the filter.

get_io()

Computes the number of input and output channels based on the size parameter.

get_map()

Get the mapping function map to parameter values that ensure stability. The type of mapping is based on filter_type.

get_poly_coeff(param)

Computes the polynomial coefficients for the specified filter type. It calls the flamo.functional.lowpass_filter(), flamo.functional.highpass_filter(), or flamo.functional.bandpass_filter() functions based on the filter type.

The shape of the tensor should be (batch_size, num_params, height, width). The parameters are interpreted differently based on the filter type:

  • For “lowpass” and “highpass” filters, param[:, 0, :, :] represents the cutoff frequency and param[:, 1, :, :] represents the gain.

  • For “bandpass” filters, param[:, 0, :, :] represents the lower cutoff frequency, param[:, 1, :, :] represents the upper cutoff frequency, and param[:, 2, :, :] represents the gain.

Arguments:

param (torch.Tensor): A tensor containing the filter parameters.

Returns:

  • H (torch.Tensor): The frequency response of the filter.

  • B (torch.Tensor): The Fourier transformed numerator polynomial coefficients.

  • A (torch.Tensor): The Fourier transformed denominator polynomial coefficients.

The method uses the filter type specified in filter_type to determine which filter to apply. It applies a anti time-aliasing envelope decay to the filter coefficients. Zero values in the denominator polynomial coefficients are replaced with a small constant to avoid division by zero.

get_size()

Get the leading dimensions of the parameters based on the filter type. These coincide with

  • 2 for lowpass and highpass filters (\(f_\textrm{c}\), gain)

  • 3 for bandpass filters (\(f_\textrm{c1}\), \(f_\textrm{c2}\), gain)

Returns:

  • tuple: leading dimensions of the parameters.

init_param()

Initialize the filter parameters.

initialize_class()

Initialize the Biquad class.

class flamo.processor.dsp.parallelBiquad(size: tuple = (1,), n_sections: int = 1, filter_type: str = 'lowpass', nfft: int = 2048, fs: int = 48000, requires_grad: bool = True, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Biquad

Parallel counterpart of the Biquad class. For information about attributes and methods see flamo.processor.dsp.Biquad.

Shape:

  • input: \((B, M, N, ...)\)

  • param: \((K, P, N, N)\)

  • freq_response: \((M, N, N)\)

  • output: \((B, M, N, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, and \(N\) is the number of input/output channels. The param attribute represent the biquad filter coefficents. The first dimension of the param tensor corresponds to the number of filters \(K\), the second dimension corresponds to the number of filter parameters \(P\) (3). Ellipsis \((...)\) represents additional dimensions (not tested).

check_param_shape()

Check the shape of the filter parameters.

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_freq_response()

Compute the frequency response of the filter.

get_io()

Computes the number of input and output channels based on the size parameter.

get_map()

Get the mapping function map to parameter values that ensure stability. The type of mapping is based on the filter type.

get_poly_coeff(param)

Computes the polynomial coefficients for the specified filter type. It calls the flamo.functional.lowpass_filter(), flamo.functional.highpass_filter(), or flamo.functional.bandpass_filter() functions based on the filter type.

Arguments:

param (torch.Tensor): A tensor containing the filter parameters.

The shape of the tensor should be (batch_size, num_params, height). The parameters are interpreted differently based on the filter type:

  • For “lowpass” and “highpass” filters, param[:, 0, :] represents the cutoff frequency and param[:, 1, :] represents the gain.

  • For “bandpass” filters, param[:, 0, :] represents the lower cutoff frequency, param[:, 1, :] represents the upper cutoff frequency, and param[:, 2, :] represents the gain.

Returns:

  • H (torch.Tensor): The frequency response of the filter.

  • B (torch.Tensor): The Fourier transformed numerator polynomial coefficients.

  • A (torch.Tensor): The Fourier transformed denominator polynomial coefficients.

The method uses the filter type specified in filter_type to determine which filter to apply. It applies an aliasing envelope decay to the filter coefficients. Zero values in the denominator polynomial coefficients are replaced with a small constant to avoid division by zero.

class flamo.processor.dsp.SVF(size: tuple = (1, 1), n_sections: int = 1, filter_type: str = None, nfft: int = 2048, fs: int = 48000, requires_grad: bool = True, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Filter

A class for IIR filters as a serially cascaded state variable filters (SVFs).

Can be used to design a variety of filters such as lowpass, highpass, bandpass, lowshelf, highshelf, peaking, and notch filters. The filter coefficients are parameterized by the cut-off frequency (\(f\)) and resonance (\(R\)) parameters. The mixing coefficients (\(m_{LP}\), \(m_{BP}\), \(m_{HP}\) for lowpass, bandpass, and highpass filters) determine the contribution of each filter type in the cascaded structure.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((P, K, N_{out}, N_{in})\)

  • freq_response: \((M, N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, \(N_{out}\) is the number of output channels, The param attribute represent the biquad filter coefficents. The first dimension of the param tensor corresponds to the number of SVF parameters (5), the second dimension corresponds to the number of filters \(K\). Ellipsis \((...)\) represents additional dimensions (not tested).

SVF parameters are used to express biquad filters as follows:

\[ \begin{align}\begin{aligned}H(z) = \frac{b_0 + b_1 z^{-1} + b_2 z^{-2}}{a_0 + a_1 z^{-1} + a_2 z^{-2}}\\\begin{split}b_0 = f^2 m_{LP} + f m_{BP} + m_{HP} \\ b_1 = 2 f^2 m_{LP} - 2 m_{HP} \\ b_2 = f^2 m_{LP} - f m_{BP} + m_{HP} \\ a_0 = f^2 + 2 R f + 1 \\ a_1 = 2 f^2 - 2 \\ a_2 = f^2 - 2 R f + 1 \\\end{split}\end{aligned}\end{align} \]

For serieally cascaded SVFs, the frequency response is

\[H(z) = \prod_{k=1}^{K} H_k(z)\]

where \(K\) is the number of cascaded filters n_sections.

Arguments / Attributes:

  • size (tuple, optional): The size of the raw filter parameters. Default: (1, 1).

  • n_sections (int, optional): The number of cascaded filters. Default: 1.

  • filter_type (str, optional): The type of filter to use. Options are {“lowpass”,”highpass”,”bandpass”,”lowshelf”,”highshelf”,”peaking”,”notch”,} Default: None.

  • nfft (int, optional): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • fs (int): The sampling frequency. Default: 48000.

  • map (function, optional): The mapping function to apply to the raw parameters. Default: lambda x: x.

  • requires_grad (bool, optional): Whether the filter parameters require gradients. Default: False.

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str, optional): The device of the constructed tensors. Default: None.

Attributes:

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • freq_response (torch.Tensor): The frequency response of the filter.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

For more details, refer to the paper Differentiable artificial reverberation by Lee, S. et al.

check_input_shape(x)

Checks if the input dimensions are compatible with the filter parameters.

Arguments:

x (torch.Tensor): The input signal.

check_param_shape()

Checks if the shape of the filter parameters is valid.

get_freq_response()

Compute the frequency response of the filter.

get_io()

Computes the number of input and output channels based on the size parameter.

get_poly_coeff(param)

Computes the polynomial coefficients for the SVF filter

map_param2svf(param)

Mapping function for the raw parameters to the SVF filter coefficients.

param2R(param)

Applies a softplus function to the parameter value and maps it to the range [0, 1], according to the formula:

\[R = \text{softplus}(x) / log(2).\]
param2freq(param)

Applies a sigmoid function to the parameter value and maps it to the range [0, fs/2], where \(f_s\) is the sampling frequency according to the formula:

\[f = \text{tan}\left(\pi \cdot \text{sigmoid}(x) \cdot 0.5\right).\]
param2mix(param, R=None)

Mapping function for the mixing coefficients relative to the filter type.

  • lowpass: \(m_{LP} = G, m_{BP} = 0, m_{HP} = 0\).

  • highpass: \(m_{LP} = 0, m_{BP} = 0, m_{HP} = G.\)

  • bandpass: \(m_{LP} = 0, m_{BP} = G, m_{HP} = 0.\)

  • lowshelf: \(m_{LP} = 1, m_{BP} = 2 \cdot R \cdot \sqrt{G}, m_{HP} = G.\)

  • highshelf: \(m_{LP} = G, m_{BP} = 2 \cdot R \cdot \sqrt{G}, m_{HP} = 1.\)

  • peaking | notch: \(m_{LP} = 1, m_{BP} = 2 \cdot R \cdot \sqrt{G}, m_{HP} = 1.\)

where \(G\) is the gain parameter mapped from the raw parameters as \(G = 10^{-\text{softplus}(x)}\).

Arguments:

  • param (torch.Tensor): The raw parameters.

  • R (torch.Tensor, optional): The resonance parameter. Default: None.

class flamo.processor.dsp.parallelSVF(size: tuple = (1,), n_sections: int = 1, filter_type: str = None, nfft: int = 2048, fs: int = 48000, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: SVF

Parallel counterpart of the SVF class. For information about attributes and methods see flamo.processor.dsp.SVF.

Shape:

  • input: \((B, M, N, ...)\)

  • param: \((P, K, N)\)

  • freq_response: \((M, N)\)

  • output: \((B, M, N, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, and \(N\) is the number of input/output channels. The param attribute represent the biquad filter coefficents. The first dimension of the param tensor corresponds to the number of SVF parameters (5), the second dimension corresponds to the number of filters \(K\). Ellipsis \((...)\) represents additional dimensions (not tested).

check_param_shape()

Checks if the shape of the filter parameters is valid.

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_freq_response()

Compute the frequency response of the filter.

get_io()

Computes the number of input and output channels based on the size parameter.

get_poly_coeff(param)

Computes the polynomial coefficients for the SVF filter

class flamo.processor.dsp.GEQ(size: tuple = (1, 1), octave_interval: int = 1, nfft: int = 2048, fs: int = 48000, map: callable = <function GEQ.<lambda>>, requires_grad: bool = True, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Filter

A class for Graphic Equilizer filters.

It supports 1 and 1/3 octave filter bands. The raw parameters are the linear gain values for each filter band.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((K, N_{out}, N_{in})\)

  • freq_response: \((M, N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, \(N_{out}\) is the number of output channels, The param attribute represent the command gains of each band and of the two shelving filters at DC and Nyquist. The first dimension of the param tensor corresponds to the number of command gains/filters \(K\). Ellipsis \((...)\) represents additional dimensions (not tested).

Arguments / Attributes:

  • size (tuple, optional): The size of the raw filter parameters. Default: (1, 1).

  • octave_interval (int, optional): The octave interval for the center frequencies. Default: 1.

  • nfft (int, optional): The number of FFT points required to compute the frequency response. Default: 2 ** 11.

  • fs (int, optional): The sampling frequency. Default: 48000.

  • map (function, optional): The mapping function to apply to the raw parameters. Default: lambda x: 20*torch.log10(x).

  • requires_grad (bool, optional): Whether the filter parameters require gradients. Default: False.

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.

  • device (str, optional): The device of the constructed tensors. Default: None.

Attributes:

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • center_freq (torch.Tensor): The center frequencies of the filter bands.

  • shelving_crossover (torch.Tensor): The shelving crossover frequencies.

  • n_gains (int): The number of command gains.

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • param (nn.Parameter): The parameters of the GEQ filter.

  • freq_response (torch.Tensor): The frequency response of the filter.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

References:

  • Schlecht, S., Habets, E. (2017). Accurate reverberation time control in feedback delay networks Proc. Int. Conf. Digital Audio Effects (DAFx) adapted to python by: Dal Santo G.

  • Välimäki V., Reiss J. All About Audio Equalization: Solutions and Frontiers, Applied Sciences, vol. 6, no. 5, pp. 129, May 2016

check_param_shape()

Checks if the shape of the filter parameters is valid.

get_freq_response()

Compute the frequency response of the filter.

get_io()

Computes the number of input and output channels based on the size parameter.

get_poly_coeff(param)

Computes the polynomial coefficients for the SOS section.

init_param()

It uses the torch.nn.init.normal_() function to set the values of param by drawing from the normal distribution \(\mathcal{N}(0, 1)\).

initialize_class()

Initializes the Filter module.

This method checks the shape of the gain parameters, computes the frequency response of the filter, and computes the frequency convolution function.

class flamo.processor.dsp.parallelGEQ(size: tuple = (1, ), octave_interval: int = 1, nfft: int = 2048, fs: int = 48000, map: callable = <function parallelGEQ.<lambda>>, requires_grad: bool = True, alias_decay_db: float = 0.0, device: str | None = None)

Bases: GEQ

Parallel counterpart of the GEQ class For information about attributes and methods see flamo.processor.dsp.GEQ.

Shape:

  • input: \((B, M, N, ...)\)

  • param: \((P, N)\)

  • freq_response: \((M, N)\)

  • output: \((B, M, N, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, and \(N\) is the number of input/output channels. The param attribute represent the command gains of each band + shelving filters. The first dimension of the param tensor corresponds to the number of command gains/filters \(K\). Ellipsis \((...)\) represents additional dimensions (not tested).

check_param_shape()

Checks if the shape of the filter parameters is valid.

get_freq_convolve()

Computes the frequency convolution function.

The frequency convolution is computed using the torch.einsum() function.

Arguments:

x (torch.Tensor): Input tensor.

Returns:

torch.Tensor: Output tensor after frequency convolution.

get_io()

Computes the number of input and output channels based on the size parameter.

get_poly_coeff(param)

Computes the polynomial coefficients for the SOS section.

class flamo.processor.dsp.Delay(size: tuple = (1, 1), max_len: int = 2000, isint: bool = False, unit: int = 100, nfft: int = 2048, fs: int = 48000, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: DSP

A class repsenting time Delay in frequency domain.

To improve update effectiveness, the unit of time can be adjusted via the unit attribute to use subdivisions or multiples of time. For integer Delays, the isint attribute can be set to True to round the delay to the nearest integer before computing the frequency response.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • param: \((M, N_{out}, N_{in})\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, and \(N_{out}\) is the number of output channels. Ellipsis \((...)\) represents additional dimensions.

For a delay of \(d\) seconds, the frequency response of the delay without anti-aliasing is computed as:

\[e^{-j \omega d}\; \text{for}\; \omega = 2\pi \frac{m}{\texttt{nfft}}\]

where \(\texttt{nfft}\) is the number of FFT points, and \(m\) is the frequency index \(m=0, 1, \dots, \lfloor\texttt{nfft}/2 +1\rfloor\) .

Arguments / Attributes:

  • size (tuple, optional): Size of the delay module. Default: (1, 1).

  • max_len (int, optional): Maximum length of the delay in samples. Default: 2000.

  • isint (bool, optional): Flag indicating whether the delay length should be rounded to the nearest integer. Default: False.

  • unit (int, optional): Unit value used for second-to-sample conversion. Default: 100.

  • nfft (int, optional): Number of FFT points. Default: 2 ** 11.

  • fs (int, optional): Sampling frequency. Default: 48000.

  • requires_grad (bool, optional): Flag indicating whether the module parameters require gradients. Default: False.

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Defaults to 0.

  • device (str, optional): The device of the constructed tensors. Default: None.

Attributes:

  • alias_envelope_dcy (torch.Tensor): The anti time-aliasing decaying envelope.

  • fft (function): The FFT function. Calls the torch.fft.rfft function.

  • ifft (function): The Inverse FFT function. Calls the torch.fft.irfft.

  • gamma (torch.Tensor): The gamma value used for time anti-aliasing envelope.

  • new_value (int): Flag indicating if new values have been assigned.

  • omega (torch.Tensor): The frequency values used for the FFT.

  • order (int): Maximum leght of the delay.

  • freq_response (torch.Tensor): The frequency response of the delay module.

  • freq_convolve (function): The frequency convolution function.

  • input_channels (int): The number of input channels.

  • output_channels (int): The number of output channels.

check_input_shape(x)

Checks if the input dimensions are compatible with the delay parameters.

Arguments:

x (torch.Tensor): The input signal.

check_param_shape()

Checks if the shape of the delay parameters is valid.

forward(x, ext_param=None)

Applies the Delay module to the input tensor x.

Arguments:

  • x (torch.Tensor): Input tensor of shape (B, M, N_in, …).

  • ext_param (torch.Tensor, optional): Parameter values received from external modules (hyper conditioning). Default: None.

Returns:

torch.Tensor: Output tensor of shape (B, M, N_out, …).

get_delays()

Computes the delay values from the raw parameters.

get_freq_convolve()

Computes the frequency convolution function.

get_freq_response()

Computes the frequency response of the delay module.

get_io()

Computes the number of input and output channels based on the size parameter.

init_param()

Initializes the Delay parameters.

initialize_class()

Initializes the Delay module.

This method checks the shape of the delay parameters, computes the frequency response, and initializes the frequency convolution function.

s2sample(delay)

Converts a delay value from seconds to samples.

Arguments:

delay (float): The delay value in seconds.

sample2s(delay: Tensor)

Converts a delay value from samples to seconds.

Arguments:

delay (torch.Tensor): The delay value in samples.

class flamo.processor.dsp.parallelDelay(size: tuple = (1,), max_len: int = 2000, unit: int = 100, isint: bool = False, nfft=2048, fs: int = 48000, requires_grad: bool = False, alias_decay_db: float = 0.0, device: str | None = None)

Bases: Delay

Parallel counterpart of the Delay class. For information about attributes and methods see Delay.

Shape:

  • input: \((B, M, N, ...)\)

  • param: \((M, N)\)

  • output: \((B, M, N, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, and \(N\) is the number of input channels. Ellipsis \((...)\) represents additional dimensions.

check_param_shape()

Checks if the shape of the delay parameters is valid.

get_freq_convolve()

Computes the frequency convolution function.

get_freq_response()

Computes the frequency response of the delay module.

get_io()

Computes the number of input and output channels based on the size parameter.