metrology.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(w0) * sinh(ln(2)/2 * BW * w0/sin(w0)) (the w0/sin(w0) 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

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

Name	Description
frequencies	Evaluation frequencies, in Hz (log-spaced).
magnitude_db	Cascade magnitude, in dB.
phase_rad	Cascade phase, unwrapped, in radians.
section_magnitude_db	Per-section magnitude, in dB, shape (n_sections, n_frequencies) - the cascade magnitude is their sum.
sos	The designed cascade, shape (n_sections, 6) (scipy SOS layout, normalized so every section’s a0 is 1).
fs	Sample rate, in Hz.
sections	The EQSection specifications, in cascade order.

EQResponseResult.plot()

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

Name	Description
ax	Existing axes for the magnitude panel, or None for a fresh two-panel (magnitude + phase) figure.
language	Label language, "en" (default) or "es".
show_sections	Overlay each section’s individual response under the cascade curve (default True).

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

EQSection

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

Name	Description
filter_type	'peaking', 'lowshelf', 'highshelf', 'lowpass', 'highpass', 'bandpass' (constant 0 dB peak gain), 'bandpass_skirt' (constant skirt gain, peak gain Q), 'notch' or 'allpass'.
f0	Centre/corner frequency, in Hz (must sit below Nyquist).
gain_db	Gain G in dB - peaking and shelving types only.
q	Quality factor. Exactly one of q, bw and slope may be given; with none, q = 1/sqrt(2) (Butterworth alignment).
bw	Bandwidth in octaves (peaking: between the midpoint-gain frequencies; band-pass/notch: between the -3 dB frequencies).
slope	Shelf-slope parameter S (shelves only; S = 1 is the steepest monotonic slope, and S must stay below the gain-dependent bound (A + 1/A)/(A + 1/A - 2) with A = 10^(gain_db/40), beyond which the cookbook’s alpha turns complex; at 0 dB gain A = 1, the bound is unbounded and every positive slope is admissible).

parametric_eq

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

Name	Description
x	Input signal (1D or 2D [channels, samples]).
fs	Sample rate in Hz.
sections	One EQSection or a sequence of them.

Returns: Equalized signal.

ParametricEQ

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

Name	Description
fs	Sample rate in Hz.
sections	One EQSection or a sequence of them; the cascade applies them in order.
stateful	If True, filter carries the filter state across calls (block processing).
steady_ic	If True, initialize the state at steady state.

ParametricEQ.filter()

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

Apply the EQ cascade to a signal.

Parameters

Name	Description
x	Input signal (1D or 2D [channels, samples]).

Returns: Equalized signal.

ParametricEQ.response()

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

Name	Description
n_points	Number of evaluation frequencies.
f_min	Lowest frequency, in Hz.
f_max	Highest frequency, in Hz (default: Nyquist).

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