feat(format): AU v2 MIDI-effect adapter — aumi, MIDI in, MIDI out

[shipyard-local]

What

Adds the core AU v2 MIDI-effect adapter — PulpAUMidiProcessor, component type aumi (kAudioUnitType_MIDIProcessor) — so a Pulp Processor whose descriptor declares PluginCategory::MidiEffect can appear in a host's MIDI-FX slot.

CMake already resolved CATEGORY MidiEffect → aumi, but there was no adapter behind it: the bundle was built on the audio-effect adapter, so it advertised an audio in/out pair it never used and its MIDI output went nowhere. This is the missing half.

The design decisions

Each of these has a silent-failure mode if reversed, and each is documented in the code and in the auv2 skill.

• Base is MusicDeviceBase (AUBase + AUMIDIBase), not AUMIDIEffectBase. The latter derives AUEffectBase, which is AUBase(ci, 1, 1) and pulls input element 0 every render — a MIDI processor has no audio input to pull.
• Zero audio input elements, one silent audio output element. The output element carries no signal (zeroed each block, kAudioUnitRenderAction_OutputIsSilence set), but it has to exist: an AU v2 host advances a plugin by rendering it, and rendering is what drains the inbound MIDI queue, runs process(), and fires the MIDI-output callback. With zero output elements there is no bus to pull and the plugin never runs.
• The zero-channel main output bus handed to process(ProcessBuffers&) is marked ACTIVE. Load-bearing: the default projection does if (!main_output()) return;, so an inactive bus means a MIDI effect written against the classic process(out, in, midi_in, midi_out, ctx) signature never runs at all — silently.
• PULP_AU_MIDI_EFFECT registers through AUMIDIEffectFactory. A factory only dispatches the selectors its lookup carries; the plain base factory makes every host MIDI delivery return -4 while the plugin otherwise looks healthy (the same trap that previously hit aumf and aumu).
• Override HandleMIDIEvent, not the per-message hooks. MusicDeviceBase::HandleNoteOn/Off route notes into StartNote/StopNote, which an aumi does not implement — every note would be dropped.

Two deliberate differences from the effect adapter:

• MIDI output is advertised unconditionally, not gated on descriptor().produces_midi. An aumi that can't emit MIDI has no reason to exist, and gating turns a forgotten produces_midi = true into silently discarded output. (The effect adapter still gates, so a plain aufx never advertises one.)
• Bypass is a wire, not a mute. A declared Bypass parameter makes the adapter copy midi_in → midi_out untouched and skip process(). Dropping the stream — right for an arpeggiator on an audio track, where the MIDI is a side product — would here silence every instrument downstream of the bypassed slot. No bypass parameter is synthesized: kAudioUnitProperty_BypassEffect lives on AUEffectBase, so on an aumi a synthesized control would carry no host bypass semantics.

Shared adapter surface

Three AU v2 adapters now exist over three different SDK bases, so everything that needs no specific base moved into au_v2_common.{hpp,cpp} and all three call it: the parameter surface, the editor→host parameter bridge (gestures + the echo guard), preset state, the MIDI-output callback handoff, the Cocoa-view hook, decode_midi_event, the render ProcessContext builders, and MidiOutputPacketBuilder.

The effect and instrument adapters shed ~480 lines of duplication, and the effect stops copying its descriptor (a std::string allocation) on every MIDI-output-name query. fill_parameter_info takes an explicit advertise_value_strings flag so the instrument — which serves neither GetParameterValueStrings nor the string-conversion properties — keeps its exact current behavior instead of advertising a door nobody answers.

Validation

auval -v aumi PTrn Pulp on examples/pulp-transpose, stable PASS across three consecutive runs after an AudioComponentRegistrar kill + settle:

VALIDATING AUDIO UNIT: 'aumi' - 'PTrn' - 'Pulp'
Input Scope Bus Configuration:  Default Bus Count:0
Output Scope Bus Configuration: Default Bus Count:1
VERIFYING REQUIRED PROPERTIES:     * * PASS
VERIFYING RECOMMENDED PROPERTIES:  * * PASS
VERIFYING OPTIONAL PROPERTIES:     Latency PASS
VERIFYING CUSTOM UI: Cocoa Views Available: 1  PASS
PUBLISHED PARAMETER INFO: 2 Global Scope Parameters  PASS
AU VALIDATION SUCCEEDED.

Registered as the ctest auval-PulpTranspose.

auval -v aumi is a weak gate and the PR says so in the support matrix and the skill: it stops after the parameter surface — no render test, no MIDI test, no channel-config negotiation (all of which it runs for aufx/aumu). Corollary: an aumi built on the effect adapter also passes auval -v aumi, so the validator would not have caught the element shape being wrong. That is why the real proof here is the headless suite below; in-DAW MIDI-FX behavior still needs a host.

Tests

test/test_au_v2_midi_processor.cpp (18 cases / 366 assertions) drives the real adapter — MIDI pushed in through the SDK's MIDIEvent/SysEx entry points, a host-installed kAudioUnitProperty_MIDIOutputCallback, Render() advancing the block, and the decoded packet list as the assertion:

transform with offsets preserved · reaching a classic process() with no audio buses · SysEx round-trip · merged SysEx+note ascending order · bypass-as-wire · empty block (no callback) · silent output element + silence flag · max-frames rejection · 4096-event flood (bounded, no leak into the next block) · out-of-block offset clamping · parameters · MIDI-output advertisement · preset round-trip · latency/tail · element shape · global-scope property guards · parameter text conversion both ways.

examples/pulp-transpose/test_pulp_transpose.cpp (5 cases) covers the example Processor headlessly: which messages carry a note number (note on/off, poly aftertouch) vs. which must survive byte-identical (CC 74 must not become CC 76), range clamping, SysEx pass-through.

Existing AU suites re-run green after the shared-surface refactor: au-v2-effect (2080 assertions), au-v2-param-display, au-v2-busses, au-bundle-entry, midi-out-offset-parity, store-lifetime, au-bundle-lifecycle-PulpEffect, cmake-au-v2-type-selection.

Also

• docs/status/support-matrix.yaml — au_v2 notes + a format_limitations entry stating what the adapter does and what auval -v aumi does not prove.
• docs/reference/cmake.md — the component-type ↔ entry-macro table (the pairing whose mismatch is the silent-MIDI trap).
• .agents/skills/auv2/SKILL.md — the aumi section, the shared-surface section, and a warning against introducing a pulp::format::au::detail namespace (it shadows pulp::format::detail and produces confusing errors far from the cause — hit during this work).

---

🔎 Provenance

Agent	claude
Machine	m3
Tab	Forge v2
Directory	/Volumes/Workshop/Code/pulp-aumi
Session	c5642b40-0090-4a66-9223-3bcc4f4de820

Resume

claude --resume c5642b40-0090-4a66-9223-3bcc4f4de820

Jump to this tab

cmux surface focus 4D22CE8D-A143-4A13-95CA-A51E871F8D9C

Relaunch (any agent)

cmux surface resume get --surface 4D22CE8D-A143-4A13-95CA-A51E871F8D9C

Restore URL — https://claude.ai/code/session_01QG7KYpNcdprcaDFrtmzUZC

_{stamped 2026-07-21 20:29 UTC}