filters.equalizer

Parametric equalizer biquads per the RBJ Audio EQ Cookbook.

Second-order (biquad) IIR sections designed from the closed-form recipes of Robert Bristow-Johnson’s Audio EQ Cookbook, the de-facto reference for parametric equalization (published as a W3C Working Group Note: https://www.w3.org/TR/audio-eq-cookbook/). Every filter type of the cookbook is available:

• peaking - the bell of a parametric EQ: gain G dB exactly at f0, 0 dB exactly at DC and Nyquist.
• lowshelf / highshelf - shelving filters: gain G dB exactly at DC (low shelf) or Nyquist (high shelf), 0 dB at the opposite end, with the transition centred on f0 (the midpoint-gain frequency).
• lowpass / highpass - second-order Butterworth-style sections with a resonance set by Q ($Q=1/\sqrt{2}$ is the Butterworth alignment; the magnitude at f0 is exactly Q).
• bandpass - constant 0 dB peak gain at f0.
• bandpass_skirt - the cookbook’s constant-skirt-gain variant (peak gain Q).
• notch - a null exactly at f0, 0 dB at DC and Nyquist.
• allpass - unit magnitude everywhere; only the phase turns (360 degrees across the band, steepest at f0).

Each section is parameterized exactly as the cookbook defines: sample rate fs, centre/corner frequency f0, gain gain_db (peaking and shelves only) and one of

• q - the quality factor (default $1/\sqrt{2}$),
• bw - the bandwidth in octaves, mapped through the cookbook’s digital-domain relation $\alpha =\sin ({\omega }_0)\sinh \left(\frac{\ln 2}{2}BW\frac{{\omega }_0}{\sin {\omega }_0}\right)$ (the ${\omega }_0/\sin {\omega }_0$ factor compensates the bilinear frequency warping), or
• slope - the shelf-slope parameter S (shelves only; $S=1$ is the steepest slope that stays monotonic).

For the peaking filter the bandwidth is measured between the midpoint-gain ($G/2$ dB) frequencies; for band-pass and notch, between the -3 dB frequencies - both as the cookbook states.

The design is exact, not approximate: the cookbook’s formulas are the bilinear transform of second-order analog prototypes with the frequency prewarped so the analog f0 lands exactly on the digital f0. Closed-form consequences pinned by the test suite: the peaking gain at f0 is exactly G dB, shelves reach exactly G dB at their shelved end and exactly 0 dB at the other, the all-pass magnitude is exactly 1 at every frequency, and the half-gain bandwidth honours the cookbook’s Q definition.

Reference: Bristow-Johnson, R. Audio EQ Cookbook. Republished as a W3C Working Group Note (ed. R. Toy), 8 June 2021. https://www.w3.org/TR/audio-eq-cookbook/

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

EQResponseResult(
    frequencies: NDArray[np.float64],
    magnitude_db: NDArray[np.float64],
    phase_rad: NDArray[np.float64],
    section_magnitude_db: NDArray[np.float64],
    sos: NDArray[np.float64],
    fs: float,
    sections: tuple[EQSection, ...],
)

Frequency response of a parametric-EQ cascade (RBJ Audio EQ Cookbook).

Attributes

EQResponseResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    show_sections: bool = True,
    **kwargs: Any,
) -> Axes | NDArray[Any]

Plot the cascade magnitude and phase response.

With ax given, only the magnitude panel is drawn on it.

Parameters

Returns: The magnitude axes (ax given) or the array of two axes.

EQSection(
    filter_type: EQFilterType,
    f0: float,
    gain_db: float = 0.0,
    q: float | None = None,
    bw: float | None = None,
    slope: float | None = None,
)

One biquad of the RBJ Audio EQ Cookbook.

Attributes

parametric_eq(
    x: Signal,
    fs: float | None = ...,
    *,
    sections: EQSection | Sequence[EQSection],
) -> Signal

parametric_eq(
    x: list[float] | np.ndarray,
    fs: float,
    *,
    sections: EQSection | Sequence[EQSection],
) -> np.ndarray

Apply a parametric-EQ cascade to a signal (RBJ Audio EQ Cookbook).

Convenience wrapper around ParametricEQ for one-shot use.

Parameters

Returns: Equalized signal.

ParametricEQ(
    fs: float,
    sections: EQSection | Sequence[EQSection],
    stateful: bool = False,
    steady_ic: bool = False,
)

Cascade of RBJ Audio EQ Cookbook biquads.

Designs one second-order section per EQSection and runs them in series as a numerically robust SOS cascade, following the house style of WeightingFilter (reusable coefficients, optional stateful block processing).

Parameters

ParametricEQ.filter(
    x: Signal | list[float] | np.ndarray,
) -> Signal | np.ndarray

Apply the EQ cascade to a signal.

Parameters

Returns: The equalized record. A bare array in gives a bare array back; a Signal gives a Signal, on the same terms as parametric_eq.

Raises

ParametricEQ.response(
    n_points: int = 2048,
    *,
    f_min: float = 10.0,
    f_max: float | None = None,
) -> EQResponseResult

Evaluate the cascade frequency response on a log-spaced grid.

Parameters

Returns: An EQResponseResult (carries the SOS cascade and plots the magnitude/phase response).