# filters.equalizer

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-21
Updated: 2026-11-11T17:49:27Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Parametric equalizer biquads per the RBJ Audio EQ Cookbook.

---

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` ($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

```python
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`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#eqsection) specifications, in cascade order. |

### EQResponseResult.plot()

```python
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

```python
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, $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^{\text{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

```python
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`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#parametriceq) for one-shot use.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input signal (1D or 2D `[channels, samples]`), or a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal) brings its own, and an explicit value that disagrees with it raises. |
| `sections` | One [`EQSection`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#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

```python
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`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#eqsection) and runs them in
series as a numerically robust SOS cascade, following the house style of
[`WeightingFilter`](https://docs.jmrp.io/phonometry/reference/api/filters/weighting/#weightingfilter)
(reusable coefficients, optional stateful block processing).

**Parameters**

| Name | Description |
| :--- | :--- |
| `fs` | Sample rate in Hz. |
| `sections` | One [`EQSection`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#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()

```python
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`](https://docs.jmrp.io/phonometry/reference/api/io/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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#signal) gives a Signal, on the same terms as [`parametric_eq`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#parametric_eq).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If a Signal's rate is not the cascade's. |

### ParametricEQ.response()

```python
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`](https://docs.jmrp.io/phonometry/reference/api/filters/equalizer/#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. |
