# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`Notch` - the two-pole band-stop: everything except one band, tuned.
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.
#
# Rebuilt from scratch for the effects program's Phase 2 against
# its dossier. The old `eq.py:Notch` is not consulted except for
# the seven defects the dossier's section 7 names.
#
# **Portability tier: audiodsp** (`REQUIRES = ("audiobiquad",)`). All three
# sections are `audiobiquad.Biquad`: float state, and a tail that reaches
# exact zero. The ported `synthio.Biquad` cannot - the mains-hum setting
# `Notch(60 Hz, q=8)` parks on 2 LSB of DC and `Notch(20 Hz, q=32)` on 18, and
# they hold it for ever (audiodsp#23, dossier A3 and A16), which is Tier 1's
# first invariant failing at exactly the settings this class is for.
#
# **What that costs, said here because a caller has to know it.** A `float`
# coefficient set cannot put the notch's zeros exactly on the unit circle:
# `b0` and `b1` are rounded independently, so the rejection at the centre is
# `|2*b0*cos(w0) + b1| * (1+alpha) / (2*alpha*sin(w0))` rather than nothing at
# all. Measured (dossier A16, 48 kHz): under one LSB - a true null - from
# 500 Hz up at Q <= 12, **-35.65 dB at 60 Hz Q 12**, and **-11.21 dB at
# 20 Hz Q 32**. So this class is a clean utility notch across the musical range and
# a 35 dB hum *reducer* at the bottom, not a hum eliminator. The dossier's T1
# is recorded disconfirmed below about 250 Hz for that reason, and its section
# 5 carries the one node ask that would recover 17-36 dB of it. The ported
# kernel is deeper there and cannot hold the Tier 1 invariant; that trade is
# dossier section 8, D1 and D2.
#
# **And one more measured edge.** T2 asks for unity within 0.1 dB at 0.48*Fs
# at every setting. It holds everywhere except the top of the Frequency span
# at the bottom of the Width span, where the notch's *own band* reaches that
# far: at 16 kHz and Q 0.5 the band is 32 kHz wide and 0.48*Fs reads
# -0.21 dB. That is the probe sitting inside the band, not the filter
# leaking, and it is why Frequency clamps at 0.4*Fs rather than at Nyquist.
#
# **Cost.** Three sections, always built, two of them wires at patch 0 - and
# a wire costs what a notch costs, because the kernel runs each recursion
# before it blends and there is no branch on `mix`
# (`audiodsp/src/shared/audiodsp_filter_f32.c:216-241`). So Harmonics buys back
# no CPU: the class costs three sections at every setting. The dossier budgets
# 1.5 % of one stereo block's real-time deadline on the ESP32-P4 and 5 % on
# the S3 with one notch and 2.5 % / 9 % with two, and since the two are the
# same figure it is the higher pair that governs; the board run in the
# evidence pack is what settles it.
#
# **Latency: zero samples, at every setting and every rate.** Every section is
# a recursive biquad reading no sample it has not been given. No option on
# this class adds a lookahead, a partition or a window, so there is no
# latency-adding option to default off and none to name in milliseconds.
#
# `capabilities = ()`: nothing in a notch is measured in beats - its controls
# are hertz and a dimensionless Q - and this class never reads
# `self._transport()`.
VENDOR = "PyDevices"
try:
import audiobiquad
except ImportError: # pragma: no cover - a stock board
audiobiquad = None # `_require_modules` raises for us
from . import _component
#: `audiobiquad`'s own clamp (`AUDIODSP_FILTER_F32_MIN_Q` / `MAX_Q`,
#: `audiodsp/src/shared/audiodsp_filter_f32.c:21-22`), mirrored because the
#: module does not export it. It bites on the harmonic notch: Width 32
#: doubles to 64 and lands on 60, so the harmonic is 6.7 % wider in hertz
#: than the fundamental there. Stated rather than hidden - dossier D3.
MIN_Q = 0.05
MAX_Q = 60.0
#: The harmonic notch sits at this multiple of the centre, and its Q is
#: multiplied by the same number so that its width *in hertz* matches the
#: fundamental's: width is f/Q (S3), so f -> 2f at Q -> 2Q is the same
#: number of hertz. Mains harmonics are exact multiples, so the narrow one
#: is what a hum eliminator wants (dossier A16, D3: 5.00 Hz against 10.00).
HARMONIC = 2.0
#: The highest centre this class will tune to, as a fraction of the rate.
#: Not `_hz()`'s 0.49: T2 reads unity at 0.48*Fs, and a notch centred above
#: this has its own band over that probe. Clamps, never refuses - the
#: rate-honesty invariant (vision section 3).
CENTRE_CEILING = 0.4
#: The trim is one high shelf at a subsonic corner, which is a broadband
#: gain everywhere above it: no node on the palette gives gain above unity
#: (`MixerVoice.level` clamps to 0..1, `audiomath.Multiply` only
#: attenuates), and there is no route from Python to a biquad's `b`
#: coefficients. Measured on this node at 48 000 / 44 100 / 22 050 Hz and
#: -12/-6/+6/+12 dB: worst deviation from the requested gain 0.105 dB, at
#: 20 Hz, and 0.021 dB or better from 50 Hz up (dossier A16).
TRIM_CORNER_HZ = 5.0
TRIM_Q = 0.7071067811865476
#: A trim under this is built as a wire rather than a pass of arithmetic
#: that must come back byte-identical. MIDI 64 is the exact centre of a
#: BIPOLAR span since audiocomponents#87, so the detent itself is 0.000 dB;
#: what this floor still covers is the codes either side of it.
FLAT_DB = 0.2
[docs]
class Notch(_component.Component):
"""A notch: one band taken out, and the rest of the signal left alone.
**Controls.** Frequency is where the notch sits. Width is its
bandwidth: low, the notch is a wide scoop; high, it is a few hertz
across and you hear a tone leave without hearing the music change.
Harmonics adds a second notch an octave up, as narrow in hertz as the
first, for hum that comes as a series. Depth is a blend, and at 0 the
class is a wire. Trim is a flat gain. The Effect controls page lists
what the knobs span.
**Response.** DC and the top of the band pass untouched. At low centres
the notch is shallower: there it reduces a hum rather than removing it.
**Timing.** Latency is zero at every setting. Silence in settles to
exact silence out.
**Levels.** Keep the input under -6 dBFS and the defaults and patches
stay off the rails. Trim at its top can still push the output onto the
rails.
**On a board.** The class needs audiodsp's `audiobiquad`, and on a board
without it construction raises `ImportError`.
"""
NAME = 'Notch'
DISPLAY_NAME = 'Notch'
CATEGORIES = ('Filter', 'EQ')
VERSION = '0.0.2'
TIER = _component.AUDIODSP
REQUIRES = ("audiobiquad",)
CAPABILITIES = ()
LATENCY_SAMPLES = 0
#: The design-rate worst case of the per-build bound `tail_samples`
#: reports: 20 Hz at Width 60, the harmonic notch on and the trim at
#: +12 dB, at 48 kHz. The instance's own figure is what a host should
#: read: patch 0's is 187 samples. Before audiocomponents#114 this was a
#: measured 143 360, which a move from a high centre to a low one as the
#: input stopped outlived by up to twice.
TAIL_SAMPLES = 965439
#: The defaults and every patch play the ceiling kit's materials
#: clean at this level; at -3 dBFS, patch 1 rails on
#: a 100 Hz square.
INPUT_CEILING_DBFS = -6
#: Settings that clip by design: the rail check skips them.
CLIPS_AT_TOP = (4,)
MACRO_LABELS = ("Frequency", "Width", "Harmonics", "Depth", "Trim")
MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "TOGGLE",
3: "UNIPOLAR", 4: "BIPOLAR"}
_MACRO_RANGES = (
(20.0, 16000.0, "log"), # 0 Frequency, Hz
(0.5, 32.0, "log"), # 1 Width, as Q; bandwidth is f0/Q
(0.0, 1.0), # 2 Harmonics, 0 = one notch
(0.0, 1.0), # 3 Depth, 0 is a wire
(-12.0, 12.0), # 4 Trim, dB
)
_MACRO_UNITS = {0: "Hz", 4: "dB"}
#: Named for settings, never for products, and every value is
#: `macro_of()` of the setting in the comment beside it. A 7-bit step on
#: a 20 Hz - 16 kHz log span is 5.4 %, so the settings below are what
#: the grid stands for and not what was asked for.
PATCHES = {
0: ("Wide Notch", (74, 11, 0, 127, 64)), # 983 Hz, Q 0.72
1: ("Hum 50", (17, 97, 127, 127, 64)), # 48.9 Hz, Q 12.0, 2
2: ("Hum 60", (21, 97, 127, 127, 64)), # 60.4 Hz, Q 12.0, 2
3: ("Feedback Tamer", (92, 118, 0, 127, 64)), # 2535 Hz, Q 23.8
4: ("Mud Scoop", (51, 27, 0, 76, 64)), # 293 Hz, Q 1.21,
# depth 0.60
5: ("Whistle Kill", (114, 125, 0, 127, 64)), # 8072 Hz, Q 30.0
}
# -- construction --------------------------------------------------
def _build(self, frequency=1000.0, q=0.7071067811865476, harmonics=1,
depth=1.0, trim_db=0.0, patch=None):
"""Three sections, in chain order: the fundamental notch, the
harmonic notch, then the trim.
The trim closes the chain because it is the *output* make-up and
each section writes int16 and clips there
(`audiodsp/src/shared/audiodsp_filter_f32.c:43-51`); a boost applied
before the notch would clip material the notch is about to remove.
The harmonic section is built at every setting and left as a wire
when Harmonics is off - a node cannot be added to a running graph,
and Harmonics is a live macro. It is also left as a wire when 2*f0
would land above the centre ceiling, which is what a rate-honest
harmonic notch does at 22.05 kHz rather than folding.
`harmonics` is a count, 1 or 2; `depth` and `q` are in the units of
their macros and `frequency` and `trim_db` in theirs. Nothing here
adds latency.
"""
rate = self._sample_rate
channels = self._channel_count
def section(mode):
node = audiobiquad.Biquad(mode=mode, frequency=1000.0,
Q=TRIM_Q, gain_db=0.0, mix=0.0,
sample_rate=rate,
channel_count=channels)
return self._own(node, reset=True, deinit=True)
self._fundamental = section(audiobiquad.NOTCH)
self._harmonic = section(audiobiquad.NOTCH)
self._trim = section(audiobiquad.HIGH_SHELF)
upstream = self._source
for node in self._nodes:
node.play(upstream)
upstream = node
self._output = upstream
self._init_macros(
(frequency, q, 0.0 if int(harmonics) <= 1 else 1.0, depth,
trim_db),
patch)
# -- the control laws ----------------------------------------------
def _value(self, index):
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
def _centre(self, hz):
"""A centre frequency, clamped into the band a notch can hold.
`_hz()` clamps at 0.49*Fs, which is where a biquad stops being a
biquad; this clamps lower, at 0.4*Fs, which is where a notch stops
leaving 0.48*Fs alone. Clamps rather than raising, which is the
rate-honesty invariant and the fourth defect section 7 names.
"""
return min(self._hz(hz), self._sample_rate * CENTRE_CEILING)
def _refresh(self):
"""Push all five knobs at once.
One routine rather than five, because every setting here depends on
at least one other: the harmonic section's frequency and Q are the
fundamental's doubled, whether it is in circuit depends on
Harmonics *and* on whether 2*f0 fits under the ceiling, and every
section's `mix` depends on Depth.
"""
asked = self._value(0)
centre = self._centre(asked)
width = min(MAX_Q, max(MIN_Q, self._value(1)))
depth = self._value(3)
trim_db = self._value(4)
stacked = self._macros[2] >= 0.5
self._fundamental.frequency = centre
self._fundamental.Q = width
self._fundamental.mix = depth
harmonic = HARMONIC * centre
reachable = harmonic <= self._sample_rate * CENTRE_CEILING
self._harmonic.frequency = self._centre(harmonic)
self._harmonic.Q = min(MAX_Q, max(MIN_Q, HARMONIC * width))
self._harmonic.mix = depth if (stacked and reachable) else 0.0
self._trim.frequency = self._hz(TRIM_CORNER_HZ)
self._trim.Q = TRIM_Q
self._trim.gain_db = trim_db
# The trim is the notch's make-up, so it goes with the notch: at
# Depth 0 the class is a wire, trim included, which is what Tier 1's
# bypass invariant asks of it.
self._trim.mix = 1.0 if (depth > 0.0 and abs(trim_db) >= FLAT_DB) \
else 0.0
def _apply_macro(self, index, position):
del index, position
self._refresh()
@property
def tail_samples(self):
"""The ring time of *this* build: the sections in circuit, each
bounded from its coefficients in force (`_component.biquad_ring`),
summed down the cascade. The bound holds from any state the
sections can hold, including what the settings before a move left
in them (audiocomponents#114). A section a Depth of 0 or the
Harmonics switch has taken out passes its input through and adds
nothing."""
self._check_live()
return _component.cascade_ring(
[node for node in (self._fundamental, self._harmonic, self._trim)
if node.mix > 0.0])