audioeffects.exciter

Exciter - dry plus a high-passed harmonic branch.

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

audioeffects.exciter.DC_BLOCK_HZ = 30.0

The output coupling pole, third fix round. Far below Tune’s own floor (2 kHz), so it takes nothing this class makes and removes the rectification offset the asymmetric diode leaves on the output.

audioeffects.exciter.INPUT_CEILING_DBFS = -3.0

The input ceiling, stated because this class adds a harmonic branch to a dry note at unity and its Output macro spans -24 to 0 dB, so it only attenuates: there is no headroom control and there never was (audit 3 (p)4, ruling (o)). Measured with sines at 1, 3, 5.5 and 8 kHz over every shipped patch and the Harmonics-max / Mix-max corner: the first railed sample anywhere is at -2 dBFS (patch 6 at 5.5 kHz, 250 of 4 800; the corner, 150 of 4 800), and -3 dBFS is clean everywhere. The 30 Hz pole bought some of that back - the offset it removes was riding on the peaks - and the rest is the class’s own gain structure.

audioeffects.exciter.ALIAS_OVERSAMPLE_COST_DB = 15.0

What the shipped x4 is worth against x1, in dB of worst in-band line, wherever Tune puts the sidechain high enough to fold - which is Tune MIDI 64 and up, 1915 Hz at 48 kHz. Under the absolute -60 dB bar alone BaseRate was healthy at 21 of 276 positions, all of them the bottom of the Tune macro and shipped patch 3 (audit 3 (p)3, ruling (i)): not because the oversampling is idle there but because a sidechain at 600 Hz makes nothing high enough to alias. Measured over the macro at 48 kHz with the row’s own probe rule, the cost is +19.1 to +46.2 dB from MIDI 56 up and -2.2 to +7.1 dB below it. x1’s own cost is 0 dB by construction, so it is red at every position the clause is claimed over.

audioeffects.exciter.OVERSAMPLE_CLAUSE_TUNE_HZ = 1900.0

the sidechain corner above which the class makes enough high harmonics for the factor to matter.

Type:

Where that clause is claimed

audioeffects.exciter.HARMONICS_SPAN_DB = 14.0

Volts the Harmonics macro puts across the 1N914 at its top, in dB over 0 dBFS = 1 V. 14 dB, not 24 since 2026-09-17: measured on this class’s own curve, the top ten of those twenty-four decibels buy 1.76 dB of h2 at -6 dBFS (h2 -10.107 at +14 dB against -8.345 at +24) and cost 6.7 dB of alias (T7’s worst in-scope cell -63.74 at +14 against -57.05 at +24), because past the knee the diode’s shape has stopped changing while the time it takes to cross the knee keeps shrinking, and a shorter corner is more fold. See the pack, S13.

audioeffects.exciter.TRANSIENT_ATTACK_DB = 6.0

transient’s onset gain and how long it lasts. +6 dB over 8 ms, not +12 dB over 50 since 2026-09-17. T4 is a claim transient makes too (dossier S3’s Char. column), and at +12 dB / 50 ms the wet sat at 72.2-76.0 % of the dry at Mix maximum on T4’s own material, read over the SETTLED half where nothing is a transient any more - over T4’s 20-70 % ceiling (audiocomponents#72, second audit item 3). Shortening the boost rather than only lowering it keeps the onset and drops what follows it: 61.72 % worst settled now, and T5’s shape is stronger than before, 12.75 dB of onset emphasis at the frozen 5 kHz / -18 dBFS against a 6 dB bar, with classic reading 0.00 dB as the control.

sustain_gain_db cannot carry the emphasis on its own: it acts on the DECAY, not on the steady state (audiodsp_dynamics.c:755-759 - the sign of fast-minus-slow picks which gain applies), so at attack 0 dB the character is a wire on a sustained tone (0.00 dB of emphasis, measured). The decay time is not a trait: T5’s tau clause is frozen as DISCONFIRMED, so what the boost’s length owes is disclosure, which is this.

transient_fast_release_ms costs nothing: the four transient time constants are config fields whose defaults are the literals the node used before they were fields (audiodsp_dynamics.c:48-53), so a node that sets one computes exactly what a node that sets none computes. The budget keeps the palette’s bare Dynamics row.

audioeffects.exciter.MIXER_BUFFER_BYTES = 1024

The blend mixer’s buffer, per channel. Mixer._render_size is buffer_size // 2 // 4 * 4 BYTES, so the 1024 this class shipped handed back 128 stereo frames and everything behind it was pulled TWICE per 256-frame block — including, on transient, an audiodynamics.Dynamics whose own output block is 256 frames by construction (audiodsp_dynamics.h:56, “the effects library’s latency assumptions — notably the Splitter ring’s depth — are written around it”). The board’s own rows are where the suspicion comes from: adding the Dynamics cost this class 0.537 ms on the P4 and 1.234 ms on the S3 where the palette prices it at 0.495 / 0.985 — 9 % over on the P4 and 27 % over on the S3. 1024 * channel_count is one pull per block at either channel count, which is what Distortion already does (_pcm_mixer), and the three classes that missed their budget on these boards are three of the four that handed back 128 frames. The second board pass measured the 256-frame graph: it is worth 3.4 / 3.5 points on `classic` and 3.2 / 4.6 on `transient`, so the block was most of the P4’s miss and about half the S3’s. What the `Dynamics` costs over its row — 22 % on the S3 — is not the block and is still unexplained.

class audioeffects.exciter.Exciter(source, *options, **keywords)[source]

Bases: Component

A harmonic exciter: your note at unity, with a high-passed copy, clipped on a single side, added for air and edge.

Controls. Tune is the corner of the high-pass that feeds the clip, so it picks which part of the note gets brighter. Harmonics drives the copy into the clip, from 0 to +14 dB. Mix is how much of the copy is added; it does not turn the note down. Character picks classic, a fixed clip, or transient, which drives the copy 6 dB harder for the first 8 ms of each onset. Output trims the whole effect, the note and the copy together, so the balance between them does not move with it, and it only turns down. The Effect controls page lists what the knobs span.

Switching. Mix at 0, with Output at 0 dB, hands back your signal untouched. Bringing Mix back up switches the copy on fresh, rather than replaying what it held when it went off.

Sound. The copy’s high-pass is second order at every rate, because Tune is held under a seventh of the sample rate: at 22.05 kHz it tops out at 3150 Hz. The clip is one-sided, so the copy carries more second harmonic than third, and its second harmonic rises with level. At full Mix the copy stays under the note. The clip runs oversampled, so at 48 kHz aliasing stays 60 dB under the copy at the defaults and with Harmonics at the top, up to the input ceiling.

Timing. Latency is zero at every setting. Silence in is silence out at every shipped patch, and the tail falls to zero within 4096 frames.

Levels. Keep the input under -3 dBFS and nothing rails, on any shipped patch or with Harmonics and Mix at the top; at -2 dBFS it can. No shipped patch leaves a DC offset on its output while it plays.

On a board. The class needs audiodsp’s audioshaper, audiobiquad, audioroute and audiodynamics, and on a board without them construction raises ImportError.

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 = 'Exciter'

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 = ()

The contract’s static reads. CAPABILITIES names "tempo_sync" if and only if the class reads self._transport().

TAIL_SAMPLES = 4096

After a reset, a rejoin or a control move a few LSB of float residue can remain in the output beside an untouched copy, past tail_samples. See “Detector and coupling state” in docs/reference/component-api.md.

MACRO_LABELS = ('Tune', 'Harmonics', 'Mix', 'Character', 'Output')

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

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 arm the graph as _build does, so a reset is a fresh instance (no block primed through the chain before it was cleared plays after it).