flamo.functional.get_magnitude(x: Tensor)

Gets the magnitude of a complex tensor.

Arguments:

x (torch.tensor): The input tensor.

Returns:

torch.tensor: The absolute value of x.

flamo.functional.get_eigenvalues(x: Tensor)

Gets the eigenvalues of a complex tensor. The last two dimensions of the input tensor must be identical.

Arguments:

x (torch.tensor): The input tensor.

Returns:

torch.tensor: The eigenvalues of x.

flamo.functional.skew_matrix(X)

Generate a skew symmetric matrix from a given matrix \(\mathbf{X}_{\textrm{Tr}}\) as follows

\[\mathbf{X} = \mathbf{X}_{\textrm{Tr}} - \mathbf{X}_{\textrm{Tr}}^\top\]

where \(\mathbf{X_{\textrm{Tr}}}\) is the upper triangular part of \(\mathbf{X}\), and \(\cdot^\top\) denotes the transpose operation.

Arguments:

X (torch.Tensor): The input matrix.

flamo.functional.get_frequency_samples(num: int, device: str | device = None)

Get frequency samples (in radians) sampled at linearly spaced points along the unit circle.

Arguments

  • num (int): number of frequency samples

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

Returns

  • frequency samples in radians between [0, pi]

flamo.functional.biquad2tf(b: Tensor, a: Tensor, nfft: int)

Converts a biquad filter representation to a transfer function. Shape of b and a is (3, n_sections)

Arguments:

  • b (torch.Tensor): Coefficients of the numerator polynomial of the biquad filter.

  • a (torch.Tensor): Coefficients of the denominator polynomial of the biquad filter.

  • nfft (int): The number of FFT points to compute teh transfer function.

Returns:

  • torch.Tensor: Transfer function of the biquad filter evaluated at x.

Generate a tensor containing a signal based on the specified signal type.

Supported signal types are:

  • impulse: A single impulse at the first sample, followed by n_samples-1 zeros.

  • sine: A sine wave of frequency rate Hz, if given. Otherwise, a sine wave of frequency 1 Hz.

  • sweep: A linear sweep from 20 Hz to 20 kHz.

  • wgn: White Gaussian noise.

  • exp: An exponential decay signal.

  • reference: A reference signal provided as argument reference.

Arguments:

  • batch_size (int): The number of batches to generate.

  • n_samples (int): THe signal length in samples.

  • n_channel (int): The number of channels in each signal.

  • signal_type (str, optional): The type of signal to generate. Defaults to ‘impulse’.

  • fs (int, optional): The sampling frequency of the signals. Defaults to 48000.

  • reference (torch.Tensor, optional): A reference signal to use. Defaults to None.

  • device (torch.device, optional): The device of constructed tensors. Defaults to None.

Returns:

  • torch.Tensor: A tensor of shape (batch_size, n_samples, n) containing the generated signals.

flamo.functional.hertz2rad(hertz: Tensor, fs: int)

Convert frequency from Hz to rad.

\[\omega = \frac{2\pi f}{f_s}\]

where \(f\) is the frequency in Hz and \(f_s\) is the sampling frequency in Hz.

Arguments:

  • hertz (torch.Tensor): The frequency in Hz.

  • fs (int): The sampling frequency in Hz.

flamo.functional.rad2hertz(rad: Tensor, fs: int)

Convert frequency from rad to Hz

\[f = \frac{\omega f_s}{2\pi}\]

where \(\omega\) is the frequency in rad and \(f_s\) is the sampling frequency in Hz.

Arguments:

  • rad (torch.Tensor): The frequency in rad.

  • fs (int): The sampling frequency in Hz.

flamo.functional.db2mag(dB: Tensor | float)

Convert a value from decibels (dB) to magnitude.

\[\text{magnitude} = 10^{dB/20}\]

where \(dB\) is the input value in decibels.

Arguments:

dB (torch.tensor | float): The value in decibels.

Returns:

  • float: The corresponding magnitude value.

flamo.functional.mag2db(mag: Tensor)

Convert a value from magnitude to decibels (dB).

\[\text{dB} = 20\log_{10}(\text{magnitude})\]

where \(\text{magnitude}\) is the input value in magnitude.

Arguments:

  • mag (torch.tensor): The value in magnitude.

Returns:

  • float: The corresponding value in decibels.

flamo.functional.lowpass_filter(fc: float = 500.0, gain: float = 0.0, fs: int = 48000, device: str | device = None) → tuple

Lowpass filter coefficients. It uses the RBJ cookbook formulas to map the cutoff frequency and gain to the \(\mathbf{b}\) and \(\mathbf{a}\) biquad 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}}\]

for

\[b_0 = \frac{1 - \cos(\omega_c)}{2},\;\; b_1 = 1 - \cos(\omega_c),\;\; b_2 = \frac{1 - \cos(\omega_c)}{2}\]
\[a_0 = 1 + \alpha,\;\; a_1 = -2 \cos(\omega_c),\;\; a_2 = 1 - \alpha\]

where \(\omega_c = 2\pi f_c / f_s\), \(\alpha = \sin(\omega_c)/2 \cdot \sqrt{2}\) and \(\cos(\omega_c)\) is the cosine of the cutoff frequency. The gain is applied to the filter coefficients as \(b = 10^{g_{\textrm{dB}}/20} b\).

Arguments:

  • fc (float, optional): The cutoff frequency of the filter in Hz. Default: 500 Hz.

  • gain (float, optional): The gain of the filter in dB. Default: 0 dB.

  • fs (int, optional): The sampling frequency of the signal in Hz. Default: 48000 Hz.

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

Returns:

  • b (torch.tensor): The numerator coefficients of the filter transfer function.

  • a (torch.tensor): The denominator coefficients of the filter transfer function.

flamo.functional.highpass_filter(fc: float = 10000.0, gain: float = 0.0, fs: int = 48000, device: str | device = None) → tuple

Highpass filter coefficients. It uses the RBJ cookbook formulas to map the cutoff frequency and gain to the \(\mathbf{b}\) and \(\mathbf{a}\) biquad coefficients.

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

for

\[b_0 = \frac{1 + \cos(\omega_c)}{2},\;\; b_1 = - 1 - \cos(\omega_c),\;\; b_2 = \frac{1 + \cos(\omega_c)}{2}\]
\[a_0 = 1 + \alpha,\;\; a_1 = -2 \cos(\omega_c),\;\; a_2 = 1 - \alpha\]

where \(\omega_c = 2\pi f_c / f_s\), \(\alpha = \sin(\omega_c)/2 \cdot \sqrt{2}\) and \(\cos(\omega_c)\) is the cosine of the cutoff frequency. The gain is applied to the filter coefficients as \(b = 10^{g_{\textrm{dB}}/20} b\).

Arguments:

  • fc (float, optional): The cutoff frequency of the filter in Hz. Default: 10000 Hz.

  • gain (float, optional): The gain of the filter in dB. Default: 0 dB.

  • fs (int, optional): The sampling frequency of the signal in Hz. Default: 48000 Hz.

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

Returns:

  • b (torch.tensor): The numerator coefficients of the filter transfer function.

  • a (torch.tensor): The denominator coefficients of the filter transfer function.

flamo.functional.bandpass_filter(fc1: Tensor, fc2: Tensor, gain: float = 0.0, fs: int = 48000, device: str | device = None) → tuple

Bandpass filter coefficients. It uses the RBJ cookbook formulas to map the cutoff frequencies and gain to the \(\mathbf{b}\) and \(\mathbf{a}\) biquad coefficients.

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

for

\[b_0 = \alpha,\;\; b_1 = 0,\;\; b_2 = - \alpha\]
\[a_0 = 1 + \alpha,\;\; a_1 = -2 \cos(\omega_c),\;\; a_2 = 1 - \alpha\]

where

\[\omega_c = \frac{2\pi f_{c1} + 2\pi f_{c2}}{2 f_s}`,\]
\[\text{ BW } = \log_2\left(\frac{f_{c2}}{f_{c1}}\right),\]
\[\alpha = \sin(\omega_c) \sinh\left(\frac{\log(2)}{2} \text{ BW } \frac{\omega_c}{\sin(\omega_c)}\right)\]

The gain is applied to the filter coefficients as \(b = 10^{g_{\textrm{dB}}/20} b\).

Arguments:

  • fc1 (float): The left cutoff frequency of the filter in Hz.

  • fc2 (float): The right cutoff frequency of the filter in Hz.

  • gain (float, optional): The gain of the filter in dB. Default: 0 dB.

  • fs (int, optional): The sampling frequency of the signal in Hz. Default: 48000 Hz.

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

Returns:

  • b (torch.Tensor): The numerator coefficients of the filter transfer function.

  • a (torch.Tensor): The denominator coefficients of the filter transfer function.

flamo.functional.shelving_filter(fc: Tensor, gain: Tensor, type: str = 'low', fs: int = 48000, device: device | str = None)

Shelving filter coefficients. Maps the cutoff frequencies and gain to the \(\mathbf{b}\) and \(\mathbf{a}\) biquad coefficients.

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

for low shelving filter:

\[ \begin{align}\begin{aligned}b_0 = \sqrt{g} ( \sqrt{g} \tau^2 + \sqrt{2} \tau g^{1/4} + 1 ),\;\; b_1 = \sqrt{g} (2 \sqrt{g} \tau^2 - 2 ),\;\; b_2 = \sqrt{g} ( \sqrt{g} \tau^2 - \sqrt{2} \tau g^{1/4} + 1 )\\a_0 = \sqrt{g} + \sqrt{2} \tau g^{1/4} + \tau^2,\;\; a_1 = 2 \tau^{2} - 2 \sqrt{g} ,\;\; a_2 = \sqrt{g} - \sqrt{2} \tau g^{1/4} + \tau^2\end{aligned}\end{align} \]

for high shelving filter:

\[ \begin{align}\begin{aligned}b_0 = g ( \sqrt{g} + \sqrt{2} \tau g^{1/4} + \tau^2 ),\;\; a_1 = g ( 2 \tau^{2} - 2 \sqrt{g} ),\;\; a_2 = g (\sqrt{g} - \sqrt{2} \tau g^{1/4} + \tau^2)\\a_0 = \sqrt{g} ( \sqrt{g} \tau^2 + \sqrt{2} \tau g^{1/4} + 1 ),\;\; a_1 = \sqrt{g} (2 \sqrt{g} \tau^2 - 2 ),\;\; a_2 = \sqrt{g} ( \sqrt{g} \tau^2 - \sqrt{2} \tau g^{1/4} + 1 )\end{aligned}\end{align} \]

where \(\tau = \tan(2 \pi f_c / (2 f_s))\), \(f_c\) is the cutoff frequency, \(f_s\) is the sampling frequency, and \(g\) is the linear gain.

Arguments:

  • fc (torch.Tensor): The cutoff frequency of the filter in Hz.

  • gain (torch.Tensor): The linear gain of the filter.

  • type (str, optional): The type of shelving filter. Can be ‘low’ or ‘high’. Default: ‘low’.

  • fs (int, optional): The sampling frequency of the signal in Hz.

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

Returns:

  • b (torch.Tensor): The numerator coefficients of the filter transfer function.

  • a (torch.Tensor): The denominator coefficients of the filter transfer function.

flamo.functional.peak_filter(fc: Tensor, gain: Tensor, Q: Tensor, fs: int = 48000, device: str | device = None) → tuple

Peak filter coefficients. Outputs the cutoff frequencies and gain to the \(\mathbf{b}\) and \(\mathbf{a}\) biquad coefficients.

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

for peak filter:

\[ \begin{align}\begin{aligned}b_0 = \sqrt{g} + g \tau,\;\; b_1 = -2 \sqrt{g} \cos(\omega_c),\;\; b_2 = \sqrt{g} - g \tau\\a_0 = \sqrt{g} + \tau,\;\; a_1 = -2 \sqrt{g} \cos(\omega_c),\;\; a_2 = \sqrt{g} - \tau\end{aligned}\end{align} \]

where \(\tau = \tan(\text{BW}/2)\), \(BW = \omega_c / Q\), \(\omega_c = 2\pi f_c / f_s\), \(g`is the linear gain, and :math:`Q\) is the quality factor.

Arguments:

  • fc (torch.Tensor): The cutoff frequency of the filter in Hz.

  • gain (torch.Tensor): The linear gain of the filter.

  • Q (torch.Tensor): The quality factor of the filter.

  • fs (int, optional): The sampling frequency of the signal in Hz. Default: 48000.

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

Returns:

  • b (torch.Tensor): The numerator coefficients of the filter transfer function.

  • a (torch.Tensor): The denominator coefficients of the filter transfer function

flamo.functional.sosfreqz(sos: Tensor, nfft: int = 512)

Compute the complex frequency response via FFT of cascade of second order filter sections (SOS).

Arguments:

  • sos (torch.Tensor): Second order filter sections with shape (n_sections, 6)

  • nfft (int): FFT size. Default: 512

Returns:

  • H (torch.Tensor): Overall complex frequency response.

flamo.functional.svf(fc: Tensor, R: Tensor, m: Tensor = tensor([1., 1., 1.]), G: Tensor = None, filter_type: str = None, fs: int = 48000, device: str | device = None)

Implements a State Variable Filter (SVF) with various filter types.

Arguments:

  • fc (torch.Tensor): The cutoff frequency of the filter.

  • R (torch.Tensor): The resonance parameter of the filter.

  • m (torch.Tensor, optional): The mixing coefficients of the filter. Default: torch.ones((3,)).

  • G (torch.Tensor, optional): The gain coefficients of the filter. Default: None.

  • filter_type (str, optional): The type of filter to be applied. Can be one of “lowpass”, “highpass”, “bandpass”, “lowshelf”, “highshelf”, “peaking”, “notch”, or None. Default: None.

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

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

Returns:

Tuple[torch.Tensor, torch.Tensor]: The numerator and denominator coefficients of the filter transfer function.

flamo.functional.probe_sos(sos: Tensor, control_freqs: list | Tensor, nfft: int, fs: int, device: str | device = None)

Probe the frequency / magnitude response of a cascaded SOS filter at the points specified by the control frequencies.

Arguments:

  • sos (torch.Tensor): Cascaded second-order sections (SOS) filter coefficients.

  • control_freqs (list or torch.Tensor): Frequencies at which to probe the filter response.

  • nfft (int): Length of the FFT used for frequency analysis.

  • fs (float): Sampling frequency in Hz.

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

Returns:
tuple: A tuple containing the following:

  • G (torch.Tensor): Magnitude response of the filter at the control frequencies.

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

  • W (torch.Tensor): Phase response of the filter.

flamo.functional.find_onset(rir: Tensor)

Find onset in input RIR by extracting a local energy envelope of the RIR then finding its maximum point

Arguments:

  • rir (torch.Tensor): Room impulse response.

flamo.functional.WGN_reverb(matrix_size: tuple = (1, 1), t60: float = 1.0, samplerate: int = 48000, device=None) → Tensor

Generates White-Gaussian-Noise-reverb impulse responses.

Arguments:

  • matrix_size (tuple, optional): (output_channels, input_channels). Defaults to (1,1).

  • t60 (float, optional): Reverberation time. Defaults to 1.0.

  • samplerate (int, optional): Sampling frequency. Defaults to 48000.

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

Returns:

torch.Tensor: Matrix of WGN-reverb impulse responses.