What audiodsp is held to
This is the one page that says what each part of audiodsp is held to: a rule you can state in a sentence, and the gates that enforce it.
The rule
A node that CircuitPython also has must render the same bytes CircuitPython
renders, under the same conditions. Same sample rate, same channel count,
same options, and the same compile-time configuration — this port ships
CIRCUITPY_SYNTHIO_MAX_CHANNELS=64, so the CircuitPython build we compare
against is built at 64 as well, and the comparison is only meaningful because it
is. Differences in configuration are not findings; they are setup errors.
A node that is ours alone has no such reference, so it is held to two things instead: that all three of our targets render it identically, and that its behaviour meets stated numeric traits. Neither is a stored byte.
Nothing here is compared against a previous version of our own output.
Why not our own past
Because it is not a standard, it is a memory of a decision. Three ways it fails, all of them observed in this repository rather than imagined:
A stored digest can be re-blessed.
--capturemoves both sides of the comparison at once, the gate goes green, and nothing was checked. That is audiodsp#27, andverify_mixdown_knee.py’s anti-launder tripwire exists because of it.A stored digest can be green while the code is wrong. On 2026-09-09 the MicroPython flanger overflowed
int32_tin its wet interpolation on full-scale material and disagreed with the CPython twin on every setting tried. Every stored fixture inflanger_probe.pymatched to the byte throughout. Only comparing the two targets against each other found it.A reference can outlive the thing it referenced. The vstaudio oracle pinned
audiodynamicsandaudiorouteto mpvst’svstaudio_dsp.cat revisionac87f13. That file was deleted from mpvst in6ea60d3— “Drop the effects library and the DSP that moved to audiodsp” — and the plug-in links audiodsp now. The relationship reversed: vstaudio is a consumer of this package, not a grader of it.
Which nodes are which
The dividing line is not “did we write the C”. It is whether upstream
CircuitPython ships the module. Both kinds are present in the oracle
binary: CircuitPython’s from its own tree, ours from this repository as a user
C module (circuitpython.mk lists exactly which).
CircuitPython’s own — held to CP’s bytes |
Ours alone — no external reference |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Nine of the seventeen are ours, and they are most of the effects palette — which is why “match CircuitPython” cannot be the only rule, and why the second half of this page is not an afterthought.
Two of ours came from mpvst’s engine (audiodynamics, audioroute)
and the rest have no ancestor anywhere. Neither fact changes anything: what
matters is that no independent implementation exists to compare against today.
What holds our own nodes up
1. Three-target agreement, with nothing stored. The CPython extension,
desktop MicroPython, and the patched CircuitPython build must render a probe
identically. All three compile the same kernel under src/shared/, so this is
a real check on the three compilations and on anything that is
architecture-dependent, undefined, or width-sensitive — the class of defect that
found the flanger overflow. It cannot be laundered, because there is no file to
re-capture.
Its honest limit, stated so nobody relies on it for more than it gives: a change to the shared kernel moves all three together and stays green. Three-way agreement sees divergence between targets. It cannot see drift over time. That is what the next item is for.
2. Numeric traits with planted faults. A stated property with a bar — “a 100 Hz low-pass attenuates 1 kHz by at least N dB”, “a reset node renders exact zero on silence from its first block”, “the settled reduction at ratio R is 20·(1−1/R) dB ± 0.01” — and beside it a deliberately broken build that must fail the check. This is measuring against physics and arithmetic, which survive a refactor and do not survive a regression.
A trait without a planted fault is not a check; it is a hope. See
tests/parity/deinit_surface_probe.py for the shape — its --fault mode is run by CI first, and CI fails if the fault
passes.
Where deviations are written down
The upstream record records every deliberate departure from CircuitPython in a node CircuitPython has, and Where audiodsp differs from CircuitPython says what each one means for a user. Under this rule each one is a decision that must be written there, or it is a bug.
What a divergence means now
CP-shared node, we differ from CircuitPython. Either a bug of ours, or a bug of theirs worth an upstream report, or a deliberate departure that goes in the upstream record. Three outcomes, and choosing between them is the work. What it is never is “re-record ours”.
Our own node, the three targets disagree. Ours, always. One of the three compilations is wrong, or the kernel relies on something undefined.
Our own node, a trait fails. Ours, and the trait is the specification — unless the trait was wrong, in which case say so, change it, and say why.
The one way the same C fails this on its own
Three targets compiling one file is the whole mechanism, so anything that lets a
compiler choose its own arithmetic breaks the gate without anybody writing a
bug. There is one such thing and it is dealt with: fused multiply-add.
a * b + c may round twice or once, both are legal, and which one you get
depends on the target – the two ESP toolchains do not even fuse at the same
number of sites in the same file. That was the whole of the P4-vs-S3 split on
audiodynamics (audiodsp#66), and since audiodsp#79 every src/shared/ file that
computes in float includes shared/audiodsp_fp_contract.h and forbids it.
The header is where the reasoning lives: the two spellings that silently do nothing, why it is not a build flag, and what it costs. Add the include to any new shared file that does float arithmetic, or that file alone keeps the behaviour the rest of the kernel has given up.
This gate cannot see contraction on an x86-64 host, and should not be
trusted to. x86-64 does not fuse without -mfma, so all three desktop
interpreters there agree whether or not the pragma is present, and that is the
host almost every run happens on. aarch64 is not blind to it: AArch64 fuses by
baseline, and CI’s ARM lane had carried an accepted baseline of its own since
2026-09-02 for six multitap and pitchshift blocks one byte from x86_64.
Adding the pragma closed exactly those six, which is where the mechanism stops
being inferred and starts being measured
(docs/wheels-and-platforms.md). Proving the board half still
needs board digests. See audiodsp#79 and audiodsp#55.
The other way: a number derived in Python
Contraction is the compiler choosing. This one is the interpreter choosing, and it happens before the kernel is reached at all.
A setting derived in Python passes through audiodsp_util.float32 before it
reaches a node. That is the rule; the rest of this section is why.
Python’s float is the interpreter’s mp_float_t. On CPython and on the desktop
MicroPython that is a double; on an ESP32-P4, an ESP32-S3, an RP2040 and any
build carrying -DMICROPY_FLOAT_IMPL=MICROPY_FLOAT_IMPL_FLOAT it is a single.
So node.mix = 0.35 is not one setting – it is two numbers a ULP apart – and
a node whose blend runs from it renders different bytes on a board than on a
desktop without anything in the kernel being wrong. audiodsp_util.float32(x) is
a pure-Python round trip through struct: the identity on a single-precision
target, a rounding on a double one, and the same number afterwards on both.
audiodsp_util.float32_bits(x) is the same rule for output. "%.6f" % value is
seven significant digits, and MicroPython’s single-precision formatter is not
correctly rounded that far, so a probe printing a float at that width compares
formatters rather than DSP. The bit pattern is exact everywhere.
This is where audiodsp#80 landed: six probes disagreed with CPython on a
single-precision build, and four of the six were the probes’ own arithmetic –
three printing a gain reduction whose bits were identical on all three
targets, one passing mix=0.35, and one deriving its square-wave material from
a Python float phase, so the two builds were being compared on two different
input signals. The two that remain are below the probes and each has its own
issue: audiodsp#101 (synthio.Biquad derives W0 at mp_float_t width where the
CPython extension calls the shared double helper) and audiodsp#102 (a filtered
Echo does its per-sample arithmetic at mp_float_t width in C and in double
in the twin).
The same rule belongs to the classes. audiocomponents#75 is this shape one
level up – a class computing 360 * 4 ** (macro / 127) for a filter frequency
lands its board and its desktop a ULP apart, and board runs of an effect
class named it as one of the three causes of a drive class’s
digests differing. The derivation ends in float32 there too, or the board and
the desktop are not running the same filter.
float32 cannot round away a different libm. A class deriving a setting
with **, math.exp or math.log calls the C library underneath the
interpreter: newlib on the ESP32 boards, glibc on a Linux desktop. Their powf
are not the same function. At 500 * 32 ** (59 / 127), the Damping macro of
audioeffects.rebuilt.Reverb at patch 7, newlib’s powf(32, 0.46456692)
returns 0x40a019be and glibc’s returns 0x40a019bf, the correctly rounded
answer. Both legs are single precision, so float32 is the identity on both,
and the node is handed damping_hz one ULP apart. That one ULP moves the
loop one-pole’s coefficient by one ULP, and the render by one LSB in 9 samples
of 65 536: the whole of audiodsp#183, which had looked like the Tank
computing differently on the boards.
It is not the Tank. Fed a board’s own settings and input, read off the board
through uctypes (the config struct at id(tank) & 0x7FFFFFFF plus 20 bytes on
the ESP32-P4), audiodsp_tank.c compiled for x86-64 renders the board’s bytes
exactly, all 128 blocks; given glibc’s damping_hz instead, it renders the
single-precision desktop’s. This is accepted, as audiocomponents#75 accepted
the width case: a setting derived in Python through libm may differ by a
last bit between a board and a desktop, and the nodes below it agree. A class
that needs the legs to agree hands the node a number it did not compute
through libm.
The third way: the twin keeping what the native borrows
Contraction is the compiler choosing, a derived setting is the interpreter choosing. This one is neither: it is the CPython twin owning memory the native builds only point at.
audiosample_get_buffer hands its caller a pointer into the producer’s own
buffer — int16_t buffer[AUDIODSP_..._FRAMES * 2] on the node, one buffer, not
a queue. A consumer that holds that pointer across calls therefore reads what
the producer rendered last, not what it had rendered when the pointer was
taken. audiomixer.MixerVoice is exactly such a consumer: play() fetches one
block and the mix-down reads it later.
The twin has no pointers, so it answered each pull with a fresh bytes and a
borrowed block could not be overtaken. Any class that pulls a node one of its
own mixer voices is already holding then rendered one block differently on
CPython than on every native build — which is what
audioeffects.rebuilt.Saturation
does to settle its coupling pole before its first block, and why its two
Bias-off-centre patches split CPython from desktop MicroPython, desktop
CircuitPython and both boards (audiodsp#89).
audiocore._AudioSample._publish is the rule now: a node hands back its own
buffer, refilled — one slot for the nodes audiodsp wrote, two for the ported
CircuitPython effects, for Mixer and for the synthesizer, because those
alternate. audiocore._borrow is the in-graph pull that does not copy;
audiocore.get_buffer still copies, on both targets, because it is the
script-facing one. tests/parity/mixer_borrowed_block_probe.py is the gate.
What this does not yet cover: a node’s leftover source block — pending
in src/audiobiquad/Biquad.c and its siblings, kept when one source buffer
outlasts one render — is a borrowed pointer in the C and still a copy in the
twin. Nothing has been measured to depend on it; it is named here so the next
divergence of this shape is recognised rather than re-derived.
The fourth way: mp_float_t inside the kernel, which no rule can round away
The two ways above have fixes. A compiler choosing contraction is forbidden by
a pragma; a number derived in Python is put through audiodsp_util.float32
before it reaches a node. This one has neither, and that is a decision rather
than an omission (2026-09-22, decision 4 of the housekeeping sweep:
accept and document, do not fix).
The shape is always the same. A binding computes something in mp_float_t and
hands it to a kernel declared in double. mp_float_t is a double on a
desktop and a single on every board we ship, so the number that arrives has
already been rounded differently before any kernel runs, and nothing downstream
can recover it. Six issues, one mechanism:
issue |
where |
the value |
|---|---|---|
|
the biquad’s centre frequency |
|
|
a filtered echo’s feedback sum |
|
|
a dB setting’s linear gain, and on a board a different libm |
|
|
the compressor’s detector, from settings that are bit-identical |
|
|
single-precision libm, same C |
|
|
a second cause beside FMA, never identified |
The two widths are 24 bits of significand and 53. The difference each one
produces is the same size every time: a sample or a few per render, each one or
two LSB, which is 90 dB or more below full scale and inaudible by a wide
margin. #101 and #102 are the two the gate actually sees, as
biquad_component_probe.py and echo_filter_probe.py on the
single-precision leg.
Why it is left. Fixing it means one of two things and neither is worth its
price. Deriving at double in the bindings puts a software double on every
board that has no hardware for one, in code that runs per block, to move a
value 90 dB down. Deriving at float everywhere makes the desktop targets
wrong instead of the boards and breaks every stored digest in the repository.
The third option – a shared derivation helper at a fixed width, which is what
audiodsp_biquad_cp_w0 already is for the CPython leg – is the right answer
for a node being written now, and is how new shared code should do it; it is
not worth retrofitting through six call sites and the goldens they move.
What the gate does instead. verify_dsp.py’s --known-divergent takes a
bound: PROBE:LINES. A listed probe may differ on at most that many of its
output lines, and the run fails if the divergence grows, if a probe stops
diverging, or if any other probe diverges at all. A bare PROBE with no
bound is an exemption rather than a tolerance; the gate still accepts it,
prints the size it measured and names the bound that should replace it. That
distinction is the whole point: an accepted difference that nobody has
measured is indistinguishable from a new defect.
Lines, not samples, and the reason is worth knowing. A probe prints a
case name and a few integers per line – usually a digest – rather than raw
PCM. A digest’s decimal spelling changes length as soon as it changes at all,
which is why the two single-precision divergences differ in total byte count
and not only in value, and why a per-sample LSB tolerance cannot describe
them. Measured on the single-precision unix build, 2026-09-22: four lines
each, for biquad_component_probe.py and echo_filter_probe.py alike. The
field delta is printed beside the count and deliberately not bounded –
between two digests it is a large meaningless number.
The one thing this page does not cover
Nothing establishes that a node of ours sounds right, or that its algorithm is the one intended. Three-target agreement proves consistency, traits prove stated properties. Neither proves a design. That comes from a circuit model, a reference recording, or a listener’s ear, and it belongs to the instrument and effect libraries’ own checks rather than to this page.