audioeffects.distortion

Distortion - the ProCo Rat, with a Boss pedal as a second character.

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

audioeffects.distortion.LEVEL_LINE = array('h', [-32767, 32767])

The Rat’s leg levels are set in float, not in the leg mixer. They are below unity and sit ahead of up to 67 dB of gain, and an integer mixer voice floors x * level, which is half an LSB of DC on every sample that is not a multiple of the step: at Distortion max a 4 LSB input stood at -0.070 of the output’s full scale. A Waveshaper at x1 on this two-point straight line, at a post_gain of level * LEVEL_GAIN, rounds to the nearest LSB instead, so it adds no bias; at a level of 1 it is exact.

audioeffects.distortion.FILTER_R0_SCOOP = 6670.646007456111

The series resistance that puts the Filter pot’s own top exactly on the DS-1’s post-clip corner. On scoop the class used to read the Rat’s FILTER_R0 and then take max(fc, CLIP_LP_HZ), which pinned MIDI 8 to 127 on one section - 120 positions that did nothing - and made MIDI 1 to 6 brighter than MIDI 0, +5.68 dB at MIDI 1 (audit 3 (p)3). With this the corner starts at CLIP_LP_HZ at MIDI 0 and falls monotonically to 452 Hz at MIDI 127, so Filter 0 is byte-for-byte the stock DS-1 and every position above it moves.

audioeffects.distortion.OUT_HP_HZ = 20.0

The DS-1’s output coupling capacitor, which the first build left out. Waveshaper.bias is Asymmetry, and a biased table has a non-zero output at zero input: the shipped scoop patches put -6.8 to -25.1 dBFS of DC on the output with a silent source (patch 8 +0.456 of full scale), which is headroom gone and a thump on engage. 0.047 uF into the 100 k volume pot is about 34 Hz; 20 Hz is the quieter end of that and costs 0.17 dB at 100 Hz, where SC1 and SC5 are read.

audioeffects.distortion.CLICK_DELAY_SAMPLES = {1: 0, 2: 1, 4: 2, 8: 2}

The measured integer-onset click delay per oversampling factor, which is what latency_samples reports at full wet. audioshaper. GROUP_DELAY_SAMPLES is the half-band’s group delay (0 / 2.2 / 3.3 / 3.9); the onset of a symmetric response arrives before its centroid, so these are the numbers a click actually reads.

audioeffects.distortion.OVERSAMPLE_FLOOR_HZ = 176400.0

The internal rate the clipper wants. Below it the decimator’s fold is what A1 reads instead of the class; above it nothing improves and the node costs twice. 48 kHz and 44.1 kHz reach it at x4; 22.05 kHz does not, and x8 there buys 5.1 dB at 1010 Hz and 11.1 dB at 3700 Hz for less of the block than x4 costs at 48 kHz, because the block is twice as long.

audioeffects.distortion.shipped_oversample(sample_rate)[source]

The factor this rate ships with: x4 at 48 and 44.1 kHz, x8 at 22.05.

Never below x4 - x2 misses A1 at every rate - and never above x8, because the node stops there and because above OVERSAMPLE_FLOOR_HZ the floor is no longer the fold. At 48 kHz x8 moves maximum-Distortion 1010 Hz from -58.51 to -58.93 dB and 3700 Hz from -48.11 to -48.12 for +0.784 / +1.408 ms, which is why it is not taken there.

class audioeffects.distortion.Distortion(source, *options, **keywords)[source]

Bases: Component

A hard-clipping distortion with a pair of pedals inside it: the ProCo Rat (filter, the default) and Boss’s orange distortion (scoop).

Controls. Distortion is the gain in front of the clip. Filter is the tone control after it, and on the Rat it runs backwards: clockwise is darker. Tone is the Boss’s scooped bass-to-treble balance. Volume is the output level and Mix how much of the clipped signal replaces your note. Character picks the pedal. Ceiling is how tall the clipped signal stands. Boost is a booster in front of the clip, and scoop starts with it at 35 dB because the Boss has one in its circuit. Asymmetry clips the Boss’s sides unevenly, which brings in even harmonics. Body moves the Rat’s treble leg between the stock pedal and a common modification. The Effect controls page lists what the knobs span.

Switching. Mix at 0 hands back your signal untouched. Leaving 0 switches the pedal on fresh, rather than replaying what it held when it went off.

Sound. At Distortion 0 the Rat is nearly clean and the Boss never is. Turned up, the Rat’s brightness folds into a mid hump. On scoop every Filter position is its own, and Filter at 0 is the stock Boss. At the defaults, aliasing on a 1010 Hz tone between -22 and -16 dBFS stays 60 dB under the note; louder than that it does not.

Timing. Latency is 2 samples at Mix 1 and zero at any Mix below it. Silence in is silence out at every shipped patch, and the tail settles inside what the class reports.

Levels. A full-scale input plays without wrapping at every shipped patch. The clip keeps its output inside its own headroom at any Ceiling, so Ceiling stops raising the level before the top of its travel, and with Ceiling high, Volume and Mix stop moving the output above a knee that wet_ceiling() reports. No shipped patch sits on a DC offset, and the first note does not arrive on one.

On a board. The class needs audiodsp’s audioshaper, audiobiquad and audioroute, 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 = 'Distortion'

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 = 48000

After a reset the coupling pole leaves a slow residue of up to about 800 LSB beside an untouched copy (787 mono and 630 stereo measured), past tail_samples; TheResetResidue holds it. See “Detector and coupling state” in docs/reference/component-api.md.

MACRO_LABELS = ('Distortion', 'Filter', 'Tone', 'Volume', 'Mix', 'Character', 'Ceiling', 'Boost', 'Asymmetry', 'Body')

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

ASYM_BLEND_STEPS = 256

Removed at the third fix round. Asymmetry used to be Waveshaper.bias, STOCK_ASYMMETRY * macro, which is a 3.5 V offset into a table whose diodes clip at 0.62 V: it parked the operating point at 0.97 of full scale, so a silent input came out at -6.8 dBFS of DC, the coupling capacitor had to hold that, and the step from silence to a note was 0.45 of full scale and took 86 ms to bleed (audit 3 (p)4 and ruling (n)). The DS-1’s asymmetric clipping section is one diode one way and two in series the other - the thresholds differ, not the operating point - so Asymmetry now blends _CURVE_DS1_DIODE into _CURVE_DS1_ASYM, both of which answer a silent input with exactly zero.

CLIPPER_CEILING = 0.74

The largest share of full scale the clipper’s output may be asked for. Above it audioshaper.Waveshaper saturates its own output on the decimator’s ring - see _headroom, and the knee measured on the bare node: clean to 0.74, -47.9 dB at 0.80, -34.0 dB at 1.00.

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).

wet_ceiling()[source]

The largest wet level this class can deliver at the Ceiling and Asymmetry in force, 0-1 - and therefore where Volume and Mix stop moving the output.

Ceiling scales the diode drop and the clipper’s own output is held at or below CLIPPER_CEILING of full scale, so above this point the split in _headroom has nowhere left to put the level: post_gain is already at the ceiling and a mixer voice cannot go past 1.0. Volume and Mix are live below it and inoperative above it - Volume MIDI 84 to 127 is one number at shipped patch 3, which is 43 positions and 3.6 dB of label travel delivering 0.00 dB (audit 3 (p)2, ruling (o)).

At the shipped Ceiling (MIDI 42) and Asymmetry 0 this is 1.0 - the whole travel works - and it falls as either knob rises: the knee is what test_volume_is_monotone_below_the_knee walks.