# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`BandPass` - the two-pole resonant band-pass, rebuilt on `audiobiquad`.
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, moved from the module docstring.
#
# The middle output of every state-variable filter ever built: a wah pedal, a
# telephone, and the mid leg of a multiband crossover are all this one circuit.
# Two knobs and no nonlinearity - a **centre frequency** and a **width** - in
# RBJ's *constant 0 dB peak gain* form, whose numerator `(alpha, 0, -alpha)`
# has zeros at both `z = 1` and `z = -1`. So it is exactly zero at DC and at
# Nyquist, and its peak is 0 dB **at every width**: narrowing the band changes
# what gets through, never how loud it is. That is the property that makes the
# width knob musical rather than a gain staircase.
#
# **Portability tier: audiodsp** (`REQUIRES = ("audiobiquad",)`), and the reason
# is a defect, not a preference. On the ported `synthio.Biquad` the recursion
# keeps its output memory in Q12 sample units with no dither and no leak, so it
# lands on states that reproduce themselves: `BandPass(80 Hz, q=4)` there holds
# -1 LSB of DC for ever after the music stops (audiodsp#23; the dossier's A3).
# `audiobiquad.Biquad` is the float-state answer Phase 1 landed for exactly
# that, and on it every setting this class offers settles to bit-exact zero
# (the dossier's A14). A stock CircuitPython board does not have the module and
# this class says so on construction rather than sounding different there.
#
# **Cost**, in a musician's terms: two float biquad sections and no tables, no
# lookahead and no buffers - the cheapest thing in the effects library after a
# gain stage. Both sections are always built, so the cost is the same whichever
# way `Slope` sits, and it is the same at every patch: 91.2 ns per stereo frame
# at patch 0 and 95.5 at patch 1 on the desktop, against 20 833 ns of real time.
# **Measured on both boards** 2026-09-07: 3.8 % of one 256-frame stereo block at
# 48 kHz on the ESP32-P4 and 6.2 % on the ESP32-S3, against the dossier's budget
# of P4 <= 4 % and S3 <= 13 %. Inside both. There is no `" - lean"` patch and
# none is owed: no reachable setting costs less than patch 0 does.
#
# **Latency: zero, at every rate and every setting.** No option this class
# offers adds any - there is nothing here that looks ahead, so no option needs
# a millisecond figure in this docstring.
#
# Two things about the surface that the algebra, not the taste, decided:
#
# * **`Mix` rides on both sections.** `mix = 0` is a byte-exact wire in both
# slope settings, which is what Tier 1 asks of it. With `Slope` off the blend
# is the plain linear dry/wet `(1-m)*x + m*H(x)`. With `Slope` on it is that
# mixed section run twice, `((1-m)I + mH)^2 x`, and **not** a linear blend
# between the dry signal and the two-section output: per-section crossfades
# cannot cancel their own cross terms, and no arrangement of this palette's
# nodes gets a linear one without a splitter and a mixer.
# * **`Slope` on divides the working Q by 1.5538** - it multiplies by
# `sqrt(sqrt(2) - 1)` - so that two cascaded sections keep the -3 dB width
# the `Width` knob asks for. Without it the cascade's width would be 41 % of
# the number on the panel.
#
# **Five of the dossier's rows are disconfirmed, and they are two different
# things.** One belongs to this build and bounds what the class promises; four
# belong to RBJ's prototype, which this class tracks to nine thousandths of a
# decibel wherever it was checked.
#
# **The build's one - the 0 dB peak is not held at one low, narrow cell.** T1
# says the gain at f0 is 0.00 dB +- 0.05 at every width. Measured 2026-09-17 at
# the audiodsp cebb7ca floor over the whole `Frequency` x `Width` grid at four
# probe levels, it holds in fifty-five of fifty-six cells, both knob stops
# included, and misses in one: **-0.091 dB at f0 31.5 Hz with Q 32**. What it
# sounds like: nothing anyone will hear - a tenth of a decibel on the narrowest
# sub-bass band the knobs reach.
#
# It used to be eleven cells, all f0 <= 63 Hz with Q >= 4, worst -0.50 dB at
# the `Frequency` knob's bottom stop against the `Width` knob's top, with an
# error that changed sign with the signal level. The history of why follows.
#
# The cause is not this class and not the prototype. RBJ's closed form at that
# cell is `+0.00000 dB`, and `audiobiquad`'s own five coefficients, read off the
# node and run through a `float64` recursion, give `-0.003 dB`. Run through the
# kernel's `float32` one they give `-0.480`, which is the class to a ten
# thousandth of a decibel. `audiodsp_filter_f32.c:220-238` is a direct-form I
# biquad with float state, and at `w0 = 0.0026 rad` its two feedback
# coefficients cancel to seven parts in a million, so the increment single
# precision has to carry is 2e-5 of the numbers being differenced. Filed as
# audiodsp#64 with the fix (a transposed direct form II costs nothing at run
# time), and the fix landed; the one cell left is what it did not reach
# (audiocomponents#66).
#
# **The prototype's four**, each measured against RBJ's closed form at the
# running rate and each tracking it to <= 0.009 dB, so none of them is a defect
# of this build - what fails is the tolerance the dossier wrote around a warped
# axis:
#
# * **T4's `|H(f0/100)| = -37.0 +- 0.1 dB` clause, above about 2.5 kHz.**
# Measured `-36.994` at f0 500 Hz, `-37.001` at 1 kHz, `-37.037` at 2 kHz,
# then `-37.279` at 4.8 kHz, `-37.837` at 8 kHz and `-41.350` at 16 kHz,
# against a closed form of `-36.991 / -37.001 / -37.038 / -37.281 / -37.837
# / -41.359`.
# * **T2's `-3 dB` edges, above about 2 kHz.** At f0 4 kHz - patch 3 `Presence
# Window` sits at 4 072 Hz - the predicted edges read `-3.209 / -3.222` at
# Q 16 and `-3.130 / -3.803` at Q 0.5, against a `-3.0 +- 0.15` bar; the
# closed form reads the same four numbers.
# * **T4's low skirt, at Q >= 8.** `+6.435 dB/oct` at f0 500 Hz Q 8 against a
# `+(5.7...6.3)` band - and `+6.435` from the closed form. Patch 4 `Narrow
# Probe` is Q 23.8, so it is a shipped setting, not a corner.
# * **T4's high skirt, at Q >= 8.** `-6.586 dB/oct` at f0 500 Hz Q 8 inside the
# clause's own `f0 <= 600 Hz` condition; closed form `-6.585`.
#
# Read together they say one thing: the +-6 dB/oct and -3 dB clauses are Q 0.707
# statements below about 2 kHz, and the dossier did not write the conditions
# down. The same warp is the defect the trait-critic pass fixed for T4's high
# skirt and left standing in the rest.
#
# **One thing to know before automating it.** The biquad's coefficients step
# at the block boundary - they are deliberately not interpolated, because
# sliding between two high-Q sections can pass through an unstable pair
# (`audiodsp/docs/upstream-diff.md:1953`). So a *hard jump* in `Frequency` or
# `Width` - a program change from a high centre to a low one, say - rings the
# energy stored at the old centre out through the new filter, and that is
# audible as a click: measured 11 964 peak from a 2 637 peak steady state on a
# 1 421 Hz -> 203 Hz jump, against 9 442 for the same jump on the stock palette,
# so it is the shape of the circuit and not of this rebuild. Automate the knob
# in steps and it is a sweep; jump it and it is a click.
#
# `capabilities = ()`: nothing in a band-pass is measured in beats, and the
# class never reads `self._transport()`.
#
# Traits frozen 2026-09-07.
VENDOR = "PyDevices"
import audiobiquad
from . import _component
[docs]
class BandPass(_component.Component):
"""A resonant band-pass: the band around the centre comes through and
the rest falls away.
**Controls.** Frequency is the centre. Width is how wide the band is,
and narrowing it changes what gets through, never how loud the centre
is. Slope on puts a second section behind the first, for steeper skirts
at the same width. Mix at 0 is your dry signal. The Effect controls page
lists what the knobs span.
**Response.** The centre stands at 0 dB at every width, except a tenth
of a decibel low at 31.5 Hz with the band at its narrowest. DC and the
top of the band are cut to exact zero.
**Timing.** Latency is zero at every setting. Silence in settles to
exact silence out. A hard jump in Frequency or Width rings out as a
click; move the knob in steps and it sweeps.
**On a board.** The class needs audiodsp's `audiobiquad`, and on a board
without it construction raises `ImportError`.
"""
NAME = 'BandPass'
DISPLAY_NAME = 'Band Pass'
CATEGORIES = ('Filter',)
VERSION = '0.0.2'
TIER = _component.AUDIODSP
REQUIRES = ("audiobiquad",)
CAPABILITIES = ()
LATENCY_SAMPLES = 0
#: The surface's worst case **at the design rate**: Q 32 at 20 Hz with
#: two sections at 48 kHz, `_component.biquad_ring` = 630 328
#: samples, 13.1 s. A class constant cannot be a ceiling for a resonator
#: whose ring time scales with the sample rate, so `tail_samples` below
#: reports the build instead; this is the design-rate figure a reader of
#: the class gets, not a bound over every rate.
TAIL_SAMPLES = 630328
MACRO_LABELS = ("Frequency", "Width", "Slope", "Mix")
MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "TOGGLE", 3: "UNIPOLAR"}
_MACRO_RANGES = ((20.0, 16000.0, "log"), (0.5, 32.0, "log"),
(0.0, 1.0), (0.0, 1.0))
_MACRO_UNITS = {0: "Hz"}
PATCHES = {
0: ("Wide Mid", (74, 11, 0, 127)),
1: ("Telephone", (81, 27, 127, 127)),
2: ("Snare Crack", (44, 42, 0, 127)),
3: ("Presence Window", (101, 34, 0, 127)),
4: ("Narrow Probe", (74, 118, 0, 127)),
5: ("Sub Window", (21, 55, 127, 127)),
}
#: What every section is built as, beyond the three things the knobs
#: move. A class constant with one job: T1 is a claim about *this*
#: numerator - RBJ's constant 0 dB peak-gain `(alpha, 0, -alpha)` - and a
#: planted fault that puts a different numerator behind the same surface
#: has to reach the class's own build to test it. The gate audit's T1
#: ruling is that the old fault built a bare `audiobiquad.Biquad`
#: outside the class, so its red never passed through `BandPass` at all.
_SECTION = {"mode": audiobiquad.BAND_PASS}
#: `sqrt(sqrt(2) - 1)`. Two cascaded band-passes reach -3 dB where one
#: reaches -1.505 dB, so the working Q must come down by this factor for
#: the cascade's width to stay `f0 / Q`. The dossier's A14 measures it:
#: at 1 kHz, Q 2 the wanted width is 500.0 Hz, `Q * k` gives 497.4 Hz,
#: and `Q / k` - the seed's wording - gives 206.1 Hz.
_CASCADE_Q = 0.6435942529055827
def _build(self, frequency=1000.0, q=0.707, sections=1, mix=1.0,
patch=None):
"""Build the two sections. `sections` is 1 or 2 and seeds the `Slope`
toggle; the second section is always built, because a TOGGLE macro
has to be able to turn it on later, and it is a byte-exact wire while
it is off."""
# Hz-valued spans clamp at the running rate rather than refusing
# (vision section 3, rate-honesty). `_hz` keeps the section off
# Nyquist; 0.4 * F_s is the dossier's own ceiling, which keeps the
# bilinear compression out of T4's high skirt.
self._ceiling = min(16000.0, 0.4 * self._sample_rate)
self._sections = []
upstream = self._source
for _ in range(2):
node = audiobiquad.Biquad(
frequency=self._centre(frequency), Q=float(q), mix=0.0,
sample_rate=self._sample_rate,
channel_count=self._channel_count, **self._SECTION)
node.play(upstream)
self._own(node)
self._sections.append(node)
upstream = node
self._output = self._sections[-1]
self._init_macros(
(frequency, q, 1.0 if int(sections) >= 2 else 0.0, mix), patch)
# -- the knobs ----------------------------------------------------
def _centre(self, hz):
return self._hz(min(self._ceiling, float(hz)))
def _steep(self):
return self._macros[2] >= 0.5
def _value(self, index):
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
def _push_frequency(self):
hz = self._centre(self._value(0))
for section in self._sections:
section.frequency = hz
def _push_q(self):
q = self._value(1)
if self._steep():
q *= self._CASCADE_Q
for section in self._sections:
section.Q = q
def _push_mix(self):
mix = self._value(3)
self._sections[0].mix = mix
self._sections[1].mix = mix if self._steep() else 0.0
def _apply_macro(self, index, position):
del position
if index == 0:
self._push_frequency()
elif index == 1:
self._push_q()
elif index == 2:
# The toggle moves two things at once: the second section stops
# being a wire, and both sections' Q comes down so the width the
# panel asks for survives the cascade.
self._push_q()
self._push_mix()
else:
self._push_mix()
# -- what the build reports ---------------------------------------
@property
def centre_hz(self):
"""The centre frequency in force, after the rate's own clamp."""
self._check_live()
return self._centre(self._value(0))
@property
def bandwidth_hz(self):
"""`Width` as the -3 dB bandwidth it stands for, `f0 / Q`. The knob
stores Q, because Q is what the node takes and what the dossier's T2
is stated in; this is the number a panel shows."""
self._check_live()
return self.centre_hz / self._value(1)
@property
def sections(self):
"""1 or 2 - how many band-pass sections are in the path."""
self._check_live()
return 2 if self._steep() else 1
@property
def tail_samples(self):
"""The ring time of *this* build, not a class constant.
A band-pass is a resonator, so its tail is set by its poles: the
sections' working Q at the centre in force, one section or the two
of the steep slope (`_component.biquad_ring`). The bound holds
from any state the sections can hold, including what the settings
before a move left in them. A host told the surface's worst case at
every setting would allocate 13 s for a filter nobody asked for.
"""
self._check_live()
sections = self._sections if self._steep() else self._sections[:1]
return _component.cascade_ring(sections)