diff --git a/AGENTS.md b/AGENTS.md index 25533fd..e00f14a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ - The five gates CI runs: `python tests/parity/verify_acceptance.py`, `verify_effects.py`, `verify_streaming.py`, `verify_biquad.py` and `verify_mixdown_knee.py`. Lint is `python -m flake8` (defect checks only). - The deeper parity gates need built interpreters and the pinned CircuitPython oracle. Pass `--micropython` and `--circuitpython` explicitly; `verify_dsp.py` refuses a run with fewer than two interpreters. A stock `circuitpython` build is not the oracle (it has 14 voices; the oracle has 64). See [Running the parity gates](docs/how-it-works/parity-gates.md). - Never edit CircuitPython's own sources for the oracle, and never let a new module shadow one of CircuitPython's. Fixes for bugs that also exist upstream go in this repo's targets only, recorded in [upstream-diff](docs/how-it-works/upstream-diff.md); ask before adding a deviation. -- Don't re-capture a golden, or move `CIRCUITPYTHON_ORACLE` or `DEPENDENCIES.lock`, without independent evidence and the reason written down ([CONTRIBUTING.md](CONTRIBUTING.md#rules-that-keep-the-port-honest)). +- Don't re-capture a golden, or move a pin in `DEPENDENCIES.lock` (the CircuitPython oracle included), without independent evidence and the reason written down ([CONTRIBUTING.md](CONTRIBUTING.md#rules-that-keep-the-port-honest)). - The `audiomp3` decoder is fetched, not vendored: `scripts/fetch_deps.sh` puts it under `.deps/`. Tremor (`audiovorbis`) is vendored in `third_party/tremor`. - Import names match CircuitPython (`import audiocore`, `import synthio`), whichever runtime is underneath. The instrument and effect libraries live in [audiocomponents](https://github.com/PyDevices/audiocomponents), not here. - A frozen module wins over `/lib` on MicroPython and CircuitPython, so a copied or mip-installed `audiodsp` never runs until you rebuild or put `/lib` first. On a source checkout set `PYTHONPATH` (CPython) or `MICROPYPATH` (MicroPython). diff --git a/CIRCUITPYTHON_ORACLE b/CIRCUITPYTHON_ORACLE deleted file mode 100644 index b940bef..0000000 --- a/CIRCUITPYTHON_ORACLE +++ /dev/null @@ -1,10 +0,0 @@ -# The CircuitPython oracle pin. Every parity golden is measured against -# this exact commit (tag 11.0.0-alpha.2; the pin moved from 11.0.0-alpha.1 on -# 2026-10-22, from 10.3.0 on 2026-10-08 with audiodsp#201, from 10.2.1 to -# 10.3.0 on 2026-09-09). -# Moving it is a re-port, not a bump: every move is a resync with upstream -# (docs/how-it-works/upstream-sync.md; the one before this was audiodsp#220). See also -# docs/how-it-works/parity-gates.md (how the 64-voice oracle binary is built) -# and docs/how-it-works/upstream-diff.md; tests/test_voice_ceiling_consistency.py -# pins the binary's sha256. -11.0.0-alpha.2 d53b2277cfad71589028e5da77c984c045db990d diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac16bf3..84e0b36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,8 +55,8 @@ what each module is held to. ## Rules that keep the port honest -- **Don't modify the CircuitPython oracle.** The tag in `CIRCUITPYTHON_ORACLE` - is what every parity golden is measured against. Edit CircuitPython's own +- **Don't modify the CircuitPython oracle.** The `circuitpython` line in + `DEPENDENCIES.lock` is what every parity golden is measured against. Edit CircuitPython's own sources for it and parity quietly means something else. Moving the pin is a resync with upstream, done deliberately: see [Keeping in step with upstream](docs/how-it-works/upstream-sync.md). @@ -65,7 +65,7 @@ what each module is held to. never shadow or rewrite one of CircuitPython's. - **Don't re-capture a parity golden casually.** A fix that is right can still change one; say what independent evidence shows it is right. -- **Don't move the dependency pins** (`DEPENDENCIES.lock`, `CIRCUITPYTHON_ORACLE`) +- **Don't move the dependency pins** (`DEPENDENCIES.lock`, which holds the CircuitPython oracle too) without saying why. - **A fix for a bug that also exists upstream** goes in this repository's targets only, recorded in diff --git a/DEPENDENCIES.lock b/DEPENDENCIES.lock index 5a1c09c..ef86212 100644 --- a/DEPENDENCIES.lock +++ b/DEPENDENCIES.lock @@ -4,3 +4,14 @@ # checkout vendors in its own lib/mp3; patches/adafruit_mp3/ applies # on top. mp3 https://github.com/adafruit/Adafruit_MP3.git aac02afd9f24d2ee930f650156654ab9211a306a +# circuitpython: the oracle pin. Every parity golden is measured against this +# exact commit (tag 11.0.0-alpha.2; the pin moved from 11.0.0-alpha.1 on +# 2026-10-22, from 10.3.0 on 2026-10-08 with audiodsp#201, from 10.2.1 to +# 10.3.0 on 2026-09-09). The build does not fetch it; scripts/fetch_deps.sh +# skips this line. +# Moving it is a re-port, not a bump: every move is a resync with upstream +# (docs/how-it-works/upstream-sync.md; the one before this was audiodsp#220). See also +# docs/how-it-works/parity-gates.md (how the 64-voice oracle binary is built) +# and docs/how-it-works/upstream-diff.md; tests/test_voice_ceiling_consistency.py +# pins the binary's sha256. +circuitpython https://github.com/adafruit/circuitpython.git d53b2277cfad71589028e5da77c984c045db990d diff --git a/ROADMAP.md b/ROADMAP.md index 04d0e16..216e246 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -25,7 +25,10 @@ audio pump holding up under live use such as a stompbox or a stage rig. `audiodynamics`, `audioecho`, `audiofilters`, `audiofreeverb`, `audiograph`, `audioladder`, `audiomixer`, `audioshaper`, `audiospeed`, `audioverb`). - The CircuitPython glue's folder takes a lasting name (`src/circuitpython_spike/` - becomes `src/circuitpython/`), and `CIRCUITPYTHON_ORACLE` joins `DEPENDENCIES.lock`. + becomes `src/circuitpython/`). +- `audiocore`, `audiomp3`, `audiopump` and `synthio` report a `__revision__` + like the other modules, so a board can say which source each was built from + (today those four have none on MicroPython). Bugs, and things you need that don't work yet, go to [issues](https://github.com/PyDevices/audiodsp/issues). diff --git a/docs/how-it-works/index.md b/docs/how-it-works/index.md index 0a61736..81890c5 100644 --- a/docs/how-it-works/index.md +++ b/docs/how-it-works/index.md @@ -120,7 +120,7 @@ hardware layer. The modules you import did not change. The helper package is The committed synthesis, mixer, MIDI, streaming and effects fixtures match CircuitPython 11.0.0-alpha.2 PCM byte-for-byte, built at the same voice -ceiling this port ships (the pin is in `CIRCUITPYTHON_ORACLE`). Import and API +ceiling this port ships (the pin is the `circuitpython` line of `DEPENDENCIES.lock`). Import and API smoke success is not used as a substitute for those comparisons. The playback-facing pull protocol (`audiocore.get_buffer` and `reset_buffer`) is consumed by `pydevices`' `lib/audiodev` package (`AudioOut` in diff --git a/docs/how-it-works/parity-gates.md b/docs/how-it-works/parity-gates.md index e48607c..d04a1ea 100644 --- a/docs/how-it-works/parity-gates.md +++ b/docs/how-it-works/parity-gates.md @@ -9,7 +9,7 @@ to is in [the correctness standard](correctness-standard.md). ## The oracle binary -CircuitPython at the tag in `CIRCUITPYTHON_ORACLE` is the oracle every +CircuitPython at the commit on the `circuitpython` line of `DEPENDENCIES.lock` is the oracle every CircuitPython-shared parity golden is measured against. Build it as CircuitPython's unix coverage variant with `CIRCUITPY_SYNTHIO_MAX_CHANNELS=64` and this repository as its only audio user C module (`circuitpython.mk`), at diff --git a/docs/how-it-works/upstream-diff.md b/docs/how-it-works/upstream-diff.md index 1a0260e..d01324b 100644 --- a/docs/how-it-works/upstream-diff.md +++ b/docs/how-it-works/upstream-diff.md @@ -338,7 +338,7 @@ in audiocomponents' parity sequences on CPython and on MicroPython. The oracle moved from 10.3.0 to 11.0.0-alpha.1 (520805e12) on 2026-10-08, with the binary at `bin/circuitpython-oracle-11.0.0-alpha.1` -(`CIRCUITPYTHON_ORACLE`, [`tests/test_voice_ceiling_consistency.py`](../../tests/test_voice_ceiling_consistency.py)). It moved +(the `circuitpython` line of `DEPENDENCIES.lock`, [`tests/test_voice_ceiling_consistency.py`](../../tests/test_voice_ceiling_consistency.py)). It moved to take upstream's 6dddbda87, "audiodelays, audiofilters, audiofreeverb: buffer lengths and silence fills", which this port now has in full: diff --git a/docs/how-it-works/upstream-sync.md b/docs/how-it-works/upstream-sync.md index 2681f28..8fc57c1 100644 --- a/docs/how-it-works/upstream-sync.md +++ b/docs/how-it-works/upstream-sync.md @@ -14,7 +14,7 @@ The reasons behind each difference, with their measurements, are in ## When -**Resync whenever the oracle pin moves.** The pin is `CIRCUITPYTHON_ORACLE` +**Resync whenever the oracle pin moves.** The pin is the `circuitpython` line of `DEPENDENCIES.lock` at the repository root, and every CircuitPython-compatible gate is measured against the release it names. Moving the pin and resyncing are one change: the resync takes every fix and every addition upstream made between the old pin diff --git a/scripts/fetch_deps.sh b/scripts/fetch_deps.sh index ff87e73..9236e99 100755 --- a/scripts/fetch_deps.sh +++ b/scripts/fetch_deps.sh @@ -14,6 +14,8 @@ MODE="${1:-fetch}" rc=0 while read -r name url rev; do [[ "$name" =~ ^#|^$ ]] && continue + # The CircuitPython oracle is a pin to test against, not a source to build. + [[ "$name" == circuitpython ]] && continue dir="$DEPS/$name" if [[ "$MODE" == "--check" ]]; then have=$(git -C "$dir" rev-parse HEAD 2>/dev/null || echo missing) diff --git a/setup.py b/setup.py index b5dccc6..93eb5ad 100644 --- a/setup.py +++ b/setup.py @@ -53,8 +53,9 @@ def fetch_mp3(): no shell. An sdist already carries the sources and skips this. """ lock = (HERE / "DEPENDENCIES.lock").read_text().split("\n") - name, url, rev = next(line.split() for line in lock - if line.strip() and not line.startswith("#")) + name, url, rev = next(fields for fields in (line.split() for line in lock + if line.strip() and not line.startswith("#")) + if fields[0] == "mp3") dest = HERE / ".deps" / name def git(*args):