# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""`NoiseGate` - a noise gate after the Drawmer DS201.
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.
#
# Range follows the DS201's own manual: a gate that closes completely makes
# the noise floor's coming and going more obvious than the noise ever was,
# so a 15 dB Range is often the better setting than -80.
#
# Portability tier: audiodsp. Built on `audiodynamics.Dynamics`, which is
# audiodsp's own module and not a CircuitPython port. The default build is
# one node: a per-sample peak detector, two key filters, a four-stage
# envelope and a VCA, all in C, with Python computing coefficients only at
# construction and on a macro move. There is no lean patch because there is
# nothing to make lean.
#
# Look-ahead buys low-frequency fidelity, not CPU: RaneNote 155 puts the
# smallest useful value at 16 samples (333 us at 48 kHz, enough for 750 Hz
# and above) and the live-sound limit "somewhere around" 2 ms.
#
# `duck=True` costs three more nodes - a `Splitter`, a `Multiply` and a
# `Mixer` - and with them a 32 KB splitter ring and a source-block ceiling
# of 8192 frames, so it is a construction option rather than a knob and a
# plain gate pays none of it. Past about -40 dB the graph subtracts two
# nearly equal 16-bit streams and runs into their own quantisation (dossier
# G7); plain gating has no such limit, its depth is the node's own float.
#
# One thing the dossier asked for and this class does not do: the key band
# sits in front of the peak detector and never comes out - the DS201's L.F.
# control bottoms at 25 Hz, it does not switch off - and a one-pole
# high-pass overshoots a square wave's edges. So a square and a sine of
# equal peak open the gate about 0.63 dB apart where trait G6 asks for 0.5,
# while the bare node with no key filters opens both at exactly the same
# threshold.
import math
VENDOR = "PyDevices"
from . import _component
try:
import audiodynamics
except ImportError: # a stock CircuitPython board, or an old audiodsp
audiodynamics = None
try:
import audioroute
except ImportError:
audioroute = None
try:
import audiomath
except ImportError:
audiomath = None
import array
import audiocore
import audiomixer
#: The gate machine in `audiodsp_dynamics.c:452` is on only when
#: `hold_frames != 0`, and below that the node is the memoryless computer
#: with its `over * 8.0f` slope, no hold and no one-shot. The Hold macro's
#: floor is what keeps it on: 2 ms is 96 frames at 48 kHz and 44 at
#: 22.05 kHz, so no rate reachable here rounds it to zero.
MINIMUM_HOLD_MS = 2.0
#: The one modulator value that inverts exactly: `(a * -32768) >> 15 == -a`
#: on signed int16 (`audiodsp_multiply.c:38`). +32767 does not - it is the
#: WIRE planted fault, 32767/32768 - which is why a built duck graph cannot
#: be switched back to a plain gate by levels alone.
INVERTING_LEVEL = -32768
#: Range is a depth, and 0 dB of ducking is no ducking. `20*log10(0)` is not
#: a number, so the duck's blend gain floors here instead; -120 dB leaves the
#: dry path a wire to well under an LSB.
SILENT_DB = -120.0
#: ln(4 * 65536): a one-pole state at four times full scale falls under
#: half an int16 LSB after this many time constants.
_KEY_RING_TIME_CONSTANTS = math.log(4.0 * 65536.0)
def _key_pole_ring(hz, sample_rate):
"""Frames one of the key band's poles at `hz` rings for: its state
falls by exp(-2 pi f / fs) a frame (`audiodsp_dynamics.c`'s sidechain
coefficients), plus a frame for single precision."""
if hz <= 0.0:
return 0
return int(math.ceil(_KEY_RING_TIME_CONSTANTS * sample_rate
/ (2.0 * math.pi * hz))) + 1
[docs]
class NoiseGate(_component.Component):
"""A noise gate after the Drawmer DS201: below the Threshold your signal
is held down, and above it the gate opens and lets it through.
**Controls.** Threshold is the level where the gate opens. Range is how
far the closed gate holds the signal down, with 0 dB where the output
is the input; it is a fixed depth, however far under the Threshold the
signal falls. A crossing opens the gate over the Attack, holds it open
for the Hold, and only then lets it fall over the Release. A long Hold
with a short Release chops a reverb's tail off square: that is the
gated-reverb snare. Once a crossing opens the gate, the gate runs
through its Attack, Hold and Release even if the signal drops away at
once. The Effect controls page lists what the knobs span.
**The key never touches the sound.** The gate listens through its own
band, with Key Low and Key High setting its edges, the top held just
under half the sample rate, so a gate on a tom can ignore the hi-hat
above it and the kick below it. Key Listen puts that band on the output
in place of the audio, so you can hear what you are tuning.
**Options.** Give the class `key=` another stream and that stream opens
and closes the gate, which is how one sound gates another.
`lookahead_ms` lets the gate read ahead of the audio, up to 50 ms, so it
is already open when a transient arrives; each millisecond of look-ahead
is a millisecond of latency. `duck=True` turns the gate inside out, for
voice-overs: below the Threshold your signal passes untouched, and above
it Range pushes it down. A duck's depth is honest to about -40 dB, and
past that it falls short: Range -80 measures about -77 dB.
**Levels.** With the gate open, the output is your signal at its own
level. Silence in is silence out, and a mono source gets the same gate
as stereo. The first opening after construction or `reset()` fades in
from silence over the Attack, even at Range 0 dB.
**Timing.** Latency is zero unless you set `lookahead_ms`. The tail is
zero, except while Key Listen is on, when it covers the key band's ring;
with `key=` the key decides, and the tail is `None`.
**The detector reads peaks.** A sine opens the gate at a Threshold
about 3 dB higher than a square of the same loudness, because its peaks
are higher. A square of the same peak as a sine opens it about 0.63 dB
higher than the sine, because the key band rings on the square's edges.
**On a board.** The class needs audiodsp's `audiodynamics`,
`audioroute` and `audiomath`, and on a board without any of them
construction raises `ImportError`.
"""
NAME = 'NoiseGate'
DISPLAY_NAME = 'Noise Gate'
CATEGORIES = ('Dynamics',)
VERSION = '0.1.0'
TIER = _component.AUDIODSP
#: `audiodynamics` first, because that is the one the default build
#: needs and the one a stock board's ImportError should name.
#: `audioroute` and `audiomath` are built only by `duck=True`.
REQUIRES = ("audiodynamics", "audioroute", "audiomath")
#: The DS201 has no tempo control and neither has this: nothing here
#: reads `self._transport()` (dossier D10).
CAPABILITIES = ()
#: The default build. `lookahead_ms` moves both of these, and the
#: properties below report the instance rather than the class.
LATENCY_SAMPLES = 0
TAIL_SAMPLES = 0
MACRO_LABELS = ("Threshold", "Attack", "Hold", "Release", "Range",
"Key Low", "Key High", "Key Listen")
MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR",
3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR",
6: "UNIPOLAR", 7: "TOGGLE"}
#: Range descends on purpose: 0 dB at the bottom of the knob is a wire,
#: and the top is the deepest cut, which is how the panel reads.
_MACRO_RANGES = (
(-80.0, 0.0), # 0 Threshold, dBFS
(0.01, 1000.0, "log"), # 1 Attack, ms
(MINIMUM_HOLD_MS, 2000.0, "log"), # 2 Hold, ms
(2.0, 4000.0, "log"), # 3 Release, ms
(0.0, -80.0), # 4 Range, dB of attenuation when shut
(25.0, 4000.0, "log"), # 5 Key Low, Hz
(250.0, 35000.0, "log"), # 6 Key High, Hz (clamped by _hz)
(0.0, 1.0), # 7 Key Listen
)
_MACRO_UNITS = {
0: "dBFS", 1: "ms", 2: "ms", 3: "ms", 4: "dB", 5: "Hz", 6: "Hz",
}
PATCHES = {
0: ("Default", (64, 51, 59, 77, 127, 0, 113, 0)),
1: ("Tom Tighten", (79, 43, 63, 68, 64, 29, 71, 0)),
2: ("Gated Reverb", (87, 33, 97, 38, 127, 0, 113, 0)),
3: ("Vocal Breath Trim", (56, 63, 75, 84, 19, 22, 99, 0)),
4: ("Amp Hiss", (48, 58, 72, 89, 127, 110, 89, 0)),
5: ("Drum Bleed", (76, 43, 50, 62, 79, 35, 36, 0)),
}
THRESHOLD, ATTACK, HOLD, RELEASE, RANGE, KEY_LOW, KEY_HIGH, \
KEY_LISTEN = range(8)
#: `audiodsp_dynamics.h:104`. The node clamps for itself; the class
#: clamps too so `latency_samples` reports what the node will do.
MAX_LOOKAHEAD_MS = 50.0
def _build(self, threshold_db=-40.0, attack_ms=1.0, hold_ms=50.0,
release_ms=200.0, range_db=-80.0, key_low_hz=25.0,
key_high_hz=20000.0, key_listen=False, duck=False,
lookahead_ms=0.0, key_poles=1, key=None, patch=None):
"""Build the gate.
`duck` and `lookahead_ms` are construction options rather than
macros, and the dossier's section 6 says why. `key` is a borrowed
second source for the detector - the DS201's Ext jack - which this
class never owns, resets or deinitialises; a key that runs dry
before the audio does starves the node into silence
(`audiodynamics/Dynamics.c:255-259`). `key_poles` is 1 or 2 poles on
each end of the key band, measured upstream at 5.29 and
10.31 dB/octave.
"""
lookahead_ms = min(max(float(lookahead_ms), 0.0),
self.MAX_LOOKAHEAD_MS)
#: The node's own conversion, `audiodsp_dynamics.c:126-127`, so the
#: reported latency is the frame count the C will actually hold.
self._latency = int(lookahead_ms * self._sample_rate / 1000.0)
self._duck = bool(duck)
if self._duck:
# See the note in `compressor.py`: `reset=False` because a
# ring cannot be rewound, but the Splitter can be released
# (audiodsp#58) and `getattr` skips the call on an audiodsp that
# has none.
self._split = self._own(
audioroute.Splitter(source=self._source, taps=2),
reset=False)
gate_input = self._own(self._split.tap(0))
dry = self._own(self._split.tap(1))
else:
self._split = None
gate_input = self._source
dry = None
self._dyn = self._own(audiodynamics.Dynamics(
audiodynamics.DYN_GATE,
sample_rate=self._sample_rate,
channel_count=self._channel_count,
threshold_db=threshold_db,
attack_ms=attack_ms,
release_ms=release_ms,
hold_ms=max(float(hold_ms), MINIMUM_HOLD_MS),
depth_db=range_db if not self._duck else -80.0,
sidechain_hz=self._hz(key_low_hz),
sidechain_lp_hz=self._hz(key_high_hz),
sidechain_poles=2 if int(key_poles) >= 2 else 1,
lookahead_ms=lookahead_ms))
self._dyn.play(gate_input)
self._key_poles = 2 if int(key_poles) >= 2 else 1
self._external_key = key is not None
if key is not None:
self._dyn.key(key)
if self._duck:
# x - b.g.x, with b in the node's own makeup_gain so the depth
# is a float rather than the Mixer's Q15 voice level.
self._modulator = self._own(audiocore.RawSample(
array.array("h", [INVERTING_LEVEL] * self._channel_count),
sample_rate=self._sample_rate,
channel_count=self._channel_count))
self._invert = self._own(audiomath.Multiply(
mix=1.0, sample_rate=self._sample_rate,
channel_count=self._channel_count))
self._invert.play(self._dyn)
self._invert.modulate(self._modulator)
self._dry = dry
self._mixer = self._own(audiomixer.Mixer(
voice_count=2, **self._pcm()), reset=self._reset_mixer)
self._wire_mixer()
self._output = self._mixer
else:
self._dry = None
self._modulator = self._invert = self._mixer = None
self._output = self._dyn
self._init_macros((threshold_db, attack_ms,
max(float(hold_ms), MINIMUM_HOLD_MS), release_ms,
range_db, key_low_hz, key_high_hz,
1.0 if key_listen else 0.0), patch)
def _wire_mixer(self):
self._mixer.voice[0].play(self._dry)
self._mixer.voice[1].play(self._invert)
def _reset_mixer(self):
"""Clear the duck's summing mixer and hand its voices back.
Upstream CircuitPython's `Mixer.reset_buffer` **stops** its voices
(`audiodsp/src/audiomixer/MixerVoice.c:91`, which says so in as many
words), and the patched CircuitPython build carries the upstream
one: measured on `bin/circuitpython-effects`, a mixer playing
a sample reads 8000 LSB before `audiocore.reset_buffer` and 0 after
it, for good. audiodsp's own `audiomixer` does not do that - the
same probe reads 8000 both sides on CPython and on desktop
MicroPython - so a duck build reset through the base class's walk
would go silent on one interpreter of three and nowhere else.
Re-playing the voices costs nothing on the builds that never
needed it.
"""
audiocore.reset_buffer(self._mixer)
self._wire_mixer()
# -- the live surface ---------------------------------------------
@property
def latency_samples(self):
"""The look-ahead, in frames, and nothing else.
Overridden because `_component` keeps `LATENCY_SAMPLES` on the
class, and `lookahead_ms` is a per-instance choice: two gates in one
graph may legitimately report different figures.
"""
self._check_live()
return self._latency
@property
def tail_samples(self):
"""The same number, with Key Listen off: what is left to come out
after the input goes quiet is exactly the audio held in the
look-ahead buffer. Nothing here has a feedback path or a delay line.
With Key Listen on, the output is the key band, and its one-pole
filters ring after the input stops (audiocomponents#114: 2 048
frames at the default Key Low). Each pole adds the frames its state
takes to fall from four times full scale - the most a high-pass
hands the next stage - to under half an LSB. With an external `key=`
the band follows the key, not the input, so there is no bound:
`None`.
"""
self._check_live()
if self._macros[self.KEY_LISTEN] < 0.5:
return self._latency
if self._external_key:
return None
ring = (_key_pole_ring(self._hz(self._value_of(self.KEY_LOW)),
self._sample_rate)
+ _key_pole_ring(self._hz(self._value_of(self.KEY_HIGH)),
self._sample_rate))
return self._latency + self._key_poles * ring
def _value_of(self, index):
return _component.macro_value(self._MACRO_RANGES[index],
self._macros[index])
# -- macros -------------------------------------------------------
def _apply_macro(self, index, position):
value = _component.macro_value(self._MACRO_RANGES[index], position)
if index == self.THRESHOLD:
self._dyn.set(threshold_db=value)
elif index == self.ATTACK:
self._dyn.set(attack_ms=value)
elif index == self.HOLD:
self._dyn.set(hold_ms=value)
elif index == self.RELEASE:
self._dyn.set(release_ms=value)
elif index == self.RANGE:
self._apply_range(value)
elif index == self.KEY_LOW:
self._dyn.set(sidechain_hz=self._hz(value))
elif index == self.KEY_HIGH:
self._dyn.set(sidechain_lp_hz=self._hz(value))
else:
self._apply_key_listen(value >= 0.5)
def _apply_range(self, range_db):
"""Range is the node's own depth when gating, and the blend gain of
the subtracted branch when ducking."""
if not self._duck:
self._dyn.set(depth_db=range_db)
return
blend = 1.0 - (10.0 ** (range_db / 20.0))
self._dyn.set(makeup_db=(20.0 * math.log10(blend))
if blend > 1e-6 else SILENT_DB)
def _apply_key_listen(self, listening):
self._dyn.set(key_listen=1.0 if listening else 0.0)
if self._duck:
# Key Listen replaces the output, so the dry half of the duck
# comes out of the sum; what is left is the key band with its
# sign flipped, which is the band and not a mix.
self._mixer.voice[0].level = 0.0 if listening else 1.0