Biquad Stages¶

Biquad Stages can be used for basic audio filters.

Biquad¶

class audio_dsp.stages.Biquad(**kwargs)

A second order biquadratic filter, which can be used to make many common second order filters. The filter is initialised in a bypass state, and the make_* methods can be used to calculate the coefficients.

This Stage implements a direct form 1 biquad filter: a0*y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]

For efficiency the biquad coefficients are normalised by a0 and the output a coefficients multiplied by -1.

Attributes:

dsp_blockaudio_dsp.dsp.biquad.biquad: The DSP block class; see Single Biquad for implementation details.

make_allpass(f: float, q: float) → Biquad

Make this biquad an all pass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_bandpass(f: float, bw: float) → Biquad

Make this biquad a second order bandpass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bandstop(f: float, bw: float) → Biquad

Make this biquad a second order bandstop filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bypass() → Biquad: Make this biquad a bypass by setting the b0 coefficient to 1.

make_constant_q( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a peaking filter with constant Q.

Constant Q means that the bandwidth of the filter remains constant as the gain varies. It is commonly used for graphic equalisers.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_gain(gain_db: float) → Biquad

Make this biquad a gain stage.

Parameters:

gain_dbfloat: Gain of the filter in decibels.

make_highpass(f: float, q: float) → Biquad

Make this biquad a second order high pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_highshelf( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a second order high shelf filter.

The Q factor is defined in a similar way to standard high pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_linkwitz( f0: float, q0: float, fp: float, qp: float, ) → Biquad

Make this biquad a Linkwitz Transform biquad filter.

The Linkwitz Transform changes the low frequency cutoff of a filter, and is commonly used to change the low frequency roll off slope of a loudspeaker. When applied to a loudspeaker, it will change the cutoff frequency from f0 to fp, and the Q factor from q0 to qp.

Parameters:

f0float: The original cutoff frequency of the filter in Hz.
q0float: The original quality factor of the filter at f0.
fpfloat: The target cutoff frequency for the filter in Hz.
qpfloat: The target quality factor for the filter.

make_lowpass(f: float, q: float) → Biquad

Make this biquad a second order low pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_lowshelf( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a second order low shelf filter.

The Q factor is defined in a similar way to standard low pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_notch(f: float, q: float) → Biquad

Make this biquad a notch filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_peaking( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a peaking filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

set_parameters(parameters: BiquadParameters)

Set biquad filter parameters.

Args:: parameters: New biquad parameters to apply

pydantic model audio_dsp.models.biquad.BiquadParameters

Parameters for a biquad filter.

Attributes:

filter_typeaudio_dsp.models.fields.BIQUAD_TYPES: The parameters of the type of biquad filter to use (e.g., biquad_lowpass, biquad_highpass, etc.)

field filter_type: biquad_allpass | biquad_bandpass | biquad_bandstop | biquad_bypass | biquad_constant_q | biquad_gain | biquad_highpass | biquad_highshelf | biquad_linkwitz | biquad_lowpass | biquad_lowshelf | biquad_mute | biquad_notch | biquad_peaking = biquad_bypass(type='bypass'): Type of biquad filter to implement and it’s parameters.

Biquad Control¶

The following runtime command ids are available for the Biquad Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_BIQUAD_LEFT_SHIFT	`sizeof(int)`
The number of bits to shift the output left by, in order to compensate for any right shift applied to the biquad b coefficients.

CMD_BIQUAD_FILTER_COEFFS	`sizeof(int32_t)*[5]`
The normalised biquad filter coefficients, in the order [b0, b1, b2, -a1, -a2]/a0. The coefficients should be in Q1.30 format. If the maximum b coefficient magnitude is greater than 2.0, the b coefficients should be right shifted to fit in Q1.30 format, and the shift value passed as left_shift to correct the gain after filtering. Biquad coefficients can be generated using the helper functions in `control/biquad.h`. See Biquad helpers.

CMD_BIQUAD_RESERVED	`sizeof(int32_t)*[3]`
Reserved memory to ensure the VPU receives 8 DWORD_ALIGNED coefficients. This command is read only. When sending a write control command, it will be ignored.

BiquadSlew¶

class audio_dsp.stages.BiquadSlew(**kwargs)

A second order biquadratic filter with slew, which can be used to make many common second order filters. The filter is initialised in a bypass state, and the make_* methods can be used to calculate the coefficients. This variant will slew between filter coefficients when they are changed.

This Stage implements a direct form 1 biquad filter: a0*y[n] = b0*x[n] + b1*x[n-1] + b2*x[n-2] - a1*y[n-1] - a2*y[n-2]

For efficiency the biquad coefficients are normalised by a0 and the output a coefficients multiplied by -1.

Attributes:

dsp_blockaudio_dsp.dsp.biquad.biquad_slew: The DSP block class; see Single Slewing Biquad for implementation details.

make_allpass(f: float, q: float) → Biquad

Make this biquad an all pass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_bandpass(f: float, bw: float) → Biquad

Make this biquad a second order bandpass filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bandstop(f: float, bw: float) → Biquad

Make this biquad a second order bandstop filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
bwfloat: Bandwidth of the filter in octaves.

make_bypass() → Biquad: Make this biquad a bypass by setting the b0 coefficient to 1.

make_constant_q( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a peaking filter with constant Q.

Constant Q means that the bandwidth of the filter remains constant as the gain varies. It is commonly used for graphic equalisers.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_gain(gain_db: float) → Biquad

Make this biquad a gain stage.

Parameters:

gain_dbfloat: Gain of the filter in decibels.

make_highpass(f: float, q: float) → Biquad

Make this biquad a second order high pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_highshelf( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a second order high shelf filter.

The Q factor is defined in a similar way to standard high pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_linkwitz( f0: float, q0: float, fp: float, qp: float, ) → Biquad

Make this biquad a Linkwitz Transform biquad filter.

Parameters:

f0float: The original cutoff frequency of the filter in Hz.
q0float: The original quality factor of the filter at f0.
fpfloat: The target cutoff frequency for the filter in Hz.
qpfloat: The target quality factor for the filter.

make_lowpass(f: float, q: float) → Biquad

Make this biquad a second order low pass filter.

Parameters:

ffloat: Cutoff frequency of the filter in Hz.
qfloat: Q factor of the filter roll-off. 0.707 is equivalent to a Butterworth response.

make_lowshelf( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a second order low shelf filter.

The Q factor is defined in a similar way to standard low pass, i.e. > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2.

Parameters:

ffloat: Cutoff frequency of the shelf in Hz, where the gain is boost_db/2
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

make_notch(f: float, q: float) → Biquad

Make this biquad a notch filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.

make_peaking( f: float, q: float, boost_db: float, ) → Biquad

Make this biquad a peaking filter.

Parameters:

ffloat: Center frequency of the filter in Hz.
qfloat: Q factor of the filter.
boost_dbfloat: Gain of the filter in decibels.

set_parameters( parameters: BiquadSlewParameters, ): Set the slewing biquad parameters.

set_slew_shift(slew_shift): Set the slew shift for a biquad object. This sets how fast the filter will slew between filter coefficients.

pydantic model audio_dsp.models.biquad.BiquadSlewParameters

Parameters for a slewing biquad filter.

field filter_type: BIQUAD_TYPES = biquad_bypass(type='bypass'): Type of biquad filter to implement and it’s parameters.

field slew_shift: int = 6

The shift value used in the exponential slew.

Constraints:

ge = 0
lt = 31

BiquadSlew Control¶

The following runtime command ids are available for the BiquadSlew Stage. For details on reading and writing these commands, see the Run-Time Control User Guide.

Control parameter	Payload length
CMD_BIQUAD_SLEW_LEFT_SHIFT	`sizeof(int)`
The number of bits to shift the output left by, in order to compensate for any right shift applied to the biquad b coefficients.

CMD_BIQUAD_SLEW_FILTER_COEFFS	`sizeof(int32_t)*[5]`
The normalised biquad filter coefficients, in the order [b0, b1, b2, -a1, -a2]/a0. The coefficients should be in Q1.30 format. If the maximum b coefficient magnitude is greater than 2.0, the b coefficients should be right shifted to fit in Q1.30 format, and the shift value passed as left_shift to correct the gain after filtering. Biquad coefficients can be generated using the helper functions in `control/biquad.h`. See Biquad helpers.

CMD_BIQUAD_SLEW_RESERVED	`sizeof(int32_t)*[3]`
Reserved memory to ensure the VPU receives 8 DWORD_ALIGNED coefficients. This command is read only. When sending a write control command, it will be ignored.

CMD_BIQUAD_SLEW_SLEW_SHIFT	`sizeof(int)`
The shift value used to set the slew rate. See the biquad slew control documentation for conversions between slew_shift and time constant.