audioeffects.overdrive
Overdrive - a Tube Screamer-shaped boost: dry plus a clipped shelf.
The player’s text is the class docstring; the CLAIMS table in the
class’s test file ties its claim sentences to tests.
- audioeffects.overdrive.CURVE_VOLTS = 0.347334239
Volts at the table’s full scale. The table is normalised to its own extreme so it fills int16 (audiocomponents#77) and this carries the scale back out in
post_gain.
- audioeffects.overdrive.OVERSAMPLE_FLOOR_HZ = 192000.0
The clip stage runs at or above this internal rate where it can. The factor follows the rate rather than being a constant the 48 kHz bench happened to be right about: every doubling is worth 11-16 dB of alias floor, measured (pack section 14,
reach).
- audioeffects.overdrive.ALIAS_DEFAULT_DB = -70.0
at the constructor default
- audioeffects.overdrive.ALIAS_PATCH_DB = -50.0
at every shipped patch, as shipped
- audioeffects.overdrive.ALIAS_SURFACE_DB = -40.0
anywhere on the macro surface
- audioeffects.overdrive.ALIAS_OVERSAMPLE_COST_DB = 20.0
what the shipped oversampling is worth, in dB of wet alias floor, against the same class run at the base rate - at every surface position where the clip stage is in circuit, which is Drive above its floor and Body below the top of its travel. Measured over the pack’s 54 positions at three rates: 47 of 52 gradable cells clear this at 48 and 44.1 kHz and all 52 clear it at 22.05 kHz; the worst cell that carries the clause is +20.520 dB (
body=360, 48 kHz). The five cells outside the region are worth 0.81 to 15.32 dB and are named in the class docstring with their numbers.This is the clause that makes
BaseRatea guard rather than a diagnostic. Under the three absolute bars alone it was healthy at 17 of 54 positions (audit 3 (p)2, ruling (i)) - not because switching the oversampling off removed nothing there, which was the old defence and is false at twelve of them, but because the class has 30 to 40 dB of margin at those settings. Under T7e it is red at every position the clause is claimed over, because its own cost is 0 dB by construction.- Type:
T7e, added by the third fix round
- audioeffects.overdrive.INPUT_CEILING_DBFS = -1.0
The input ceiling, stated because the class adds a clipped shelf to a dry note at unity and so has to run out of headroom somewhere (audit 3 ruling (o)). Sine into the output’s int16, 100 Hz to 2 kHz:
-1 dBFS at every shipped patch. Patch 7
Edge Boostis the one that reaches the rail at all, 4 samples of 9600 at 0 dBFS / 400 Hz.-6 dBFS anywhere on the macro surface. Drive max with Level max and Tone open rails at -3 dBFS (570 of 9600 at 700 Hz).
The 30 Hz output pole bought most of this: before it, patch 7 railed at -3 dBFS at 700 Hz and 1 kHz, because Symmetry’s offset rode on the peaks. The standing offset is now blocked and only the signal itself reaches the rail.
- audioeffects.overdrive.shipped_oversample(sample_rate)[source]
The factor this rate ships with: x4 at 48 kHz and up, x8 below it.
Never below x4, because x2’s own node floor at 1010 Hz is -56.4 dB and fails T7 before the class is in it; never above x8, because the node stops there and because the cost is real - x8 at 48 kHz is +0.799 ms on the P4 and +1.408 ms on the S3 per block, which is the whole of why the budget’s rate keeps x4.
So the rule is exactly: x8 at every rate below 48 kHz, x4 at 48 kHz and above. The 192 kHz floor is reached at 48 kHz and above only. Every rate under 24 kHz leaves the internal rate under that floor and takes x8 anyway because x8 is all there is: 22.05 kHz runs 176.4 kHz internally, and 16 kHz - outside this program’s three rates, but reachable - runs 128 kHz and reads -50.451 dB at Drive max on the wet branch, -41.732 dB at the worst macro corner. (The -56.9 dB the second fix round quoted here was a mixed reading, with the dry note diluting the floor by about 6 dB.) The ceiling is the node’s:
AUDIODSP_SHAPER_MAX_OVERSAMPLEis 8, and audiodsp#104 is the ask. The floor is a target, not a guarantee, and the class’s bars areALIAS_DEFAULT_DB/ALIAS_PATCH_DB/ALIAS_SURFACE_DB/ALIAS_OVERSAMPLE_COST_DB.
- audioeffects.overdrive.DC_BLOCK_HZ = 30.0
The output capacitor, third fix round. A TS is DC-coupled inside and AC-coupled at the jack; the class had the first half only, so Symmetry’s operating-point offset walked straight out of the shaper and stood on the output for ever - +4461 LSB at shipped patch 6 into digital silence (audit 3 ruling (n)). This pole sits after the shaper, on the clip branch only, so the dry note is still a byte-exact copy. 30 Hz because the clip branch is already high-passed at Body (360 Hz at its lowest), so the pole takes nothing a player hears, and because it has to settle: at 20 Hz the offset was still nonzero at frame 16383, at 30 Hz it is exactly zero from frame 2965.
- audioeffects.overdrive.OFFSET_LINE = array('h', [-32767, 32767])
The offset is also taken off before the pole, so the pole holds a few LSB rather than thousands. Its float32 recursion cannot step a large constant down by less than one rounding of it: fed shipped patch 6’s offset at 44.1 kHz it came to rest at -0.7 LSB rather than on zero, which the Level stage’s integer mixer floors to a standing -1 LSB for ever, and a burst of signal leaves it somewhere else in that band. The node that takes it off is a second
Waveshaperat x1 on a straight line: a two-point curve at apost_gainof 32768 / 32767 playsx + biasback exactly, to the LSB, for every int16x, so it adds no rounding to the clip branch and no latency.
- audioeffects.overdrive.DC_SETTLE_BLOCKS = 64
How many blocks
_settle_dcwill pull before it gives up. The pole needs about 3000 frames at 48 kHz; 64 blocks is 16384 frames, five times that.
- audioeffects.overdrive.DC_QUIET_FRAMES = 512
The length of the zero sample the charge is pulled through, in frames. One block, because the shaper’s
play()has noloopand the charge re-plays it per pull; 2 KB of stereo int16 that only the charge holds.
- class audioeffects.overdrive.Overdrive(source, *options, **keywords)[source]
Bases:
ComponentA Tube Screamer-shaped overdrive: your note at unity, with a high-passed, clipped copy added on top.
Controls. Drive is how hard the copy is clipped, and even at its floor the pedal is not clean. Tone is a low-pass after the clip. Body is the corner of the high-pass in front of the clip, so it sets how much bass reaches it. Ceiling is how tall the clipped copy stands. Symmetry biases the clip off centre and brings in even harmonics. Level is the output stage. Mix is how much clipped signal is added to your note; it does not turn the note down. The Effect controls page lists what the knobs span.
Switching. Mix at 0 takes the pedal out of circuit and hands back your signal byte for byte. Leaving 0 switches the pedal on fresh, rather than replaying what it held when it went off. At Mix 1 with Level at 0 the pedal is silent.
Sound. At the defaults, bass comes through cleaner than the mids, as the high-pass in front of the clip makes it; at the bottom of Body, or on a square, that reverses. With Symmetry centred the dirt rises with Drive; off centre it peaks partway up the knob. The clip runs oversampled, so aliasing stays at least 40 dB under the note anywhere on the panel, up to a full-scale input.
Timing. Latency is zero at every setting. Silence in is silence out at every shipped patch.
Levels. Keep the input under -1 dBFS and the shipped patches stay off the rails; anywhere on the panel, keep it under -6 dBFS.
On a board. The class needs audiodsp’s
audioshaper,audiobiquadandaudioroute, and on a board without them construction raisesImportError.- 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 = 'Overdrive'
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.
CAPABILITIESnames"tempo_sync"if and only if the class readsself._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.
- ALIAS_DEFAULT_DB = -70.0
T7’s bars, so a test or a probe reads them from one place.
- MACRO_LABELS = ('Drive', 'Tone', 'Level', 'Mix', 'Body', 'Ceiling', 'Symmetry')
Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.
- reset()[source]
Clear every node and restore patch 0, then arm the graph as
_builddoes, so a reset is a fresh instance (no block primed through the chain before it was cleared plays after it).
- 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_aroundthen 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.