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
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,24 @@ breaking changes to the contract were allowed where they bought correctness (D5
`docs/PRODUCTION-PLAN.md`); each is recorded here. From 1.0.0, a change to the class contract is
a major version.

## 2.0.0 — unreleased

The release that brings `tap.python`, a Python class as a Max object without audio
(`docs/TAP-PYTHON-PLAN.md`, Phase 9 of the production plan). Its entries are added as the phase
lands.

### Changed — a last parameter hinted `list[…]` or `np.ndarray` takes the remaining atoms

- **A message's last parameter hinted `list[float]`, `list[int]`, `list[str]`, `list` or
`np.ndarray`** — with no `*args` after it — now takes every atom left after the parameters before
it: as one list, each atom converted by the element hint as a single parameter's would be, or as
a float64 array. `def taps(self, values: list[float])` answers `taps 0.1 0.2 0.3`, and `def
list(self, values: np.ndarray)` a whole list message. With no atoms left it is an empty list, or
its default if it has one. Before, such a parameter took one atom, converted as a `str` — so a
number arrived as the empty string — and a message with more atoms than the method has
parameters was refused. A class that relied on that now receives a list. It is a change to the
class contract, and so the release is 2.0.0 (plan 9.1; decided 2026-10-09).

## 1.0.2 — 2026-10-08

1.0.1 was tagged but never released: its Windows package still had the first fault below. Its
Expand Down
6 changes: 4 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ built yet.
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()`), `worker.h` (worker
per vector when the input is hinted `np.ndarray` — plus `flush_reports()`; and, with `bind_audio`
off for `tap.python`, `call_with_output()`, which converts what a method returns for the outlets
by the plan's output table, and `outlet_count()` from the return hints: plan 9.1), `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`).
Expand All @@ -43,7 +45,7 @@ built yet.
- **`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 — `stereo_width.py`, two inputs and two outputs, and
`allpass-doc.ipynb`).
`allpass-doc.ipynb`; and for `tap.python`, without audio: `euclid.py`, `scale.py`, `note_name.py`).
- **`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 Down
2 changes: 1 addition & 1 deletion ReadMe.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Without a runtime the object still loads, and says in the Max console what is mi
Python sources live in the package's `python` folder. `[tap.python~ name]` loads `python/name.py` and instantiates the class `name` defined in it (the file, class, and argument must share the same name, which must be a valid Python identifier; with no argument, `default` is loaded). The file is loaded by its path, never through `import`, so a file named like a standard-library module (`random.py`, `json.py`) works and does not shadow that module for anyone else. Other files in the `python` folder can be imported by your class as helper modules (the folder is on `sys.path`, after the standard library) — a helper is imported afresh whenever a class file that changed is saved (the loader forgets every module imported from the folder first), but a save of the helper alone is not watched: save the class file too, with a change, to pick it up. No bytecode is written for anything in the folder. Text is UTF-8: the interpreter runs in Python's UTF-8 mode, so `open()` reads and writes UTF-8 unless you pass another `encoding`, whatever the machine's locale.

- **Attributes** — class-level annotated fields (e.g. via `attrs`) become Max attributes. `int` maps to a Max `long`, `float` to `float64`, `bool` to an on/off `long` (your field receives a real `bool`), anything else to a symbol; `Optional[X]`, `X | None`, `Annotated[X, …]` and `Final[X]` count as `X`, a subclass of one of those types (`np.float64`, an `IntEnum`) as its base, and numpy's scalar types (`np.int64`, `np.bool_`) as the kind they hold. A union of several kinds (`float | int`, `str | float`) is a symbol attribute in Max whose value reaches your field as the atom carried it — an `int`, `float` or `str` — like an unannotated parameter. Names starting with `_` are private, and `ClassVar`s are not fields. If a hint cannot be resolved (say a name imported only under `TYPE_CHECKING`), the console says so and the annotation is read as written.
- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …, and the object's own attributes `mode`, `latency` and `latencysamples`) are not exposed — as methods, or as fields; the console names any skipped this way so you can rename it.
- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). A last parameter hinted `list[float]` (or `list[int]`, `list[str]`, `list`) or `np.ndarray`, with no `*args` after it, takes every atom left after the others — as one list, or a float64 array — so `def taps(self, values: list[float])` answers `taps 0.1 0.2 0.3`; with none left it is empty, or its default. Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …, and the object's own attributes `mode`, `latency` and `latencysamples`) are not exposed — as methods, or as fields; the console names any skipped this way so you can rename it.
- **Audio** — a method `process()` runs on the signal, in one of two forms chosen by its type hint:
- `process(self, x: np.ndarray) -> np.ndarray` is called **once per signal vector** with a numpy array of the input and must return an array of the same length (any numeric dtype, or a list; it is converted). This is the form to use for anything that must run in real time — see `python/numpy_gain.py`, and `python/numpy_allpass.py` for a filter with feedback. The input array is reused from one call to the next: copy it if you want to keep it.
- `process(self, x: float) -> float` is called **once per sample** — simplest for sketching; the call is cheap, but every line of Python in it runs once per sample (see [the performance note](#a-note-on-performance)).
Expand Down
91 changes: 89 additions & 2 deletions core/bench/process_bench.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@
// tap_python_bench --json out.json # also write the measurements (scripts/update-perf-docs.py)
// tap_python_bench --seconds 4 --runs 7
//
// It also times a message to an object without audio (tap.python, plan 9.1): a list of 64 numbers
// through processor::call_with_output(), converted in and back out, as the external's messages are
// called from Max's main or scheduler thread.
//
// Run it on an otherwise idle machine, from a Release build.

#include <algorithm>
Expand All @@ -22,6 +26,7 @@
#include <cstdio>
#include <cstdlib>
#include <fstream>
#include <functional>
#include <memory>
#include <numbers>
#include <string>
Expand Down Expand Up @@ -50,6 +55,20 @@ namespace {
{"numpy_gain", "per vector: numpy_gain.py, a gain"},
{"numpy_allpass", "per vector: numpy_allpass.py, the same allpass filter"},
};
// Messages to an object without audio, each with a list of k_message_atoms numbers: the bridge
// alone, then an example doing numpy work.
struct message_subject {
const char* name; // the class file
const char* message; // the method
const char* description; // for the table
};
constexpr message_subject k_message_subjects[] = {
{"bench_list_identity", "list", "returns its list (the bridge alone)"},
{"scale", "list", "scale.py, the list as one array, scaled with numpy"},
};
constexpr std::size_t k_message_atoms = 64;
constexpr std::size_t k_message_calls = 20000; // per round

constexpr double k_sample_rates[] = {48000.0, 96000.0};
constexpr std::size_t k_vector_sizes[] = {64, 512}; // Max's default signal vector, and a large one

Expand Down Expand Up @@ -94,7 +113,38 @@ namespace {
return elapsed.count() / seconds_of_audio;
}

void write_json(const std::string& path, const std::vector<measurement>& results) {
/// One message subject, and the time each round's call took.
struct call_measurement {
std::string subject;
std::string description;
std::vector<double> seconds; // per call, one per round

double fastest() const { return *std::min_element(seconds.begin(), seconds.end()); }

double median() const {
auto sorted = seconds;
std::sort(sorted.begin(), sorted.end());
return sorted[sorted.size() / 2];
}
};

/// The time one call of `message` with `args` takes on `p`, from `calls` of them.
double call_once(processor& p, const char* message, const std::vector<tap::python::value>& args,
const std::size_t calls) {
const auto start = std::chrono::steady_clock::now();
for (std::size_t i = 0; i < calls; ++i) {
const auto out = p.call_with_output(message, args);
if (out.empty()) {
std::fprintf(stderr, "%s output nothing\n", message);
std::exit(1);
}
}
const std::chrono::duration<double> elapsed = std::chrono::steady_clock::now() - start;
return elapsed.count() / static_cast<double>(calls);
}

void write_json(const std::string& path, const std::vector<measurement>& results,
const std::vector<call_measurement>& calls) {
std::ofstream out{path};
out << "{\n \"python\": \"" << Py_GetVersion() << "\",\n \"measurements\": [\n";
for (std::size_t i = 0; i < results.size(); ++i) {
Expand All @@ -104,6 +154,13 @@ namespace {
<< ", \"vector_size\": " << r.vector_size << ", \"load\": " << r.load()
<< ", \"median\": " << r.median() << "}" << (i + 1 < results.size() ? ",\n" : "\n");
}
out << " ],\n \"calls\": [\n";
for (std::size_t i = 0; i < calls.size(); ++i) {
const auto& c = calls[i];
out << " {\"subject\": \"" << c.subject << "\", \"description\": \"" << c.description
<< "\", \"atoms\": " << k_message_atoms << ", \"seconds\": " << c.fastest()
<< ", \"median\": " << c.median() << "}" << (i + 1 < calls.size() ? ",\n" : "\n");
}
out << " ]\n}\n";
}

Expand Down Expand Up @@ -164,6 +221,23 @@ int main(int argc, char** argv) {
}
}
}
std::vector<std::unique_ptr<processor>> message_processors;
std::vector<call_measurement> calls;
std::vector<tap::python::value> list_args;
for (std::size_t i = 0; i < k_message_atoms; ++i) {
list_args.emplace_back(0.5 * static_cast<double>(i));
}
for (const auto& s : k_message_subjects) {
message_processors.push_back(std::make_unique<processor>(s.name, log, std::vector<std::string>{},
std::function<void()>{},
std::function<bool(const std::string&)>{}, false));
if (!message_processors.back()->load()) {
std::fprintf(stderr, "could not load %s (are attrs and numpy importable?)\n", s.name);
return 1;
}
calls.push_back({s.name, s.description, {}});
}

for (int round = -1; round < runs; ++round) { // round -1 warms up, untimed
for (std::size_t i = 0; i < results.size(); ++i) {
auto& r = results[i];
Expand All @@ -172,6 +246,13 @@ int main(int argc, char** argv) {
r.loads.push_back(load);
}
}
for (std::size_t i = 0; i < calls.size(); ++i) {
const double seconds =
call_once(*message_processors[i], k_message_subjects[i].message, list_args, k_message_calls);
if (round >= 0) {
calls[i].seconds.push_back(seconds);
}
}
}

std::printf("%-22s %-7s %-5s %-7s %-7s %s\n", "class", "rate", "vs", "load", "median", "cost");
Expand All @@ -183,8 +264,14 @@ int main(int argc, char** argv) {
load * 100.0, r.median() * 100.0, per_call, r.block ? "us/vector" : "ns/sample");
}

std::printf("\n%-22s %-9s %-9s %s\n", "message", "atoms", "fastest", "median");
for (const auto& c : calls) {
std::printf("%-22s %-9zu %6.2f us %6.2f us\n", c.subject.c_str(), k_message_atoms, c.fastest() * 1e6,
c.median() * 1e6);
}

if (!json_path.empty()) {
write_json(json_path, results);
write_json(json_path, results, calls);
}
return 0;
}
7 changes: 7 additions & 0 deletions core/bench/python/bench_list_identity.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Benchmark fixture (plan 9.1): a tap.python message that returns its list as it came — what the
# bridge costs a message: 64 atoms converted in, the list converted back out.


class bench_list_identity:
def list(self, values: list[float]) -> list[float]:
return values
Loading
Loading