Skip to content

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, with gain G dB exactly at f0 and 0 dB exactly at DC and Nyquist.
  • lowshelf / highshelf: shelving filters, with gain G dB exactly at DC (low shelf) or Nyquist (high shelf), 0 dB at the opposite end, and the transition centred on f0 (the midpoint-gain frequency).
  • lowpass / highpass: second-order Butterworth-style sections with a resonance set by Q ( 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 ),
  • bw: the bandwidth in octaves, mapped through the cookbook’s digital-domain relation (the factor compensates the bilinear frequency warping), or
  • slope: the shelf-slope parameter S (shelves only; is the steepest slope that stays monotonic).

For the peaking filter the bandwidth is measured between the midpoint-gain ( 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

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(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
show_sections: bool = True,
**kwargs: Any,
) -> tuple[Axes, Axes]
EQResponseResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
show_sections: bool = True,
**kwargs: Any,
) -> Axes

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 tuple of two axes.

EQSection(
*,
filter_type: Literal['peaking', 'lowshelf', 'highshelf', 'lowpass', 'highpass', 'bandpass', 'bandpass_skirt', 'notch', 'allpass'],
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, for the peaking and shelving types only.
q Quality factor. Exactly one of q, bw and slope may be given; with none, (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; is the steepest monotonic slope, and S must stay below the gain-dependent bound with , beyond which the cookbook’s alpha turns complex; at 0 dB gain , the bound is unbounded and every positive slope is admissible).
parametric_eq(
x: Signal,
fs: float | None = ...,
*,
sections: EQSection | Sequence[EQSection],
) -> Signal
parametric_eq(
x: NumericArrayLike,
fs: float,
*,
sections: EQSection | Sequence[EQSection],
) -> NDArray[np.float64]

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]), or a phonometry.io.Signal read from a measurement file. A calibrated Signal is equalized in pascals, so the result is in pascals too.
fs Sample rate in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises.
sections One EQSection or a sequence of them. Keyword-only and required: it sits behind an optional fs, and a default here would be a signature that lies about what the call needs.

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

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.

Raises

Exception When
TypeError if fs is not a single number.
ParametricEQ.filter(x: Signal) -> Signal
ParametricEQ.filter(x: NumericArrayLike) -> NDArray[np.float64]

Apply the EQ cascade to a signal.

Parameters

Name Description
x Input signal (1D or 2D [channels, samples]), or a phonometry.io.Signal. A Signal whose rate disagrees with the one this cascade was designed for is refused; a calibrated one is equalized in pascals.

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

Exception When
ValueError If a Signal’s rate is not the cascade’s.
ParametricEQ.response(
n_points: int | np.integer[Any] = 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).

Raises

Exception When
ValueError for an n_points that is not a whole number from 2, or frequency limits outside 0 < f_min < f_max <= fs / 2.
TypeError if f_max or f_min is not a single number, or n_points is a flag, a text or an array where a count goes.