grafx.processors.filter

class FIRFilter(fir_len=1023, processor_channel='mono', **backend_kwargs)

Bases: Module

A time-domain filter with learnable finite impulse response (FIR) coefficients. It is implemented with the FIRConvolution module.

Parameters:

fir_len (int, optional) – The length of the FIR filter (default: 1023).
processor_channel (str, optional) – The channel type of the processor, which can be either "mono", "stereo", or "midside" (default: "mono").
**backend_kwargs – Additional keyword arguments for the FIRConvolution.

forward(input_signals, fir)

Performs the convolution operation.

Parameters:

input_signals (FloatTensor, \(B \times C_\mathrm{in} \times L_\mathrm{in}\)) – A batch of input audio signals.
fir (FloatTensor, \(B \times C_\mathrm{filter} \times L_\mathrm{filter}\)) – A batch of FIR filters.

Returns:

A batch of convolved signals of shape \(B \times C_\mathrm{out} \times L_\mathrm{in}\) where \(C_\mathrm{out} = \max (C_\mathrm{in}, C_\mathrm{filter})\).

Return type:

FloatTensor

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

class BiquadFilter(num_filters=1, normalized=False, **backend_kwargs)

Bases: Module

A serial stack of second-order filters (biquads) with the given coefficients.

To ensure the stability of each biquad, we restrict the normalized feedback coefficients with the following activations [NSW21].

\[\begin{split} \bar{a}_{i, 1} &= 2 \tanh(\tilde{a}_{i, 1}), \\ \bar{a}_{i, 2} &= \frac{(2 - \left|\bar{a}_{i, 1}\right|) \tanh(\tilde{a}_{i, 2}) + \left|\bar{a}_{i, 1}\right|}{2}. \end{split}\]

Here, \(\tilde{a}_{i, 1}\) and \(\tilde{a}_{i, 2}\) are the pre-activation values. The unnormlized coefficients can be optionally recovered by multiplying the normalized ones with \(a_{i, 0}\). The learnable parameters are \(p = \{\mathbf{B}, \tilde{\mathbf{a}}_1, \tilde{\mathbf{a}}_2, \mathbf{a}_0 \}\), where \(\mathbf{B} = [\mathbf{b}_0, \mathbf{b}_1, \mathbf{b}_2] \in \mathbb{R}^{K\times 3}\) is the stacked biquad coefficients for the feedforward path and the latter three are the pre-activation values for the feedback path. The last one \(\mathbf{a}_0\) is optional and only used when normalized == False.

Parameters:

num_filters (int, optional) – Number of biquads to use (default: 1).
normalized (bool, optional) – If set to True, the filter coefficients are assumed to be normalized by \(a_{i, 0}\), making the number of learnable parameters \(5\) per biquad instead of \(6\) (default: False).
backend (str, optional) – The backend to use for the filtering, which can either be the frequency-sampling method "fsm" or exact time-domain filter "lfilter" (default: "fsm").
fsm_fir_len (int, optional) – The length of FIR approximation when backend == "fsm" (default: 8192).

forward(input_signals, Bs, A1_pre, A2_pre, A0=None)

Processes input audio with the processor and given parameters.

Parameters:

input_signals (FloatTensor, \(B \times C \times L\)) – A batch of input audio signals.
Bs (FloatTensor, \(B \times K \times 3\)) – A batch of biquad coefficients, \(b_{i, 0}, b_{i, 1}, b_{i, 2}\), stacked in the last dimension.
A1_pre (FloatTensor, \(B \times K\:\!\)) – A batch of pre-activation coefficients \(\tilde{a}_{i, 1}\).
A2_pre (FloatTensor, \(B \times K\:\!\)) – A batch of pre-activation coefficients \(\tilde{a}_{i, 2}\).
A0 (FloatTensor, \(B \times K\), optional) – A batch of \(a_{i, 0}\) coefficients, only used when normalized == False (default: None).

Returns:

A batch of output signals of shape \(B \times C \times L\).

Return type:

FloatTensor

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

class PoleZeroFilter(num_filters=1, **backend_kwargs)

Bases: Module

A serial stack of biquads with pole/zero parameters.

\[ H(z) = g \prod_{k=1}^K \frac{(z-q_{k})(z-q_{k}^*)}{(z-p_{k})(z-p_{k}^*)} \]

The poles are restricted to the unit circle and reparameterized as follows,

\[ p_k = \tilde{p}_k \cdot \frac{\tanh( | \tilde{p}_k | )}{ | \tilde{p}_k | + \epsilon}. \]

\(p = \{ g, \tilde{\mathbf{p}}, \mathbf{z} \}\) are the learnable parameters, where both complex poles and zeros are repesented as a real-valued tensors with last dimension of size 2.

Parameters:

num_filters (int, optional) – Number of biquads to use (default: 1).
**backend_kwargs – Additional keyword arguments for the IIRFilter.

forward(input_signals, log_gain, poles, zeros)

Processes input audio with the processor and given parameters.

Parameters:

input_signals (FloatTensor, \(B \times C \times L\)) – A batch of input audio signals.
log_gain (FloatTensor, \(B \times 1\)) – A batch of log-gains.
poles (FloatTensor, \(B \times K \times 2\)) – A batch of complex poles.
zeros (FloatTensor, \(B \times K \times 2\)) – A batch of complex zeros.

Returns:

A batch of output signals of shape \(B \times C \times L\).

Return type:

FloatTensor

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

class StateVariableFilter(num_filters=1, **backend_kwargs)

Bases: Module

A series of biquads with the state variable filter (SVF) parameters [KPE20, Zav20].

The biquad coefficients reparameterized and computed from the SVF parameters \(R_i, G_i, c^{\mathrm{HP}}_i, c^{\mathrm{BP}}_i, c^{\mathrm{LP}}_i\) as follows,

\[\begin{split} b_{i, 0} &= G_i^2 c^{\mathrm{LP}}_i+G_i c^{\mathrm{BP}}_i+c^{\mathrm{HP}}_i, \\ b_{i, 1} &= 2G_i^2 c^{\mathrm{LP}}_i - 2c^{\mathrm{HP}}_i, \\ b_{i, 2} &= G_i^2 c^{\mathrm{LP}}_i-G_i c^{\mathrm{BP}}_i+c^{\mathrm{HP}}_i, \\ a_{i, 0} &= G_i^2 + 2R_iG_i + 1, \\ a_{i, 1} &= 2G_i^2-2, \\ a_{i, 2} &= G_i^2 - 2R_iG_i + 1. \end{split}\]

Note that we are not using the exact time-domain implementation of the SVF, but rather its parameterization that allows better optimization than the direct prediction of biquad coefficients (empirically observed in [KPE20, LCL22, NSW21]). To ensure the stability of each biquad, we ensure that \(G_i\) and \(R_i\) are positive.

Parameters:

num_filters (int, optional) – Number of SVFs to use (default: 1).
**backend_kwargs – Additional keyword arguments for the IIRFilter.

forward(input_signals, twoR, G, c_hp, c_bp, c_lp)

Processes input audio with the processor and given parameters.

Parameters:

input_signals (FloatTensor, \(B \times C \times L\)) – A batch of input audio signals.
log_gains (FloatTensor, \(B \times K \:\!\)) – A batch of log-gain vectors of the GEQ.

Returns:

A batch of output signals of shape \(B \times C \times L\).

Return type:

FloatTensor

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

static get_biquad_coefficients(twoR, G, c_hp, c_bp, c_lp)

class BaseParametricFilter(**backend_kwargs)

Bases: Module

forward(input_signals, w0, q_inv)

Processes input audio with the processor and given parameters.

Parameters:

input_signals (FloatTensor, \(B \times C \times L\)) – A batch of input audio signals.
w0 (FloatTensor, \(B \times 1\)) – A batch of cutoff frequencies.
q_inv (FloatTensor, \(B \times 1\)) – A batch of the inverse of quality factors (or resonance).

Returns:

A batch of output signals of shape \(B \times C \times L\).

Return type:

FloatTensor

static get_biquad_coefficients(cos_w0, alpha)

static filter_parameter_activations(w0, q_inv)

static compute_common_filter_parameters(w0, q_inv)

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

class LowPassFilter(**backend_kwargs)

Bases: BaseParametricFilter

Compute a simple second-order low-pass filter.

\[\begin{split} \mathbf{b} &= \left[ \frac{1 - \cos(\omega_0)}{2}, 1 - \cos(\omega_0), \frac{1 - \cos(\omega_0)}{2} \right], \\ \mathbf{a} &= \left[ 1 + \alpha, -2 \cos(\omega_0), 1 - \alpha \right]. \end{split}\]

These coefficients are calculated with the following pre-activations: \(\omega_0 = \pi \cdot \sigma(\tilde{w}_0)\) and \(\alpha = \sin(\omega_0) / 2q\) where the inverse of the quality factor is simply parameterized as \(1 / q = \exp(\tilde{q})\). This processor has two learnable parameters: \(p = \{\tilde{w}_0, \tilde{q}\}\).

Parameters:: **backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha)

class HighPassFilter(**backend_kwargs)

Bases: BaseParametricFilter

Compute a simple second-order high-pass filter.

The feedforward coefficients are given as

\[ \mathbf{b} = \left[ \frac{1 + \cos(\omega_0)}{2}, 1 + \cos(\omega_0), \frac{1 + \cos(\omega_0)}{2} \right], \]

and the remainings are the same as the LowPassFilter.

Parameters:: **backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha): Get biquad coefficients for high-pass filter.

class BandPassFilter(**backend_kwargs)

Bases: BaseParametricFilter

Compute a simple second-order band-pass filter.

The feedforward coefficients are given as

\[ \mathbf{b} = \left[\alpha, 0, -\alpha \right], \]

and the remainings are the same as the LowPassFilter.

Parameters:: **backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha)

class BandRejectFilter(**backend_kwargs)

Bases: BaseParametricFilter

Compute a simple second-order band-reject filter.

The feedforward coefficients are given as

\[ \mathbf{b} = \left[ 1, -2 \cos \omega_0, 1 \right], \]

and the remainings are the same as the LowPassFilter.

Parameters:: **backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha)

class AllPassFilter(**backend_kwargs)

Bases: BaseParametricFilter

Compute a simple second-order all-pass filter.

The feedforward coefficients are given as

\[ \mathbf{b} = \left[a_2, a_1, a_0 \right], \]

and the remainings are the same as the LowPassFilter.

Parameters:: **backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha)

class BaseParametricEqualizerFilter(num_filters=1, **backend_kwargs)

Bases: Module

forward(input_signals, w0, q_inv, log_gain)

Processes input audio with the processor and given parameters.

Parameters:

input_signals (FloatTensor, \(B \times C \times L\)) – A batch of input audio signals.
w0 (FloatTensor, \(B \times 1\)) – A batch of cutoff frequencies.
q_inv (FloatTensor, \(B \times 1\)) – A batch of the inverse of quality factors (or resonance).

Returns:

A batch of output signals of shape \(B \times C \times L\).

Return type:

FloatTensor

static get_biquad_coefficients(cos_w0, alpha, A)

static filter_parameter_activations(w0, q_inv, log_gain)

static compute_common_filter_parameters(w0, q_inv)

parameter_size()

Returns:: A dictionary that contains each parameter tensor’s shape.
Return type:: Dict[str, Tuple[int, ...]]

class PeakingFilter(num_filters=1, **backend_kwargs)

Bases: BaseParametricEqualizerFilter

A second-order peaking filter.

The feedforward coefficients are given as

\[\begin{split} \mathbf{b} &= \left[1 + \alpha A, -2 \cos \omega_0, 1 - \alpha A \right], \\ \mathbf{a} &= \left[1 + \frac{\alpha}{A}, -2 \cos \omega_0, 1 - \frac{\alpha}{A} \right], \end{split}\]

where \(A = \exp(\tilde{A})\). We follow the same activations as the LowPassFilter, and the learnable parameters are \(p = \{\tilde{w}_0, \tilde{q}, \tilde{A}\}\).

Parameters:

num_filters (int, optional) – Number of filters to use (default: 1).
**backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha, A)

class LowShelf(num_filters=1, **backend_kwargs)

Bases: BaseParametricEqualizerFilter

A second-order low-shelf filter.

The biquad coefficients are given as

\[\begin{split} b_0 &= A((A + 1) - (A - 1) \cos \omega_0 + 2 \smash{\sqrt{A}} \alpha), \\ b_1 &= 2A((A - 1) - (A + 1) \cos \omega_0), \\ b_2 &= A((A + 1) - (A - 1) \cos \omega_0 - 2 \smash{\sqrt{A}} \alpha), \\ a_0 &= (A + 1) + (A - 1) \cos \omega_0 + 2 \smash{\sqrt{A}} \alpha, \\ a_1 &= -2((A - 1) - (A + 1) \cos \omega_0), \\ a_2 &= (A + 1) + (A - 1) \cos \omega_0 - 2 \smash{\sqrt{A}} \alpha, \end{split}\]

The remainings are the same as the PeakingFilter.

Parameters:

num_filters (int, optional) – Number of filters to use (default: 1).
**backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha, A)

class HighShelf(num_filters=1, **backend_kwargs)

Bases: BaseParametricEqualizerFilter

A second-order high-shelf filter.

The biquad coefficients are given as

\[\begin{split} b_0 &= A((A + 1) + (A - 1) \cos \omega_0 + 2 \smash{\sqrt{A}} \alpha), \\ b_1 &= -2A((A - 1) + (A + 1) \cos \omega_0), \\ b_2 &= A((A + 1) + (A - 1) \cos \omega_0 - 2 \smash{\sqrt{A}} \alpha), \\ a_0 &= (A + 1) - (A - 1) \cos \omega_0 + 2 \smash{\sqrt{A}} \alpha, \\ a_1 &= 2((A - 1) + (A + 1) \cos \omega_0), \\ a_2 &= (A + 1) - (A - 1) \cos \omega_0 - 2 \smash{\sqrt{A}} \alpha, \end{split}\]

The remainings are the same as the PeakingFilter.

Parameters:

num_filters (int, optional) – Number of filters to use (default: 1).
**backend_kwargs – Additional keyword arguments for the IIRFilter.

static get_biquad_coefficients(cos_w0, alpha, A)