audioeffects.dynamiceq

DynamicEQ - one equaliser band that only moves when there is something in it.

The player’s text is the class docstring; the CLAIMS table in the class’s test file ties its claim sentences to tests.

class audioeffects.dynamiceq.DynamicEQ(source, *options, **keywords)[source]

Bases: Component

One EQ band that only moves when there is something in it.

What it does. You dial in a bell the ordinary way, with Frequency and Width. It does nothing until the sound in that band crosses Threshold, and then it cuts the band as far as Ratio says. Everything outside the band is left as it was.

Idle, it is a wire. Below the threshold the band and its complement add back to the input within 0.05 dB from 100 Hz to 12 kHz, and an impulse comes out at its own height.

The controls. Frequency places the band, Width is its Q, Threshold is where the cut starts, Ratio is how far it cuts, and Attack and Release are how fast it moves. The Effect controls page lists what the knobs span and the patches.

The law. At the default, a 3 kHz tone follows the compressor law within 1 dB, and across the bell the cut follows the closed form within 0.5 dB. Two octaves down nothing moves by as much as 0.2 dB, idle or working.

Mix is the Range. Mix also caps the deepest cut: at 0.75 the band can move by at most 12 dB, and at 1 there is no limit. Across Mix the cut follows that blend within 0.2 dB, and out of band nothing moves. Mix 0 is the source byte for byte, at full scale and at 48 kHz, 44.1 kHz and 22.05 kHz. Bringing Mix back after silence plays nothing.

Listen. Listen solos the band being processed.

Expand. Build it with expand=True and it cuts the band when the band is quiet instead: over the threshold it is a wire within 0.1 dB, and 16 dB under it the band drops by more than 20 dB.

Sample rate and mono. The law holds within 0.35 dB at 48 kHz, 44.1 kHz and 22.05 kHz, and in mono. A Frequency above 0.4 of the running rate is built there, and frequency_hz says what you got.

Latency and tail. It adds no latency at any setting. The tail reaches exact zero inside tail_samples, after a knob move too.

It needs audiobiquad, audiodynamics and audioroute, so a stock CircuitPython board can’t run it.

LAZY_BUILD = True

Construction arms the voices on silence (Component._play_voice), so a Mix 0 set before the first pull hands out the source whole.

NAME = 'DynamicEQ'

The stable provider name audioeffects.create() discovers.

TIER = 'audiodsp'

STOCK or AUDIODSP, with REQUIRES naming the audiodsp-own modules an AUDIODSP class needs.

Type:

roadmap §3

CAPABILITIES = ()

attack and release are absolute milliseconds and nothing on this class is measured in bars, so self._transport() is never read.

Type:

(), and the dossier’s reason (D10)

LATENCY_SAMPLES = 0

Zero at every setting. Both branches are IIR and no look-ahead is offered, so there is no option whose milliseconds need naming.

TAIL_SAMPLES = 0

the ring-down is the pole pair’s, so it depends on the rate and on where Frequency and Width are.

After a reset, a rejoin or a control move the detectors can leave the output about 1,000 LSB from an untouched copy for 5 to 20 blocks: a re-attack, which tail_samples does not bound. See “Detector and coupling state” in docs/reference/component-api.md.

Type:

Overridden as a property below

MACRO_LABELS = ('Frequency', 'Width', 'Threshold', 'Ratio', 'Attack', 'Release', 'Mix', 'Listen')

Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.

PATCHES = {0: ('Wide Band', (93, 55, 64, 59, 55, 66, 127, 0)), 1: ('Boxiness Control', (52, 64, 76, 47, 85, 82, 127, 0)), 2: ('Harshness Control', (94, 72, 68, 59, 42, 60, 127, 0)), 3: ('Low End Tamer', (20, 35, 85, 59, 97, 94, 127, 0)), 4: ('Sibilance', (110, 83, 64, 88, 13, 50, 127, 0)), 5: ('Half Measure', (93, 28, 55, 76, 72, 88, 64, 0))}

Patch 0 is the constructor’s defaults on the 0-127 grid; tests/test_cpython_effects_dynamiceq.py holds it to them span by span rather than to a hand-copied list.

WALKS_TO_BYPASS = True

A class sets this when its graph, at Mix 0, walks to the source it routes around: its mixer levels to the dry alone, on ramped mixers (ramp_levels). _route_around then lets the port switch once the walk has landed rather than at once. Mix 0 is still the source, byte for byte, from then on.

reset()[source]

Clear every node and restore patch 0, then hand the voices their sources at patch 0’s levels, as _build does. The walk used to re-play them at the outgoing patch’s levels, before patch 0 went in, so the levels moved after the gates had opened and landed late, a few LSB (up to 70 here) off a fresh instance for the first blocks.

property expand

Whether the band is cut when it goes under the threshold (True) rather than over it. Fixed at construction; see the class docstring for why it is not a macro.

property frequency_hz

The centre actually applied, after the rate clamp. It can sit below what macro(0) reports - that is the clamp doing its job at a lower sample rate.

property range_db

The deepest the band can ever be moved, in dB, at this Mix.

-20*log10(1 - Mix), and inf at Mix 1. This is the Range control S6 names; it is not a separate macro because in an exactly complementary split a dry/wet blend and a band-range limit are the same arithmetic (dossier T6).

property tail_samples

How long the split rings, in samples at this rate.

The only memory in this class is the two biquads’, and they share a denominator, so one pole pair sets it: the bound is read off the coefficients in force (_component.biquad_ring) and holds from any state the sections can hold, including what the settings before a move left in them. The old figure, 4 periods of Q / f0 from a burst at fixed settings, was short after a large move down (audiocomponents#114). The float state is flushed to exact zero below 1e-20, so the tail really does arrive.

The detector holds no audio: audiodynamics multiplies its input by a gain, so silence in is silence out whatever the release is doing, and the release therefore adds nothing here.

gain_reduction_db()[source]

What the gain cell did to the last frame of the band, in dB.

The cell’s own number, before the Mix blend, so it is the detector’s reading and not what reached the output. At blend m the output’s move at the centre is 20*log10((1 - m) + m * 10**(cell/20)).