audioeffects.bitcrusher

Bitcrusher — a linear hold, the SP-1200’s two numbers as knobs.

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

audioeffects.bitcrusher.CURVE_STEP = 8

How many int16 codes one table point stands for – the width of every riser in the staircase, and the whole of T1’s and T2’s departure from a hard quantizer. CURVE_POINTS - 1 divides 65536, so this is exact.

audioeffects.bitcrusher.DITHER_FRAMES_A = 1021

The two rectangular dither tables. TPDF is the sum of two rectangular draws, so the class plays two loops of COPRIME length rather than one precomputed triangular loop: 1021 and 1024 frames repeat together every lcm = 1 045 504 frames (21.8 s at 48 kHz), where a single 2048-frame loop repeated every 42.7 ms and was a 23.4 Hz comb, not noise (second-pass refutation). Same total frames, so the same pull cost.

audioeffects.bitcrusher.DITHER_GATE_DB = -60.0

The gate on the dither sum, third fix round. The threshold sits 6 dB above the two tables’ own summed level, so the only thing that closes it is the input going away; the hold and release are a converter’s noise following the note rather than stopping dead with it.

audioeffects.bitcrusher.DITHER_GATE_PEAK = 32.768

The dither peak, in 16-bit counts, at which the dither alone reaches the gate’s threshold and holds it open.

audioeffects.bitcrusher.BAND_SECTIONS = 2

The band limit is a 4th-order Butterworth – two sections at the pole Qs the polynomial actually has, not four sections at 0.7071 apiece. Four identical sections were 48 dB/octave with the -3 dB point at 0.66x the nominal corner, so an octave above it the wet was below one 12-bit code and the “filter” was a mute (second-pass refutation; §13.2’s “-384 dB” was digital silence). Two sections roll off 24 dB/octave and leave something to measure.

class audioeffects.bitcrusher.Bitcrusher(source, *options, **keywords)[source]

Bases: Component

12-bit linear hold: Bits and Rate, informed by the SP-1200.

Bits. Bits is the word length, and 12 is the SP-1200’s own. Every depth rounds to the nearest step rather than down, and none is a wire. Each step is rounded over a short ramp, so at 12 bits the error is half a hard converter’s, and it follows that law within 10 %.

Rate. Rate is how fast the hold samples. The hold lands on the whole hertz you ask for and never drifts. At the default, at least 99 % of its runs are one or two samples long. Its images stand within 3 dB of their own level, which is the sound of the knob; above the hold’s own Nyquist they read between 3 dB and 8 dB down. A single-sample event can fall between two held samples and vanish: about 46 % of them do at the default at 48 kHz.

The running rate. Asking for the running rate is a pass-through, and the latency is then 0. Above it Rate clamps, and hold_rate_hz says what you got where the macro says what you asked: at 22.05 kHz the default clamps, and the top of the knob is the same pass-through. Otherwise the latency is the hold’s displacement, 1 sample at the default at 48 kHz, plus the band limit’s when it is on, and the host is told.

Band Limit. Band Limit is a switch, off by default. On, it puts a low-pass in front of the hold that takes the images more than 20 dB down, without muting what is under it, and the tail becomes 640 samples.

Dither. Dither is off by default. It is gated on the input, so silence in is silence out at every patch, and at its top it fades inside the declared tail. At a deep crush with Dither at its top the dither holds its own gate open: it plays on silence, and the class declares no tail.

Mix and Output. Mix 0 is a wire at the source’s own level. Output trims the whole blend: -6 dB is 6 dB down within 0.1 dB, at Mix 1 and at a blend. Keep the input under -3 dBFS and the defaults and patches stay off the rails. The Effect controls page lists what the knobs span and the patches.

It needs audioshaper, audiobiquad, audioroute and audiodynamics, 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 = 'Bitcrusher'

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

INPUT_CEILING_DBFS = -3

The defaults and every patch play the ceiling kit’s materials clean at this level; at full scale, patch 1 rails on a 50 Hz sine.

MACRO_LABELS = ('Bits', 'Rate', 'Dither', 'Band Limit', 'Mix', '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, lazily, so a reset is a fresh instance and takes nothing from the source.

property hold_rate_hz

The hold rate this class actually got, in hertz.

Rate says what you asked for; this says what runs. They differ in two places a user can stand: Rate above the running rate clamps (a hold cannot invent frames), which at 22.05 kHz makes the top four of the knob’s seventeen MIDI stops – and patch 0’s own hold – an identity; and the asked rate is rounded to the whole hertz so the ratio can be exact. audioshaper.SampleHold reduces the pair, so this is sample_rate * den / num off the node itself rather than the class’s arithmetic repeated.

property latency_samples

The hold’s worst-case displacement, in samples.

The DSP has no lookahead and no filter in the reported path, and SampleHold.latency is 0 at every ratio: a refresh latches the frame it is looking at and emits it in the same frame. What a click probe reads is not 0, because a hold decimates: an event lands on the next kept frame and can arrive up to ceil(num/den) - 1 frames late. That bound is read off the node’s own reduced pair – 1 at the default at 48 and 44.1 kHz, 0 at 22.05 kHz where Rate clamps, 0 at Mix 0. Reporting it is what makes the declaration and the probe the same statement.

The band limit has its own delay and the bound did not carry it. Its two Biquad sections are minimum phase and their group delay lands on top of the hold’s displacement: shipped patch 3 measured 2 to 8 samples over 120 offsets at 48 kHz against a declared 6, and 2 to 7 against 5 at 44.1 kHz (audit 3 (p)5, G7). BAND_LATENCY_SAMPLES is what those sections add, measured the same way, and it is in the bound whenever the band limit is in circuit.

BAND_TAIL_SAMPLES = 640

a 200 Hz burst into the two sections at the LOWEST corner the Rate knob reaches (Rate MIDI 0 = 1000 Hz, corner 420 Hz) leaves its last nonzero 16-bit code 530 frames after the input stops, at 44.1 kHz. 256 was the four-section figure and was never the worst corner.

Type:

The band limit’s ring, measured rather than assumed

BAND_LATENCY_SAMPLES = 2

What the band limit’s two sections add to the hold’s displacement, measured over 120 single-sample offsets at 48 and 44.1 kHz (audit 3 (p)5). It is a group delay, so it is the same at both.

DITHER_TAIL_SAMPLES = 9728

What the dither gate rings for after the input stops. The gate holds 20 ms and releases over 50 ms, and the longer the dither, the later its last nonzero 16-bit code: 7 248 frames at +-16 counts, 9 030 at +-32 (12 bits, Dither at maximum, mono, 48 kHz, with the Dither move inside the burst), counted the way the contract counts. 8 192 was the +-16 number. 9 728 covers +-32 with 7 % over it, with or without the band limit, at every rate. Zero dither is still a zero tail: the gate is only in the chain where the dither is.

property tail_samples

0, the band limit’s 640, or the dither gate’s 9 728, and None where the dither is louder than the gate’s threshold.

The gate’s threshold is a level, DITHER_GATE_DB, and the dither’s peak is Dither’s LSB at the depth in force. Past +-32 counts (12 bits at maximum Dither, 11 bits at 1 LSB, and every deeper crush above that) the dither alone holds the gate open, so it plays on silence for good and no bound is true.