# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`GraphicEQ` - ten octave bands and two level sliders, after the MXR
M-108 Ten Band.
The player's text is the class docstring; the `CLAIMS` table in the class's
test file ties its claim sentences to tests.
"""
# Design notes, from the rebuild.
#
# The M-108 is not ten filters in parallel. It is one op-amp stage whose gain
# is varied across a tuned circuit, nine gyrator bells at 31.25 Hz doubling to
# 8 kHz and a shelf at 16 kHz, with a mechanical centre detent at which each
# band is out of the circuit. Two more sliders, GAIN and VOLUME, sit around the
# bank.
#
# The bands get wider as you back off, and that is the whole character.
# Because the slider loads the tuned circuit, the M-108's Q moves with it: a
# band is narrow only near the ends of its travel and, a couple of dB in, has
# "degraded into something nearer to a 10-band octave equalizer" (Bohn, JAES
# 34(9)). This class does the same thing arithmetically -- `Q` is computed from
# each band's gain on every macro move, holding a 1 dB skirt still while the
# peak grows. At `Band Q` 2.0 the 1 kHz band is 1.8 octaves wide at +3 dB and
# 0.71 at +12. Turn `Constant Q` on and every band keeps one width at every
# setting, which is the other half of Bohn's paper and sounds like a studio
# graphic rather than a pedal.
#
# Bands overlap and add. Three adjacent sliders at +6 dB do not give you
# +6 dB: measured, they give +8.78 dB across 2.6 octaves. That is what a
# musician hears when they draw a curve on this pedal, and it is why the two
# level sliders exist. All ten at +6 dB reach +8.70 dB on average from 60 Hz
# to 8 kHz, with 2.35 dB of ripple between the centres -- the bank is hot and
# not quite flat, and the dossier records both as measured rather than as
# intended.
#
# The 16k slider is a shelf, and its corner sits below its label. A shelf's
# named frequency is where it has reached *half* its gain, so a corner on
# 16 kHz would move 16 kHz by 6 dB of a 12 dB request and put the rest above
# hearing. Half an octave down puts +10.91 dB at 16 kHz and +11.94 at
# 20 kHz, and lifts the 8 kHz slider's own centre by less than 2 dB.
#
# Those treble figures need headroom, and the panel can take it away. Every
# section writes int16 between stages, so a +12 dB request stops being +12 dB
# well below full scale. The shelf holds its full lift to a source peaking
# about 13 000 LSB (-8.1 dBFS) -- +9.15 dB at 16 kHz and +9.51 at 20 kHz --
# and at 14 000 it is down to +8.78 / +8.90. `Gain` reaches the same place
# on a quiet source: with the input at 6 000, `Gain` +9 dB against `Volume`
# -9 dB reads +7.40 dB at 20 kHz, and +12 against -12 reads +4.64. The
# 16 kHz slider is worth its label on a source with room above it; on a hot one
# it is worth less, and the way to get it back is to pull `Gain` down rather
# than push it up (evidence pack T1, disconfirmed above that level).
#
# And a patch's `Volume` trim comes off the treble reading too. Push the
# 16k slider to +12 on top of a recalled patch and it measures, against the
# dry source, +6.12 dB at 20 kHz on `Scooped Mids`, +7.54 on `Pushed Mids`
# and +4.61 on `Full Boost` -- because those three trim `Volume` by 5.95,
# 4.44 and 7.46 dB so that they are a curve and not a volume. Add the trim
# back and the shelf's own lift is +11.98 to +12.08 dB at all six patches:
# the slider still does what it says, and the bank is quieter. `Rolled Top` is
# the one that is not a trim -- its 8 kHz cut pulls 16 kHz 1.57 dB below
# 20 kHz, past the 1.5 dB the trait allows -- so the shelf's shape does depend
# on the slider under it.
#
# A band at its detent is a wire, byte for byte. `mix` goes to zero on any
# band inside 0.1 dB of centre -- one macro step at +/-12 dB is 0.189 dB, so
# codes 63 and 64 are the detent and nothing else is. This matters more than it
# sounds: a *flat* biquad section at 31.25 Hz is not bit-transparent in float32
# (Direct Form I, poles that close to z = 1, up to 5 LSB over 24 000 frames),
# so a band left "at zero" with `mix = 1` would quietly rewrite the bottom
# octave.
#
# Latency: zero, at every setting and every rate. Twelve biquads, nothing
# that looks ahead. No option on this class adds any -- there is no lookahead,
# no partition and no window to add, so the table of latency-adding options is
# empty on purpose.
#
# Tail: the build's own. `tail_samples` bounds the ring-down of the
# sections in circuit at the settings in force, from whatever state they hold,
# so it also covers a move made as the input stops. A flat curve is a wire with
# no tail; the 31.25 Hz band at full boost rings for about half a second.
#
# It is loud, and it clips where the pedal clips. `Gain` sits before the
# bank and `Volume` after, as the panel reads; each node writes int16 between
# sections and saturates at full scale, so +12 dB of Gain into a hot source
# clips at the first section -- an M-108's op-amps do too. Pull `Volume` down
# when you push `Gain` up, or push the bank instead.
#
# `audiodsp` tier: it needs `audiobiquad`. The ported `synthio.Biquad` holds
# DC after silence at exactly this bank's bottom two bands -- +7 LSB at 31.25 Hz
# and +5 LSB with all ten engaged, for ever (audiodsp#23). Those are the numbers
# that made the DC-clean node (audiodsp#39); on it every one of them is exact
# zero.
#
# Cost. Twelve biquad sections run at every setting -- a flat band is muted,
# not skipped -- which is about two thirds of an ESP32-S3's stereo block and
# under two fifths of an ESP32-P4's. There is no lean patch, because a patch
# cannot change the node count.
#
# The class docstring before the player's text, kept for its figures.
#
# A ten-band octave graphic EQ with proportional Q, after the MXR M-108.
#
# `audiodsp` tier: it needs `audiobiquad`, whose float state is what lets a
# 31.25 Hz band reach exact zero after silence.
#
# Twelve `audiobiquad.Biquad` nodes in series -- `Gain`, nine bells, the
# 16 kHz shelf, `Volume`. A band inside the detent is crossfaded out
# (`mix = 0`), so it is a wire byte for byte while its knob still turns.
VENDOR = "PyDevices"
import math
from . import _component
try:
import audiobiquad
except ImportError: # a stock CircuitPython board, or an old audiodsp
audiobiquad = None
#: The M-108's own centres: exact octave doublings from 31.25 Hz, not the ISO
#: preferred series (G1 and G2's Filtering line, and the panel legend).
DEFAULT_CENTRES = (31.25, 62.5, 125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0,
8000.0, 16000.0)
#: The band travel, and therefore the width of the detent. One step on the
#: 0-127 grid is 24/127 = 0.189 dB, so codes 63 and 64 sit at -/+0.094 dB and
#: code 65 at +0.283: a 0.1 dB dead band is exactly the two centre codes.
_BAND_DB = 12.0
_DETENT_DB = 0.1
#: The shelf's half-gain corner sits this far below its named band.
#:
#: An RBJ shelf's `frequency` is where it has reached *half* its dB gain, so a
#: shelf whose corner is its own band centre gives that band only +6.00 dB of
#: a +12 dB request and puts the rest above 20 kHz -- measured, and most of it
#: past hearing. Half an octave lower puts **+10.91 dB at 16 kHz** and +11.94
#: at 20 kHz, while lifting the 8 kHz bell's centre by only 1.96 dB, so the
#: top slider does what its label says and the two bands stay apart.
_SHELF_CORNER_RATIO = 2.0 ** 0.5
#: A shelf takes `Q` as a resonance, not a bandwidth, and 1.4 makes it
#: overshoot: at 16 kHz and +12 dB it measures **-2.37 dB at 12 kHz** and
#: +13.94 at 20 kHz -- a cut below the corner and 1.9 dB past the asymptote
#: above it. 0.707 is the flat shelf a level slider means.
_SHELF_Q = 0.7071067811865475
#: The corner of the two level sections. A `HIGH_SHELF` is the only shape on
#: this palette that can give gain above unity (`audiomixer` clamps its level
#: to 1.0 silently, `audiomath.Multiply` can only attenuate), and 5 Hz is the
#: corner at which +12 dB measures +12.00 dB at 30 Hz as well as at 10 kHz.
#: At 10 Hz the 30 Hz reading is already 0.22 dB short.
_LEVEL_CORNER_HZ = 5.0
#: The proportional-Q law's skirt: the level, in dB, whose crossing frequency
#: is held still while the peak grows.
_SKIRT_DB = 1.0
#: The anchor gain the `Band Q` macro names the Q of.
_ANCHOR_DB = 12.0
#: `audiodsp_filter_f32.c:99-100` clamps Q into this band for stability; the class
#: clamps to the same numbers so a macro cannot ask for what the kernel will
#: silently refuse.
_Q_MIN = 0.05
_Q_MAX = 60.0
#: The largest per-build bound found at 48 kHz over 400 random settings of
#: the fourteen macros at their stops, about 4.5 s. `tail_samples`
#: reports the build in force, which is what a host should read; this is
#: the class's static figure. Before audiocomponents#114 it was a measured
#: 0.47 s, which a Gain or Volume move to the bottom outlived.
_DESIGN_TAIL_SAMPLES = 217895
_SKIRT = 10.0 ** (_SKIRT_DB / 20.0)
_ANCHOR_A = 10.0 ** (_ANCHOR_DB / 40.0)
_ANCHOR_NUM = _ANCHOR_A ** 2 - (_SKIRT ** 2) / (_ANCHOR_A ** 2)
[docs]
def band_q(gain_db, anchor):
"""The Q a band of `gain_db` gets, for a bank anchored at `anchor`.
`ParametricEQ`'s proportional-Q law, rearranged so the anchor is the
macro: holding the +/-1 dB skirt at one frequency while the peak grows
means `Q(G) = anchor * sqrt((A^2 - L^2/A^2) / (A12^2 - L^2/A12^2))` with
`A = 10^(|G|/40)`. Below +1 dB there is no root -- a 1 dB skirt cannot sit
on a 1 dB bell -- and Q floors at the kernel's own minimum, which is the
limit of the law rather than a special case.
"""
amplitude = 10.0 ** (abs(gain_db) / 40.0)
numerator = amplitude ** 2 - (_SKIRT ** 2) / (amplitude ** 2)
if numerator <= 0.0:
return _Q_MIN
return min(_Q_MAX, max(_Q_MIN,
anchor * math.sqrt(numerator / _ANCHOR_NUM)))
[docs]
class GraphicEQ(_component.Component):
"""A ten-band octave graphic EQ after the MXR M-108: nine bells and a
top shelf, between a Gain and a Volume slider.
**Bands.** The bands sit an octave apart from 31.25 Hz to 8 kHz, and
the top one is a shelf at 16 kHz. At its centre detent a band is out of
the circuit, so a flat bank is the source byte for byte. A band brought
back from the detent starts from nothing. `centres=` retunes the bank
to ten ascending frequencies, and the shelf stays the top band.
**Band Q and Constant Q.** As on the pedal, a band narrows as its
slider travels. Band Q is its width at full travel, and it is wider
than that a few dB in. Constant Q holds every band at Band Q at every
setting.
**Gain and Volume.** Gain sits before the bank and Volume after it.
Each moves every frequency alike, within 0.15 dB. The Effect controls
page lists what the knobs span and the patches.
**Level.** Bands overlap and add: three adjacent sliders at +6 dB lift
the middle one's frequency by more than 7 dB. Every section hands the
next an int16, so leave headroom, and pull Volume down when you push
Gain up. A band, Gain or Volume at its top can push a full-scale input
onto the rails.
**Patches.** Scooped Mids, Pushed Mids and Full Boost pull Volume down,
so stepping through them you hear the curve rather than the level. A
patch change starts the bank clean and doesn't overshoot; a knob move
rides through.
**Sample rate.** At 48 kHz and 44.1 kHz every band is where its label
says. At 22.05 kHz the 16 kHz shelf is past Nyquist, so it is built
just under it and `clamped` says so.
**Latency and tail.** It adds no latency at any setting. Silence in is
exact zero out, and `tail_samples` bounds the ring for the settings in
force, after a knob move too. A mono source gets the same curve.
It needs `audiobiquad`, so a stock CircuitPython board can't run it.
"""
NAME = 'GraphicEQ'
DISPLAY_NAME = 'Graphic EQ'
CATEGORIES = ('EQ',)
VERSION = '0.0.1'
TIER = _component.AUDIODSP
REQUIRES = ("audiobiquad",)
#: The transport is never read: nothing here is tempo-dependent, and a
#: filter bank has no rate to lock to.
CAPABILITIES = ()
LATENCY_SAMPLES = 0
TAIL_SAMPLES = _DESIGN_TAIL_SAMPLES
#: Settings that clip by design: the rail check skips them.
CLIPS_AT_TOP = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)
MACRO_LABELS = ("31", "63", "125", "250", "500", "1k", "2k", "4k", "8k",
"16k Shelf", "Gain", "Volume", "Band Q", "Constant Q")
MACRO_MODES = {0: "BIPOLAR", 1: "BIPOLAR", 2: "BIPOLAR", 3: "BIPOLAR",
4: "BIPOLAR", 5: "BIPOLAR", 6: "BIPOLAR", 7: "BIPOLAR",
8: "BIPOLAR", 9: "BIPOLAR", 10: "BIPOLAR", 11: "BIPOLAR",
12: "UNIPOLAR", 13: "TOGGLE"}
_MACRO_RANGES = (((-_BAND_DB, _BAND_DB),) * 12
+ ((0.7, 2.5), (0.0, 1.0)))
_MACRO_UNITS = {
0: "dB", 1: "dB", 2: "dB", 3: "dB", 4: "dB", 5: "dB", 6: "dB", 7: "dB",
8: "dB", 9: "dB", 10: "dB", 11: "dB",
}
#: Every band macro at 64 is the detent, so patch 0 is a wire.
#:
#: The three boosting patches carry a `Volume` trim, and it is not
#: decoration: measured on an 11000-peak source, `Scooped Mids` reaches
#: 21574 at the detent, `Pushed Mids` 17893 and `Full Boost` 26741 -- the
#: last of those clips a source only 3 dB hotter. Each trim is the one
#: that brings its patch back to roughly `Flat`'s own level, so a player
#: hears the curve rather than the volume when they step through them.
#: That is what the VOLUME slider is for on the pedal.
_FLAT = 64
PATCHES = {
0: ("Flat", (64,) * 12 + (92, 0)),
1: ("Scooped Mids", (95, 95, 79, 48, 32, 32, 48, 79, 95, 95,
64, 32, 92, 0)),
2: ("Pushed Mids", (48, 48, 64, 79, 95, 95, 95, 79, 64, 48,
64, 40, 92, 0)),
3: ("Trimmed Bottom", (16, 32, 48, 64, 64, 64, 64, 64, 64, 64,
64, 64, 92, 0)),
4: ("Rolled Top", (64, 64, 64, 64, 64, 64, 64, 48, 32, 16,
64, 64, 92, 0)),
5: ("Full Boost", (95,) * 10 + (64, 24, 92, 0)),
}
#: Macro indexes, named so the arithmetic below reads.
_FIRST_BAND = 0
_BANDS = 10
_GAIN = 10
_VOLUME = 11
_BAND_Q = 12
_CONSTANT_Q = 13
def _build(self, gains_db=None, gain_db=0.0, volume_db=0.0, band_q=2.0,
constant_q=False, centres=None, patch=None):
"""Build the twelve sections, head to tail.
`gains_db` sets the whole curve in one call -- up to ten numbers in
dB, in the order the panel reads, low to high; a short list leaves the
rest of the bank at its detent. `centres` retunes the bank and
must be **exactly ten ascending frequencies**: the macro surface is
fixed at fourteen, so a shorter list would leave knobs addressing
nothing. The 16 kHz shelf is always `centres[9]`, so it stays the top
band through any retune.
"""
centres = DEFAULT_CENTRES if centres is None else tuple(
float(hz) for hz in centres)
if len(centres) != self._BANDS:
raise ValueError("centres must name exactly %d frequencies, "
"low to high" % self._BANDS)
for index in range(1, self._BANDS):
if centres[index] <= centres[index - 1]:
raise ValueError("centres must ascend")
self._centres = centres
# Fewer than ten sets the bottom of the bank and leaves the rest at
# the detent, which is what the old class's `zip(ISO_BANDS, gains_db)`
# did and what the callers that already pass five expect. More than
# ten is a caller who thinks this bank is a different size, and that
# is an error rather than a truncation.
gains_db = () if gains_db is None else tuple(
float(db) for db in gains_db)
if len(gains_db) > self._BANDS:
raise ValueError("gains_db names %d bands; this bank has %d"
% (len(gains_db), self._BANDS))
gains_db = gains_db + (0.0,) * (self._BANDS - len(gains_db))
# `_hz()` clamps to 0.98 x Nyquist rather than refusing: at 22.05 kHz
# the 16 kHz shelf has nowhere to sit, and a biquad asked for a corner
# over Nyquist rails into a full-scale square wave at fs/4 while
# raising nothing. What was clamped is reported, never dropped.
# The top band is a shelf, so what goes into the filter is its
# half-gain corner rather than the band's own name.
asked = tuple(list(centres[:self._BANDS - 1])
+ [centres[self._BANDS - 1] / _SHELF_CORNER_RATIO])
self._built_hz = tuple(self._hz(hz) for hz in asked)
self._clamped = tuple(index for index in range(self._BANDS)
if self._built_hz[index] != asked[index])
# Head: Gain, before the bank, as the panel reads.
self._gain = self._own(self._section(audiobiquad.HIGH_SHELF,
_LEVEL_CORNER_HZ, _SHELF_Q))
self._gain.play(self._source)
previous = self._gain
# The bank: nine bells and the shelf on top.
self._sections = []
for index in range(self._BANDS):
shelf = index == self._BANDS - 1
mode = audiobiquad.HIGH_SHELF if shelf else audiobiquad.PEAKING_EQ
# A bell's Q is replaced on every macro move by the law; the
# shelf's is not a bandwidth and stays where it is put.
node = self._own(self._section(mode, self._built_hz[index],
_SHELF_Q if shelf else 1.4))
node.play(previous)
self._sections.append(node)
previous = node
# Tail: Volume, after the bank.
self._volume = self._own(self._section(audiobiquad.HIGH_SHELF,
_LEVEL_CORNER_HZ, _SHELF_Q))
self._volume.play(previous)
self._output = self._volume
self._init_macros(
tuple(gains_db) + (float(gain_db), float(volume_db),
float(band_q), 1.0 if constant_q else 0.0),
patch)
def _section(self, mode, frequency, q):
"""One node, muted. Every section starts as a wire and `_apply_macro`
is the only thing that ever un-mutes one, so the constructor and a
later `set_macro` cannot disagree about what a detent means."""
return audiobiquad.Biquad(mode=mode, frequency=frequency, Q=q,
gain_db=0.0, mix=0.0,
sample_rate=self._sample_rate,
channel_count=self._channel_count)
def _apply_macro(self, index, position):
if index < self._BANDS:
self._retune(index)
elif index == self._GAIN:
self._level(self._gain, self._GAIN)
elif index == self._VOLUME:
self._level(self._volume, self._VOLUME)
else:
# Band Q and Constant Q are the law, not a band: both move every
# bell at once. The shelf keeps its own Q, which is not a
# bandwidth.
for band in range(self._BANDS):
self._retune(band)
def _retune(self, band):
gain_db = _component.macro_value(self._MACRO_RANGES[band],
self._macros[band])
node = self._sections[band]
if abs(gain_db) < _DETENT_DB:
# `mix = 0` makes the kernel compute `1.0f * x + 0.0f * y`, which
# is the input sample exactly. A `gain_db = 0` section used to
# drift up to 5 LSB at 31.25 Hz over 24000 frames and no longer
# does -- audiobiquad's transposed direct form II (audiodsp#64) is
# bit-transparent at 0 dB at all ten centres, measured in
# `tests/test_cpython_effects_graphiceq.py`. So what this branch
# buys now is the section's work and `_wake`'s state hygiene, not
# a different output -- so T4's guard is a measurement of a band
# coming BACK from the detent, not of a steady render
# (audiocomponents#88).
node.mix = 0.0
return
self._wake(node)
if band < self._BANDS - 1:
node.Q = self._q_for(gain_db)
node.gain_db = gain_db
node.mix = 1.0
@staticmethod
def _wake(node):
"""Clear a section that is leaving the detent.
The kernel runs the recursion even at `mix = 0`
(`audiodsp_filter_f32.c:216-241` has no short-circuit), so a muted
section's state is a filter nobody heard, tracking the input through
the coefficients it had when it was last live. Handing that state to
the filter about to run is what makes a slider slam.
**This is the `set_macro` path and only that path.** `program_change`
clears every node in the bank before anything else, so a patch change
never reaches here and the same fault is invisible through it -- the
numbers this docstring used to carry were a patch change's, and they
cannot be reproduced now. Measured on a 220 Hz tone at peak 3000,
all ten bands driven to full boost, held at the detent for half a
second and then driven to full cut: the class peaks at **824**
against a settled 668, and without this at **1714**, 8.2 dB over the
level it is arriving at. Live-to-live moves are deliberately not
cleared -- those states mean something, a slider being pushed should
ride through on the state it has, and that path is byte-identical
with this method and without it. Both halves are asserted in
`tests/test_cpython_effects_graphiceq.TheDetentIsAWire`, which is
where T4's planted fault lives since audiocomponents#88.
"""
if node.mix == 0.0:
node.clear()
def _q_for(self, gain_db):
anchor = _component.macro_value(self._MACRO_RANGES[self._BAND_Q],
self._macros[self._BAND_Q])
if self._macros[self._CONSTANT_Q] >= 0.5:
return min(_Q_MAX, max(_Q_MIN, anchor))
return band_q(gain_db, anchor)
def _level(self, node, index):
gain_db = _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
if abs(gain_db) < _DETENT_DB:
node.mix = 0.0
return
self._wake(node)
node.gain_db = gain_db
node.mix = 1.0
def _apply_positions(self, positions, patch_index):
"""Jump to a patch (or a rack's restore), and start the new curve
from a clean bank.
The difference between this and `set_macro` is deliberate, and it is
the difference between a jump and a sweep. A slider being pushed
should ride through on the state it has; a patch change is ten
sliders arriving somewhere else at once, and handing that jump a
bank full of the old curve's memory is what makes it slam. Measured
on a 220 Hz tone at peak 11000, `Full Boost` to `Scooped Mids`
peaks at **32767 and stays above its own steady level for 306 ms**
without this, and at **5826 for 8 ms** with it.
"""
_component.Component._apply_positions(self, positions, patch_index)
for node in self._nodes:
node.clear()
@property
def tail_samples(self):
"""The ring time of *this* build: Gain, the ten bands and Volume,
each section in circuit bounded from its coefficients in force
(`_component.biquad_ring`) and summed down the chain. The bound
holds from any state the sections can hold, including what the
settings before a move left in them: a Gain or Volume move from the
top to the bottom as the input stopped rang 10 to 20 % past the old
fixed 0.47 s (audiocomponents#114). A flat section is a wire and
adds nothing.
"""
self._check_live()
return _component.cascade_ring(
[node for node in [self._gain] + self._sections + [self._volume]
if node.mix > 0.0])
@property
def centres(self):
"""The band centres this instance was asked for, in Hz."""
self._check_live()
return self._centres
@property
def built_centres(self):
"""What is actually in the filters: nine bell centres and, in the
tenth slot, the **shelf's half-gain corner** -- half an octave below
its named band, so the band gets 10.91 dB of a 12 dB request rather
than 6.00.
At a rate too low to hold the top of the bank the values are clamped
as well: at 22.05 kHz the shelf's corner sits at 10804.5 Hz rather
than 11313.7. `clamped` says which, so a caller reads the clamp
rather than inferring it from a response it did not ask for.
"""
self._check_live()
return self._built_hz
@property
def clamped(self):
"""The indexes of the bands whose centre was clamped below Nyquist.
Empty at 48 kHz and 44.1 kHz. The old class dropped those bands
silently instead; nothing said so, which is absence reading as
agreement.
"""
self._check_live()
return self._clamped