audioeffects.saturation

Saturation - a tube stage, a tape chain, or transformer iron.

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

audioeffects.saturation.OVERSAMPLE_RATE_HZ = 32000.0

see _build. The rate picks the factor, on measurement rather than on habit. At maximum Drive with a 3700 Hz probe the alias floor reads, per factor: 48 kHz x1 -35.977, x2 -57.200, x4 -63.847, x8 -64.770 — x4 is the first factor that clears the -60 bar and x8 buys 0.923 dB for another 1.408 ms of S3 block. 44.1 kHz x2 -47.034, x4 -47.763, x8 -47.735 — nothing clears, because h6 of 3700 Hz is above that rate’s Nyquist and folds back whatever the internal rate was. 22.05 kHz x2 -17.590, x4 -17.609, x8 -17.613 — 0.023 dB apart, so the class takes the cheapest factor that is not x1 (which is 4.3 dB worse there, and 4.078 dB worse at the default).

Type:

One factor below whatever the rate ships

audioeffects.saturation.NODE_CEILING = 0.98

audioshaper.Waveshaper clamps its own output at int16 (to_s16), so a post_gain that asks the node for more than full scale hard-clips at the BASE rate, downstream of the decimator, where no oversampling factor can reach it — Distortion’s audiodsp#99, re-measured on this curve. The tube table is smooth, so unlike a diode clipper it does not ring: the bare node on this table at 1010 Hz, 0 dBFS, x8 reads -95.331 dB of inharmonic energy at an output peak of 0.98120 and -70.233 at 1.00000, a 25 dB step at the rail and nothing before it. So the ceiling here is the rail, not Distortion’s 0.74, and this is 0.16 dB under it.

audioeffects.saturation.MAKEUP_SHELF_HZ = 10.0

The makeup stage the third fix round added, and the corner it shelves at. What the node gives up at NODE_CEILING used to go onto the wet mixer voice as level > 1.0 - and a mixer voice clamps at 1.0, so Output +6 delivered +5.965 dB and Output +12 delivered +7.866 (1 kHz, -12 dBFS). The test that should have caught it multiplied post_gain by the level in Python and never rendered (audit 3 (p)1, ruling (o)). A HIGH_SHELF at 10 Hz is a flat boost everywhere a note lives - 0.02 dB down at 100 Hz - and it is the one node in the palette that can carry a gain above unity behind the shaper.

audioeffects.saturation.MIXER_BUFFER_BYTES = 1024

The output 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 every node behind it — the Splitter, whose own chunk is 256 frames, the oversampled shaper and the three biquads — was pulled TWICE per 256-frame block. 256 frames is the palette’s block and the unit every audiodsp node works in, and 1024 * channel_count is one pull per block at either channel count. Distortion already does this (_pcm_mixer) and came in inside its budget on both boards; Saturation, Exciter and Bitcrusher were the three that did not. Measured on the sub-graph alone, six alternating reps in one process on desktop MicroPython: 0.0736 ms/block at 128 frames against 0.0672 at 256, 8.7 % of what the sub-graph costs.

audioeffects.saturation.CHARGE_FRAMES = 512

The zero sample the shapers are re-pointed through on a rewire. The shaper’s native play() takes no loop; one block is all a re-point needs.

audioeffects.saturation.BIAS_STEPS = 256

a grid a board’s single precision and a desktop’s double land on alike (audiocomponents#75), and 0.00001 of the curve’s input span.

Type:

Bias is folded into the table in steps of 1/256 of one table step

audioeffects.saturation.TUBE_BIAS_REACH = 0.125

How far Bias’s ends move tube’s operating point, in the table’s own input units (x = +-1 is +-10 V of grid): +-1.25 V. The 12AX7 in this netlist is cut off below about -2.5 V and pinned by grid conduction above about +1.5 V, and Bias used to be the table’s whole span, +-10 V, so past about a quarter of its travel either way the stage had no slope left: at -6 dBFS Bias -0.4 rendered digital silence and +1 was 37 dB down (sweep finding 4). At +-1.25 V the ends read 5.6 and 7.0 dB under Bias 0 and the operating point is still well off centre. A power of two, so shipped patches 4 and 6 (now Bias -0.75 and +0.762, MIDI 16 and 112, eight times the 58 and 70 they were) land on the table offset they always had and their bytes do not move on tube. tape and console are odd Langevin curves with slope to the table’s ends and keep the whole span: their ends read 6.8 and 6.9 dB under Bias 0. Patches 4 and 6 built on either of those do move, to the eightfold Bias they now name.

audioeffects.saturation.HELD_BY_THE_PLAY_OPERATOR = (0, 1, 3, 4, 7)

The macros whose move changes what the shaper answers silence with while Hysteresis holds the play operator off centre: Drive, Output, Headroom, Bias and Hysteresis itself (_let_go_in_silence).

audioeffects.saturation.DRIVE_CEILING_DB = 15.0

Drive’s ceiling, and now the ceiling on everything in front of the curve. Headroom moves the character’s knee and Drive moves the signal at it, and on this palette those are one number — the node has one gain before the table — so pre = pre0 * drive / head made Headroom a second Drive with +27 dB of reach behind a documented +15 dB cap, and A4 failed from the shipped surface at Headroom -6 / Output +6 (-45.621 at 3700 Hz, audiocomponents#70). The cap is on the pair.

audioeffects.saturation.CONSOLE_EXTRA_SAMPLES = 2.0

console’s two audioecho.FeedbackDelay sections, one sample of pure delay each. It is 2 and not the 9.5 a sub-sample CLICK reads, and the difference is worth the sentence: the 5 Hz damping and cut filters inside those sections have group delay, and kit.click’s own docstring says group delay “is a real property of the class and not the processing latency latency_samples declares”. Read as the integer onset - subsample=False, which is the reading this row wants - a click comes out where 2 says it will. Read sub-sample it is 12.774 at 48 kHz on an impulse and 16.808 on a 4 ms burst, because the envelope of a 5 Hz-filtered click is probe-dependent. Both readings are in the pack; only one of them is a latency.

audioeffects.saturation.CLICK_ONSET_SAMPLES = {('console', 1): 2, ('console', 2): 3, ('console', 4): 4, ('console', 8): 5, ('tape', 1): 0, ('tape', 2): 1, ('tape', 4): 2, ('tape', 8): 2, ('tube', 1): 0, ('tube', 2): 0, ('tube', 4): 1, ('tube', 8): 2}

What a click actually reads, per character and oversampling factor - measured, not derived, by the third fix round.

There were two readings and one declaration. _GROUP_DELAY_SAMPLES is the half-band’s group delay, which is where a symmetric response’s centroid sits; the onset of that response arrives before its centroid, and an onset detector answers the onset. So tube graded sub-sample and failed the integer onset by 2 samples, console graded integer and failed sub-sample, and 10 of 18 build x rate cells were red on one reading or the other (audit 3 (p)8, G7).

This class declares the integer onset, which is the reading a host doing sample-accurate delay compensation can use and the one Distortion already declares (CLICK_DELAY_SAMPLES there). The sub-sample group delay is a real property of the graph and is named in the docstring; it is not what latency_samples reports. Measured at 48 kHz with an impulse at frame 400, stereo and mono; the same factor reads within the kit’s 1-sample bar at 44.1 and 22.05 kHz, which is the whole of what a declaration can promise about an onset the filters move by a fraction of a sample.

audioeffects.saturation.shipped_oversample(sample_rate)[source]

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

Taken from the alias floor at each factor rather than from a rule of thumb — the numbers are at OVERSAMPLE_RATE_HZ. Above x4 the floor at every supported rate is harmonic fold-back, which is the base rate’s Nyquist and not the oversampler’s business, so the factors above it are S3 block for nothing.

class audioeffects.saturation.Saturation(source, *options, **keywords)[source]

Bases: Component

A 12AX7 stage, a tape machine, or transformer iron.

Character. character picks the stage when you build it: tube (the default), tape or console. On tube the second harmonic leads the third by more than 15 dB from -26 dBFS to -6 dBFS, and by more than 20 dB at -6 dBFS. On tape the curve is odd: at the default the second harmonic of a -12 dBFS tone stays 40 dB under it. console is transformer iron, and it saturates from the bottom up.

Drive and Headroom. Headroom is Drive spent the other way round, and the two share one ceiling: Drive less Headroom stops at +15 dB however you reach it.

Aliasing. At 48 kHz on tube the aliasing stays more than 60 dB under a 1010 Hz or a 3700 Hz tone, at the default and at full Drive, and at every Headroom down to -12 dB. That is a ratio, so wherever the output is quiet it reads worse, one dB for one, and console at Drive 0 dB does not reach it.

Output and Mix. Output’s +3, +6, +9 and +12 dB come out within 0.25 dB of what they say. At the default the stage takes level away: a -12 dBFS 1 kHz tone comes out about 8 dB down on tube, 13 dB on tape and 33 dB on console, and Output is what puts it back. With every macro at its top a full-scale input can clip. Mix runs from the dry signal at 0 to the stage at 1, and it is a blend: the level never rises on the way and there is no notch. At Mix 0 the output is the source itself and the latency is 0.

Bias. Bias moves the stage’s operating point. Every position sounds: none takes more than 12 dB off the level at Bias 0, and none wanders more than 1 dB once it has settled. Silence in is silence out at every Bias and every patch.

Speed, Tilt and Hysteresis. Speed is the tape’s, in inches a second, and slides its playback loss; on tube it changes nothing. Tilt tilts the balance about 1 kHz. Hysteresis is off by default. The Effect controls page lists what the knobs span and the patches.

Latency and tail. The rate picks the oversampling: x4 at 48 kHz and 44.1 kHz, x2 at 22.05 kHz. At x4 the latency is 1 sample on tube, 2 on tape and 4 on console, and the host is told. After a burst every patch is back to silence within the declared tail of 65536 samples.

Patches. Alone on an ESP32-S3 the class was measured at 55 % of a block at its default patch and 56 % at its costliest. Saturation - lean runs one oversampling factor lower and was measured at 40 %, so play it when you stack effects.

It needs audioshaper, audiobiquad, audioroute and audioecho, 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.

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.

NAME = 'Saturation'

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

LATENCY_SAMPLES = 3

The shipped x4 group delay, 3.3 samples. The instance property is the one to read: Mix 0 is 0, and it is the onset CLICK_ONSET_SAMPLES measures at the running character and factor.

TAIL_SAMPLES = 65536

Measured, not inherited. The longest memory in the graph is the 20 Hz plate capacitor - 5 Hz on console, which is the slow one. A 200 ms 0 dBFS burst’s residual reaches 0 LSB 3282 frames after the burst on tube at 48 kHz, 3196 on tape and 13759 on `console` (0.287 s at every rate, since the corner is in hertz). 65536 is 1.365 s at 48 kHz, 4.8x the worst of those. The 655360 this used to declare was 13.65 s and was in neither the pack nor a measurement.

MACRO_LABELS = ('Drive', 'Output', 'Mix', 'Headroom', 'Bias', 'Speed', 'Tilt', 'Hysteresis')

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 come back as _build leaves a fresh instance at patch 0.

The walk clears the mixer first (it is registered last), and its voices used to be re-played there: a play primes a voice with a block of its source, so the wet voice took one from a chain the walk had not cleared yet and the first block after the reset was the old audio, 1504 LSB at the defaults. Here the voices are stopped, the patch goes in with the graph unarmed, and the graph is armed the way _build arms it: the shapers re-pointed, the level gates opened, then the voices played.