Fold render_component and harness.py into one renderer core, with seams that keep a musician-facing tool possible

[bdbarnett]

Decision recorded, not scheduled. Brad: "build the core so that the product is possible later. We don't have to do it now, but we don't paint ourselves into a corner and build something that can't be built upon."

The duplication

Two scripts do the same three things — drive something that emits audio blocks, deliver timed events into it, stream the result to a WAV with a digest:

• audiocomponents/tools/render_component.py — targets audioinstruments components by name; modes oneshots, kit, phrase, transitions. Runs under CPython and MicroPython, and is careful about memory because a whole render in RAM is a MemoryError on a board.
• micropython-vst3/tools/harness.py — targets micropython-vst3 scripts through the vstaudio shim on the audioif CPython wheel. CPython only.

They differ only in what they drive. Every number the accuracy program has produced came from the first one.

The three seams, and what "not painting into a corner" means for each

Source. The core must not import audioinstruments. A source is anything that yields blocks — an audioinstruments component, a vst3 script, an effects chain — plugged in from outside. If the core knows about instruments, a MIDI-file front end or an effects-only render needs the core changed to exist.

Timeline — the one that actually decides whether the product is possible. Events must be data, not closures. render_component currently schedules lambda: inst.note_on(36, 100). A closure cannot be parsed from a MIDI file, serialised, inspected, diffed, or generated by a DAW export. Declarative records (time, kind, args) can be all of those, and executing them is trivial. This is the difference between a harness and something a musician could ever drive.

The timeline is also where note-offs, macro moves and program changes get modelled properly rather than being a list of note-ons — see #16.

Sink. Streaming, so length is not bounded by RAM, and the digest separable from the file so tests and users want the same code path.

Constraints to carry

• MicroPython compatibility is not optional. render_component has it and harness.py does not; folding toward the latter's shape loses the ability to render on a board and breaks the cross-interpreter parity work, which is how the audioif envelope bug was found.
• Dependency direction: the core depends on audioif's audiocore/synthio only. audiocomponents and micropython-vst3 consume it.
• Blast radius: render_component is used by the tests, measure_hits, shared_circuits, the overlap gate and every listening capture. Changing its interface is not free.

What this is NOT, today

Not a musician-facing product. That would additionally need MIDI-file input, patches addressable by name, and CLI/docs/packaging — the fluidsynth -F out.wav font.sf2 in.mid shape, which is the obvious precedent. Deliberately deferred. The point of the seams above is that adding a MIDI-file source later is another source, not a rewrite.

Related

• render_component sends no note-offs — blocks Phase 2 measurement #16 — no note-offs. The fix should land as the timeline seam, not as a patch bolted onto the current closure list. Held until Listening rig: drive audioinstruments from a DAW via micropython-vst3 so hits are visible #15.
• Listening rig: drive audioinstruments from a DAW via micropython-vst3 so hits are visible #15 — the DAW listening rig.
• The missing parity gate between the fast path and the REAPER/plug-in oracle is a separate piece of work; harness.py already documents that "the REAPER render through the real plug-in stays authoritative", but nothing checks it.

[bdbarnett]

Brad is picking this up in a separate session with Arthur.

Two coupling notes for whoever builds it, so the split does not cause a collision:

#16 (no note-offs) should land as this issue's timeline seam, not before it. Fixing note-offs by adding closures to the current list would be the exact corner this issue exists to avoid. #16 is itself held until the DAW rig (#15) defines what a realistic gate length is, so the natural order is #15 → #17's timeline seam → #16.

The accuracy program is actively using render_component.py — the overlap gate, measure_hits, shared_circuits and every listening capture go through it, and Phase 2 is starting now. Interface changes are not free while that is live. Coordinating the cutover is worth a word before it lands rather than after.

[bdbarnett]

Before anyone writes code against this issue: a fourth renderer exists that this issue does not mention, it lives in audioif, it ships, and it already implements two of the three seams argued for below.

audioif/lib/audiorender/ — a package with a README, a documented composition contract, a 25-name __all__, and its own section in audioif/docs/audio-component-api.md. It has been there since 2026-08-26.

Why nobody looked: the lineage

From the commit that created it (audioif 86056c1):

"audiorender is the tier above audioinstruments and audioeffects: it knows what a piece is — tracks, a tempo map, notes, automation, sections — and turns one into a mixed master and the level report that master is judged by. It comes out of micropython-vst3's render_preview.py, which was the only thing in the workspace that could do this and could only do it for that plug-in."

It grew out of the soundtrack work — a piece needed something that could hear itself — and was then generalised out of micropython-vst3 into audioif. render_preview.py still exists but is now a shim: "The render loop, the tempo math, the mixing and the level report all live in audioif's audiorender. What stays here is the part that is about this plug-in."

That history is why this issue compares render_component.py against harness.py and misses it: it arrived from a third direction, into a third repo.

The three seams, measured against what already exists

Source — already done, and in exactly the shape this issue asks for. voices.py has Puller, Voice, PcmSource, Clock. render() takes a voice_for(track, clock) callback and requires only deliver() and pull_frames() back, so the core never imports audioinstruments — the issue's stated requirement. The commit is explicit that loading a track's sound stays the caller's job precisely so a host can keep its own loader.

Timeline — already data, not closures. build_events() returns (position, kind, data, value) tuples with NOTE_ON / NOTE_OFF / MACRO / PROGRAM constants; deliver() executes them. That is this issue's central demand, already built — and it already emits NOTE_OFF, which is what #16 says is missing from render_component. It also carries two ordering rules the extraction was careful to preserve: events at one sample position happen macros → program change → note-offs → note-ons, and a macro the composition never mentions resolves to the instrument's own patch rather than mid-range. Both are silent when wrong and worth several dB.

Sink — partly. write_wav plus metrics.py for the level report, but the whole song is held in memory.

What this actually changes about the work

This is not a duplicate to merge. It is a different tier, and seeing that changes the shape of the job:

renderer	scope	runtime
audioif/lib/audiorender/	a whole composition — tracks, tempo map, sections, automation	desktop only: numpy throughout, whole song in RAM, explicitly "not meant for a board"
audiocomponents/tools/render_component.py	one component — oneshots / kit / phrase / transitions	dual-runtime by design, CPython and the workspace MicroPython; deliberately stdlib-free of numpy, argparse, pathlib and wave; streams because a whole render in RAM is a MemoryError on a board
micropython-vst3/tools/harness.py	a vst3 script through the vstaudio shim	CPython only
audiocomponents/tools/render_rig_offline.py	rig gestures	CPython only

So the fold is not "adopt audiorender". This issue's own constraint says MicroPython compatibility is not optional — it is how the envelope bug was found — and audiorender cannot satisfy it by construction. The real question is narrower and better founded than the one filed here:

Can the timeline seam be shared across the tiers, given that the composition tier may use numpy and the component tier may not? The event representation is plain tuples of numbers, so it is a plausible yes. build_events() is where the composition-shaped input is turned into them, and that half is desktop; deliver() is the half that touches a component, and nothing in it needs numpy.

What is genuinely missing, and it is the product-shaped part

audioif/docs/audio-component-api.md names its own gap:

Known seam gap: this API defines component methods, not a MIDI wire intake. No shared adapter from MIDI bytes or event streams to these methods ships yet: each consumer hand-rolls its own dispatch (micropython-vst3's mpvst_adapter does, and so does deliver() in lib/audiorender/events.py), and pairings that need a wire decoder in front of a component — for example, playing a Standard MIDI File straight into an instrument — are consequently undelivered.

That is this issue's "musician-facing product" requirement, already scoped, already owned by the message model, and still open. It is the gap worth closing — not the seams, which largely exist.

Verified, not inferred

Both output paths were run on PatchTest (2026-09-02):

• tools/render_preview.py --piece PatchTest out.wav → 8.1 MB stereo master plus the level report (peaks, per-section RMS, simultaneous-track counts).
• reaper/generate_project.py --piece PatchTest out.RPP → 9 KB project, 1 track, 128 notes, scripts embedded in synthesized VST3 state.

Same composition.py, two outputs, one source of truth. Every name in audiorender's documented composition contract is present in soundtrack/Perihelion/composition.py.

One consequence to carry: those two paths are now expected to disagree on dense passages. The WAV path runs the CPython target and the RPP path runs the native engine, and audioif#16 means a released note holds its channel for its whole release tail on the former and not the latter. That is a real divergence, not a renderer fault.

Recommendation

Re-scope this issue against audiorender before writing anything. As filed it proposes designing seams that exist and merging tiers that should not merge. The remaining work is smaller, sharper, and mostly about the MIDI intake gap and whether the timeline representation can be shared downward to the board-capable tier.

[bdbarnett]

Proposal only, no code, as the housekeeping brief asks. Three things have changed under this issue since it was written, and one of them halves it.

Two stale facts first

• micropython-vst3 is mpvst, and harness.py is no longer in tools/ — it is mpvst/examples/soundtrack/composer/harness.py, 141 lines, moved when both composers went to live beside their songs.
• micropython-vst3/tools/render_preview.py, named in the related work, was deleted in the same move.

The timeline seam is half built, and it built itself

#16 landed in 0b34308. It could not wait for this issue — the renderer sent no note-offs at all, so three Phase 2 traits were unmeasurable — but it did not land as another closure list, because writing it that way turned out to be harder than writing it as data.

Every mode now builds a list of records:

presses = [(block, pitch, velocity), ...]

and one function turns that into the executable list, deriving each release from the record beside it:

gated(instrument, presses, gate_blocks) -> [(block, callable), ...]

So presses are already data in all four modes. The closures that remain are only the last wrapper render() consumes, produced in one place instead of being written by hand at four call sites. That is most of the seam this issue calls "the one that actually decides whether the product is possible", arrived at for the ordinary reason: the note-off rule ("release one block early if the same pitch is struck again") cannot be expressed over a list of closures at all, because a closure does not say which pitch it presses.

And the other script already has the same shape. harness.py's deliver(event_type, channel, note_id, data0, value0, value1, sample_position) is a declarative event record in positional form — it has never used closures. The two scripts are closer to a shared timeline than this issue assumes.

What I would actually do, and in what order

1. Widen the record, do not build a core yet. (block, pitch, velocity) becomes (block, kind, args) where kind is the seven-value event vocabulary both sides already speak — the one harness.deliver takes and Instrument._handle dispatches. gated() becomes the executor: one dict from kind to method. That is maybe 40 lines in render_component.py, changes no output, and buys the whole of "parsed from a MIDI file, serialised, inspected, diffed" for note-ons, note-offs, macro moves and program changes at once. It is also the smallest change that makes transitions expressible as data, which today it is not.

2. Only then ask whether a core is worth extracting. With step 1 done, what the two scripts share is: a record vocabulary, a "deliver events up to block N, then pull" loop, and a streaming WAV writer with a separable digest. That is about 120 lines. What they do not share is the source — one loads a script into a namespace through a shim, the other calls audioinstruments.create. The source seam is already clean on both sides, so extraction is mechanical once step 1 exists, and speculative before it.

3. Do not move the file. tools/render_component.py is imported or invoked by the tests, measure_hits, shared_circuits, the overlap gate and every listening capture. The core should appear beside it and render_component become its first caller, so the blast radius is one import line rather than five call sites.

The constraint I would put above the others

MicroPython compatibility, and I would state it more strongly than this issue does. render_component runs under both interpreters today, and the record form in step 1 keeps it: tuples and a dict of bound methods are portable. The moment the core reaches for dataclasses, enum, typing, argparse or pathlib it becomes CPython-only, the cross-interpreter renders stop, and the thing that found the audiodsp envelope bug is gone. render_component's docstring already names those four modules by name as deliberately avoided; whatever comes out of this issue should carry that sentence forward verbatim.

What I would not do yet

The MIDI-file front end, patches by name, packaging. This issue already says so and I agree — but worth noting the ordering that makes it true: step 1 is what makes a MIDI front end "another source" rather than a rewrite, and step 1 is cheap. Until the timeline is a record vocabulary, everything downstream is speculative, and once it is, the rest can wait indefinitely without costing anything.

Sizing

Step 1: an afternoon, no output change, guarded by rendering every mode before and after and requiring byte-identity at gate 0 (which is how #16 was checked — all four modes, byte-identical to the pre-change tool). Step 2: a day, and only worth starting once a second consumer actually wants it. Nothing here is urgent; the seam that mattered is no longer in the way.

[bdbarnett]

Parked (Arthur, 2026-09-22): the proposal above is the plan, and it is a program-sized refactor, not housekeeping. Reopens when the next audio program needs the timeline seam — the note-off rule from #16 already shows where it goes.

[bdbarnett]

Kept parked (Brad, 2026-09-23), with the recorded decision standing. It reopens when a third renderer is about to be written, or the musician-facing tool starts.