Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,14 @@ jobs:
|| { echo "ERROR: $bin is not universal"; exit 1; }
done

# max-sdk-base leaves the identifier for Xcode to expand; the object's CMakeLists expands it
- name: Verify the bundle identifier is expanded
run: |
id=$(plutil -extract CFBundleIdentifier raw "externals/tap.python~.mxo/Contents/Info.plist")
echo "CFBundleIdentifier: $id"
[ "$id" = "com.74objects.tap.python-tilde" ] \
|| { echo "ERROR: expected com.74objects.tap.python-tilde"; exit 1; }

- name: Verify libpython resolves via a relative rpath only
run: |
bin="externals/tap.python~.mxo/Contents/MacOS/tap.python~"
Expand Down
61 changes: 53 additions & 8 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
name: release

# Builds the release packages (plan 4.5, D3): the Max package with the runtime bundled, per
# platform, zipped with SHA256 checksums, and attached to a *draft* GitHub release for a tag
# vMAJOR.MINOR.PATCH — publishing it stays a deliberate act. Run by hand (workflow_dispatch), it
# builds and uploads the packages as workflow artifacts without making a release.
# platform and for every platform at once (plan 4.8), zipped with SHA256 checksums, and attached
# to a GitHub release for a tag vMAJOR.MINOR.PATCH: published as a pre-release for 0.x versions,
# and a *draft* from 1.0 on — publishing those stays a deliberate act until the packages are
# signed. Run by hand (workflow_dispatch), it builds and uploads the packages as workflow artifacts
# without making a release.
#
# PythonTap-<version>.zip every platform: both externals, and each runtime in
# support/<platform>, where the external looks first
# PythonTap-<version>-macos-arm64.zip universal external + the Apple Silicon runtime
# PythonTap-<version>-macos-x86_64.zip universal external + the Intel runtime (and for Max
# running under Rosetta)
Expand Down Expand Up @@ -194,12 +198,50 @@ jobs:
path: dist/*.zip*
if-no-files-found: error

# One package for every platform (plan 4.8), merged from the three just built: each runtime in
# support/<platform>, each platform's licenses in licenses/<platform>, the rest once.
all-platforms:
name: all platforms
needs: [macos, windows]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
pattern: package-*
path: platforms
merge-multiple: true

- name: Merge
run: |
set -euo pipefail
args=()
version=""
for zip in platforms/PythonTap-*.zip; do
[[ "$(basename "$zip")" =~ ^PythonTap-([0-9][0-9.]*)-(macos-arm64|macos-x86_64|windows-x64)\.zip$ ]] \
|| { echo "::error::unexpected package $zip"; exit 1; }
version="${BASH_REMATCH[1]}"
args+=("${BASH_REMATCH[2]}=$zip")
done
[[ ${#args[@]} -eq 3 ]] || { echo "::error::expected 3 platform packages, found ${#args[@]}"; exit 1; }
python3 scripts/assemble-package.py --merge "${args[@]}" --output dist
name="PythonTap-$version.zip"
(cd dist && zip -qry "$name" PythonTap && sha256sum "$name" > "$name.sha256")
ls -la dist

- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: package-all
path: dist/*.zip*
if-no-files-found: error

release:
if: github.ref_type == 'tag'
needs: [macos, windows]
needs: [macos, windows, all-platforms]
runs-on: ubuntu-latest
permissions:
contents: write # create the draft release; nothing else in this workflow can write
contents: write # create the release; nothing else in this workflow can write
steps:
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
Expand All @@ -215,10 +257,13 @@ jobs:
sha256sum *.zip > SHA256SUMS
for f in *.zip.sha256; do sha256sum -c "$f"; done

- name: Create the draft release
# 0.x: published at once, as a pre-release (plan 4.8); from 1.0, a draft to publish by hand
- name: Create the release
env:
GH_TOKEN: ${{ github.token }}
run: |
version="${GITHUB_REF_NAME#v}"
if [[ "$version" == 0.* ]]; then kind=(--prerelease); else kind=(--draft); fi
gh release create "$GITHUB_REF_NAME" dist/*.zip dist/*.zip.sha256 dist/SHA256SUMS \
--repo "$GITHUB_REPOSITORY" --draft --verify-tag --title "PythonTap ${GITHUB_REF_NAME#v}" \
--notes "See CHANGELOG.md for what changed. Unzip into Documents/Max 9/Packages; the Python runtime is included. On a Mac, choose arm64 for Apple Silicon or x86_64 for Intel (or for Max running under Rosetta)."
--repo "$GITHUB_REPOSITORY" "${kind[@]}" --verify-tag --title "PythonTap $version" \
--notes "See CHANGELOG.md for what changed. Unzip into Documents/Max 9/Packages; the Python runtime is included. PythonTap-$version.zip works on every platform; the others are smaller, one platform each — on a Mac, arm64 for Apple Silicon or x86_64 for Intel (or for Max running under Rosetta)."
63 changes: 62 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,68 @@ Changes to the Python class contract and to the object's behavior, newest first.
breaking changes to the contract are allowed where they buy correctness (D5 in
`docs/PRODUCTION-PLAN.md`); each is recorded here.

## Unreleased
## 0.10.0 — 2026-10-01

### Added — one package for every platform

- **Each release also has `PythonTap-<version>.zip`, for every platform at once**: the macOS and
Windows externals, and each platform's runtime in `support/<platform>/`. The external uses
`support/<platform>/` when its package has one — on macOS, each architecture its own — and
`support/` otherwise, so the per-platform packages and a checkout work as before. 0.x releases
are published as pre-releases rather than drafts. (Plan 4.8.)

### Added — worker mode

- **`@mode worker` runs `process()` on a thread of its own**, `@latency` milliseconds behind the
audio (30 by default, rounded up to whole signal vectors; it must exceed Max's I/O vector), so
that nothing else Python does — a
reload, a message, another instance — can hold up the audio thread, which only copies vectors to
and from it. Vectors the worker is late for are output as silence, reported once per load, and
the delay stays the same; the read-only `@latencysamples` gives it in samples. The worker thread
has the real-time scheduling of an audio thread. `@mode direct`, the default, is as before.
(Plan 2.5.) *Changed with it:* the object's own attributes `mode`, `latency` and
`latencysamples` are reserved — a class's field or method of one of those names is not exposed,
and the console says so (before, fields were never checked against reserved names).

### Added — several inputs and outputs

- **process() can take several signal inputs and return several outputs.** Its parameters are the
object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right:
np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes `[tap.python~ …]` with two of each, and
`process(self) -> float` a generator (with one inlet still, for messages). The inputs are all
`np.ndarray` or all per sample; a tuple return must say how many values it has. A return with the
wrong number of values is output as silence and reported once. New example: `stereo_width.py`.
A save that changes how many changes the object's inlets and outlets in place, keeping the patch
cords of those that stay. (Plan 2.4.) *Changed with it:*
`process()` taking `*args` is now reported and not bound (before, it was bound and its extra
arguments never arrived).

### Changed — a broken file is reported once

- **A save that breaks a class file is reported once, however many objects share it.** Every
object used to run the file and print its traceback: a syntax error with 25 objects printed 25
tracebacks. Now a failure of the same source already reported in the last two seconds — the
same save, or a patch opening many objects at once — is not reported again, while an object
created later with the file still broken says why it is silent. Every load still runs the file,
in case something it imports has been fixed. (Plan 6.10.)

### Changed — reloads and the audio thread

- **A reload no longer holds up the audio for its whole length.** The interpreter now hands itself
to a waiting thread after 0.5 ms instead of CPython's 5 ms, so the audio thread waits at most
about that long at a time while another thread — a reload, above all, which takes a few
milliseconds — runs Python. Measured at 96 kHz with 512-sample buffers and a save every 100 ms,
CPython's default made a buffer late in most runs (the worst took 45 ms); at 0.5 ms none was.
(Plan 2.6.)

### Fixed — the package

- **The macOS external's bundle identifier** is `com.74objects.tap.python-tilde`; it shipped as an
unexpanded template (`com.74objects.${PRODUCT_NAME:rfc1034identifier}`), which signing and
notarizing would have refused. The development plan no longer ships inside the package, and the
reference page now follows the object's descriptions (Max rewrites it from them).

## 0.9.0 — 2026-09-30

### Changed — the console on reload

Expand Down
34 changes: 25 additions & 9 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,26 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as
signatures) that `processor.h` builds its descriptions from), `value.h` (the Max-atom value model and its coercion
rules, which reproduce `atom_getlong`/`atom_getfloat`/`atom_getsym`), `processor.h` (load/reload,
class introspection, attribute and message dispatch, `prepare()`, and `process()` — per sample, or
per vector when the input is hinted `np.ndarray` — plus `flush_reports()`). New CPython-facing
per vector when the input is hinted `np.ndarray` — plus `flush_reports()`), `worker.h` (worker
mode, plan 2.5: `process()` on a thread of its own, a fixed number of vectors behind an audio
thread that only copies through a lock-free ring and never takes the GIL). New CPython-facing
behavior goes here, never in the wrapper. CMake target `tap::python` (`core/CMakeLists.txt`).
- **`core/tests/`** — the core's Catch2 battery against CPython 3.13, with Python fixtures in
`core/tests/python/` and the shipped examples copied alongside. Runs on Linux, including under
ASan/UBSan and TSan.
- **`core/bench/`** — `tap_python_bench` times `processor::process()` as Max's audio thread calls it
(plan 6.3), fastest of five runs. `scripts/update-perf-docs.py` builds it (Release), runs it, and
(plan 6.3); `tap_python_reload_bench` times the audio buffers while the class reloads, with the
audio thread scheduled as Core Audio's are (plan 2.6: why the runtime sets a 0.5 ms switch
interval). `scripts/update-perf-docs.py` builds it (Release), runs it, and
rewrites the ReadMe's generated performance tables — with `--max`, Max's CPU meter too, through
`runtime-tests/run.py --session perf`. Never hand-edit those tables; measure on an idle machine.
- **`source/projects/tap.python_tilde/`** — the Min external: package paths, the file watcher, atom
conversion, and mapping the core's descriptions onto `object_addattr`/`object_addmethod`. Its
`_test.cpp` drives the Max glue through min-api's mock kernel.
- **`python/`** — the user's script folder in the package (and the examples: `default.py`,
`numpy_gain.py`, `allpass.py`, `numpy_allpass.py` — the same filter per vector, checked equal
sample for sample by the core battery — and `allpass-doc.ipynb`).
sample for sample by the core battery — `stereo_width.py`, two inputs and two outputs, and
`allpass-doc.ipynb`).
- **`runtime-tests/`** — tests that run inside a real Max (plan 6.1): Cycling '74's max-test harness
(submodule), patchers generated by `make_patchers.py` (edit the generator, never the patchers),
fixtures (`python/maxtest_*.py`, copied into `python/` for a run) and `run.py`, which installs the
Expand All @@ -55,7 +60,8 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as

## Build & test

The fast loop is Linux, no Max and no runtime install needed — just a CPython 3.13 with headers:
The fast loop is Linux, no Max and no runtime install needed — just a CPython 3.13 with headers
(without one, `uv python install 3.13`, then `-DPython3_EXECUTABLE=$(uv python find 3.13)`):

```sh
# the core battery
Expand Down Expand Up @@ -88,7 +94,9 @@ clang-format, clang-tidy (a clang-tidy failure or crash fails the gate, not just
run with `contents: read`, pin third-party actions by commit SHA (tag noted beside it), and cancel
superseded runs. `release.yml`: on a `vX.Y.Z` tag, builds, tests, packages (macOS per architecture,
on runners of that architecture — the runtime is per arch, only libpython is universal), signs when
the secrets exist, and attaches zips + SHA256s to a draft release.
the secrets exist, merges the three into one package for every platform (`assemble-package.py
--merge`: each runtime in `support/<platform>`, where the external looks before `support/`), and
attaches all the zips + SHA256s to a release — a pre-release for 0.x, a draft from 1.0.

## Threads and the GIL (load-bearing)

Expand All @@ -103,6 +111,12 @@ the secrets exist, and attaches zips + SHA256s to a draft release.
(and copies) of what it uses before running anything that could yield. Keep it that way.
- `gil_lock` gives each thread one long-lived Python thread state (`detail::thread_state_keeper`);
don't call `PyGILState_Ensure` directly.
- **Worker mode** (`@mode worker`, plan 2.5): `process()` runs on the worker's own thread instead,
and the audio thread only copies vectors through `worker`'s lock-free ring — no GIL, no
allocation, no Python. The worker thread must have audio-thread scheduling (the wrapper's
`audio_thread_scheduling`, through the core's `thread_setup` hook): an ordinary thread was late
even at 21 ms of latency on a busy machine. `worker::start()`/`stop()` join threads, so never call
them holding the GIL.
- **Nothing prints on the audio thread.** Problems in `process()` are recorded (exception object,
flags) and the host's `report_ready` callback fires — the external sets a `queue<>` — and
`flush_reports()` prints them on the main thread. Anything new on the audio path follows suit.
Expand All @@ -120,8 +134,9 @@ the secrets exist, and attaches zips + SHA256s to a draft release.
- **Say what is true of a class once, what is true of an instance per instance.** Many objects can
share one class file; only the processor whose `load()` ran the file (`load_script` says so)
announces the class — its `Loaded` line and its diagnostics — through `announce()` (plan 6.7).
Use `log()` only for what concerns one instance. Tests that load a file again and check what was
announced call `forget_loaded()` first.
Use `log()` only for what concerns one instance. A file that fails to load is reported once too:
the loader marks a failure of the same source it reported under two seconds ago (6.10). Tests
that load a file again and check what was announced or reported call `forget_loaded()` first.
- Report user exceptions with `tap::python::report_exception()`, **never `PyErr_Print()`**: for a
`SystemExit` it calls `Py_Exit()` and quits Max. Never finalize the interpreter, and never let a C++
exception cross a Max callback (the trampolines are wrapped in `guarded()`).
Expand All @@ -140,8 +155,9 @@ the secrets exist, and attaches zips + SHA256s to a draft release.
C++17), as TapTools-Max does.
- **Keep in sync when behavior changes:** `ReadMe.md`, the object's min metadata
(`MIN_DESCRIPTION`, argument and message descriptions — min regenerates
`docs/tap.python~.maxref.xml` from them whenever the external is newer, so never hand-edit the
page; commit the regenerated one), `help/tap.python~.maxhelp`, the examples and their notebook
`docs/tap.python~.maxref.xml` from them when Max loads an external newer than the page, so never
hand-edit the page: rebuild, run Max once — `runtime-tests/run.py` says when the page was
rewritten — and commit it), `help/tap.python~.maxhelp`, the examples and their notebook
(committed executed), and the plan.
- **Implement from documentation and published sources only** — the CPython C-API docs, the Max SDK
docs — never by reverse-engineering another product.
Loading
Loading