Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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_block `audio_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:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

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

    Make this biquad a second order bandpass filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      bw float

        Bandwidth of the filter in octaves.

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

    Make this biquad a second order bandstop filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      bw float

        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:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

      boost_db float

        Gain of the filter in decibels.

  make_gain(gain_db: float) → Biquad

    Make this biquad a gain stage.

    Parameters:
      gain_db float

        Gain of the filter in decibels.

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

    Make this biquad a second order high pass filter.

    Parameters:
      f float

        Cutoff frequency of the filter in Hz.

      q float

        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:
      f float

        Cutoff frequency of the shelf in Hz, where the gain is boost_db/2

      q float

        Q factor of the filter.

      boost_db float

        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:
      f0 float

        The original cutoff frequency of the filter in Hz.

      q0 float

        The original quality factor of the filter at f0.

      fp float

        The target cutoff frequency for the filter in Hz.

      qp float

        The target quality factor for the filter.

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

    Make this biquad a second order low pass filter.

    Parameters:
      f float

        Cutoff frequency of the filter in Hz.

      q float

        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:
      f float

        Cutoff frequency of the shelf in Hz, where the gain is boost_db/2

      q float

        Q factor of the filter.

      boost_db float

        Gain of the filter in decibels.

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

    Make this biquad a notch filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

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

    Make this biquad a peaking filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

      boost_db float

        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_type audio_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_block `audio_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:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

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

    Make this biquad a second order bandpass filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      bw float

        Bandwidth of the filter in octaves.

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

    Make this biquad a second order bandstop filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      bw float

        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:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

      boost_db float

        Gain of the filter in decibels.

  make_gain(gain_db: float) → Biquad

    Make this biquad a gain stage.

    Parameters:
      gain_db float

        Gain of the filter in decibels.

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

    Make this biquad a second order high pass filter.

    Parameters:
      f float

        Cutoff frequency of the filter in Hz.

      q float

        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:
      f float

        Cutoff frequency of the shelf in Hz, where the gain is boost_db/2

      q float

        Q factor of the filter.

      boost_db float

        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:
      f0 float

        The original cutoff frequency of the filter in Hz.

      q0 float

        The original quality factor of the filter at f0.

      fp float

        The target cutoff frequency for the filter in Hz.

      qp float

        The target quality factor for the filter.

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

    Make this biquad a second order low pass filter.

    Parameters:
      f float

        Cutoff frequency of the filter in Hz.

      q float

        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:
      f float

        Cutoff frequency of the shelf in Hz, where the gain is boost_db/2

      q float

        Q factor of the filter.

      boost_db float

        Gain of the filter in decibels.

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

    Make this biquad a notch filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

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

    Make this biquad a peaking filter.

    Parameters:
      f float

        Center frequency of the filter in Hz.

      q float

        Q factor of the filter.

      boost_db float

        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. |