MPE: route per-channel MIDI through the engine, expose enable + bend-range controls

[rullopat]

Depends on sfztools/sfizz#1327 (the engine-side MPE PR). Draft for parity with that one — merge order should be engine first, this second.

What's in the Settings panel

• MPE enabled — engine-wide channel routing gate. When off, the engine collapses channel to 0 in all channel-aware entry points so single-channel sessions behave exactly like pre-fork sfizz.
• Master bend (st) / Per-note bend (st) — pitch-bend ranges (MPE 1.0 defaults: 2 / 48).
• Ignore master-bend RPN / Ignore per-note-bend RPN — opt-outs that pin manual values against incoming RPN 0 from a controller. MCM (RPN 6) auto-enable is unconditional per the spec.

Plumbing

• VST3 (SfizzVstProcessor.cpp): 16-channel event bus; playOrderedEvent calls the engine's channel-aware overloads with event.*.channel; kLegacyMIDICCOutEvent carries per-channel pitch-bend / channel pressure / poly pressure / CC; kNoteExpressionValueEvent (tuning, volume, brightness) is routed per-note via a noteId→channel registry. Per-channel paramIDs (kPidMPEPitchBendCh1..15, kPidMPEAftertouchCh1..15, kPidMPECC74Ch1..15) expose the same modulation as VST3 automation, for hosts that prefer parameters over events. Engine-driven MPE state changes (from MCM / RPN 0) feed back to the host via outputParameterChanges so the editor reflects auto-config and project saves persist it.
• LV2 (plugins/lv2/sfizz.cpp): three new control input ports for the 23/24/25 stereo + 37/38/39 multi variants; MIDI dispatch uses sfizz_send_*_channel keyed on msg[0] & 0x0F.
• Pure Data: raw-MIDI input uses the channel-aware C variants.

State versioned (5→6) in SfizzVstState.cpp with backwards-compat read. AU passes auval; VST3 passes pluginval at strictness 4.

What's in the PR (grouped commits)

Initial MPE wiring

• f79e78a DRAFT submodule pin · e67291a MPE across VST3/AU, LV2, PD, editor · 9f8ed47 UI layout

Hand-test fixes

• b0699c8 keep kPidPitchBend / kPidAftertouch in MPE mode · 65f23be VST3 NoteExpression → engine · 7faecf0 per-channel paramIDs

MCM / RPN 0 auto-configuration

• e4e12e7 / 140e8d5 library bumps · b91fad3 library bump bringing in MCM parser · 1252c7a per-axis RPN opt-out checkboxes · 0c9c4f4 stop clobbering engine-driven state per-block · acd5007 feed engine-driven state back to the host · df8833c README MPE section

MPE-off compatibility

• 4a789ff wrapper gates dispatch on the toggle · 68c7dea library bump with the engine-side isolation regression test · 954cf60 library bump moving normalization into the engine (setMPEEnabled(false) flushes voices) · 9e16932 drop the wrapper's now-redundant if (mpe) branches

API rename

• 99eef74 engine dropped the *MPE suffix from dispatch methods; wrapper updates to call noteOn(delay, ch, ...) etc. and the LV2 plugin to sfizz_send_*_channel.

Bend-range read-out and UX fixes

• 39e3107 populate the master / per-note value menus (were silently empty)
• 2ced678 integer formatter, width align with preload / oversampling, disable when RPN-driven
• 4fb3724 new "Current master / per-note bend value" read-out beside each override — shows engine's effective range; in override-on mode with RPN received, displays the incoming RPN value struck through

Help wanted

Smoke-tested by @jamshark70 via SuperCollider + the VSTPlugin extension during review. Additional MPE-controller passes would be welcome — load an SFZ with per-note modulation, toggle MPE on, confirm per-finger pitch-bend / CC74 / channel pressure each route to their own voice.

If a host routes per-channel pitch-bend through VST3 IMidiMapping (rather than emitting Vst::Events), this PR captures the bend via the per-channel paramID mirrors added in 7faecf0.

Submodule note

library/ currently tracks rullopat/sfizz @ 9eaef3fc so the build picks up the engine-side channel-aware symbols. Re-pin to whatever SHA the engine PR merges at once sfztools/sfizz#1327 lands.

cc @paulfd, @jamshark70.

[rullopat]

Four commits on top of the existing branch + a library bump bring this to feature-complete on macOS hosts:

• b0699c8 — kPidPitchBend / kPidAftertouch were being dropped when MPE was enabled, on the assumption that per-channel bend would arrive via kLegacyMIDICCOutEvent. Neither Ableton Live nor SuperCollider's VSTPlugin emit that event. Always forward both; in MPE they land on master channel 0 (correct per MPE 1.0).

• 65f23be — VST3 NoteExpression wiring: INoteExpressionController + INoteExpressionPhysicalUIMapping, three expression types (tuning / volume / brightness) mapped to PUI X/Y/Pressure. Processor keeps a noteId → channel correlation table populated at NoteOn and dispatches kNoteExpressionValueEvent to the matching MPE engine method. Canonical VST3 MPE path for hosts that use Note Expression (Bitwig Studio).

• 7faecf0 — 45 hidden per-channel paramIDs (15 × 3) for member-channel pitch bend / aftertouch / CC74. getMidiControllerAssignment returns the per-channel paramID for the relevant MIDI controllers, and playOrderedParameter dispatches them to channel-aware engine methods. Ableton Live 12's MPE route lands here — once the user toggles "Enable MPE mode" on the device from its right-click context menu.

• e4e12e7 + 140e8d5 — bump library to sftools/sfizz#1327 at c2f81dc7 (channel-aware noteOff, master→member scalar fallback, MPE bend range + master/member contribution summing, empty-vector guard).

Verified end-to-end on Push 3 + Ableton Live 12 with the default *sine SFZ: per-note slide bend (over the configured per-note range, default 48 st), master touch-strip bend (over the master range, default 2 st), per-note pressure, per-note Y / CC74, and overlapping notes on different channels with independent release.

Phase 2's NoteExpression path is implemented but not yet exercised on a host that emits kNoteExpressionValueEvent — Bitwig would be the obvious test, deferred.

User-facing note for the eventual changelog: in Ableton Live 12, MPE has to be enabled per-plugin from the device's right-click context menu ("Enable MPE mode" / "MPE/Multi-channel Settings..."). It's the host-side toggle that switches Live from its non-MPE fallback (which collapses everything to master) to actual per-channel MIDI delivery.

[rullopat]

Added a README section in df8833c documenting MPE usage and the Ableton Live 12 right-click toggle.

For context on the toggle: Ableton ships an internal auto-detect list of MPE-compatible plug-ins as part of Live releases (Kilohearts' Phase Plant / Multipass / Snap Heap were added in 12.2.5, per the release notes — no public mechanism to opt in from the plug-in side). Sfizz isn't on the list, so users currently need to right-click the device header → Enable MPE mode once per instance (Live persists it in the project). Worth flagging in the readme so it doesn't surprise people testing in Live.

[rullopat]

Addresses the MPE-off divergence noted on sftools/sfizz#1327.

• 4a789ff — wrapper dispatch gated on _state.mpeEnabled; on→off flushes via allSoundOff().
• 68c7dea — library bump to 36c92314 (adds engine-side regression test).

[rullopat]

Picks up the engine API rename in 99eef74:

• Library bump to 9eaef3fc.
• VST3 wrapper (SfizzVstProcessor.cpp) calls the renamed C++ overloads (noteOn / cc / pitchWheel etc. with a channel arg).
• LV2 plugin (plugins/lv2/sfizz.cpp) calls the renamed C API (sfizz_send_*_channel).

[rullopat]

Two follow-ups to 9e16932 completing the same cleanup on the remaining dispatch paths:

• 5877c4a — kNoteExpressionValueEvent. Per-note tuning / volume / brightness now dispatch in both MPE states; the engine collapses channel to 0 when MPE is off (Synth::hdPitchWheel et al.), so a per-note expression gesture from an MPE-aware host folds into channel 0 with MPE off, exactly as a raw-MIDI bend on the same channel would.

• 10464fa — kPidMPEPitchBendCh* / kPidMPEAftertouchCh* / kPidMPECC74Ch*. Same pattern for the per-channel parameter mirrors that getMidiControllerAssignment exposes — which is the path Ableton Live 12 actually uses to route per-note expression to the plugin.

Both were silently dropping member-channel input when the wrapper's MPE toggle was off, instead of letting the engine apply its now-consistent channel normalization. Verified on Push 3 + Ableton Live 12:

• MPE off: per-pad slide audibly bends the whole chord.
• MPE on: per-pad slide bends only the touched note, as before.

[jamshark70]

Hi, finally had a bit of time to check this. I was getting some confusing results, so I wanted to double check everything.

"Ignore pb" settings

I had complained that the pitch bend sensitivity settings were disabled. Now I see this is because I didn't understand "ignore xxx bend" -- so I guess either the wording should be improved (though this is difficult, due to limited space in the window) or it's a future documentation need.

When the box is checked, it will use the user's setting in the preferences panel, and disregard RPN 0 settings. If it's unchecked then it's using RPN 0 and not using the UI preference, in which case, indeed, it does make sense not to allow the user to set a value that won't be used.

I can't think of a way to squeeze that into three or four words, so maybe a mouse-hover tooltip should be added?

RPN activation of MPE

AFAICS I am following the spec, but I still can't get it to activate MPE via CC messages.

I'll put in the full transcript of what I'm doing, with comments.

// setup
(
SynthDef(\vst, { |out = 0|
	Out.ar(out, VSTPlugin.ar(numOut: 2));
}).add;
)

a = Synth(\vst);
c = VSTPluginController(a);
c.open("sfizz.vst3"/*, mode: \sandbox*/);
m = VSTPluginMIDISender(c);

c.editor;  // load an instrument

s.addr = DebugNetAddr("127.0.0.1", 57110);  // debug output

v = Voicer(15, \midi -> m, [mpe: true]);
v.gate([60, 63.5].midicps, 2, 0.6);

This is the "control group" -- SC is sending MPE messages, but sfizz has not enabled MPE. So I hear notes rounded to 12ET semitones.

Those messages are:

// pitch bend
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-27, 0, 64], 0]

// note
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-107, 60, 76], 0]

// pitch bend
// (63*128)+43 = 8107 = -85, quarter tone down
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-26, 43, 63], 0]

// note: 63.5 rounded up to 64
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-106, 64, 76], 0]

// note-offs, 2 sec later
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-123, 60, 0], 0]
	['/u_cmd', 1000, 1, '/midi_msg', Int8Array[-122, 64, 0], 0]

Now I send the bytes [0xB0 0x65 0x00] [0xB0 0x64 0x06] [0xB0 0x06 0x0F] per Appendix B example 1 in the MPE spec.

MIDIControlMessage(device: m).play(0x65, 0).play(0x64, 6).play(6, 15);

// sent
Int8Array[-80, 101, 0, -80, 100, 6, -80, 6, 15].prettyPrint
B0 65 00 B0 64 06 B0 06 0F

// play again
v.gate([60, 63.5].midicps, 2, 0.6);

Experimental group: MPE on by CCs. But I still hear 12ET, so, unsuccessful.

Then I manually click the MPE switch in the UI, play it again, and then I hear 24ET (so I know I'm sending valid messages, and the messages are transmitted through VSTPlugin correctly).

I suppose it's possible I might be missing some code...? But I think I'm doing this right, and the CC messages are just not taking effect.

I also verified that saving a preset file does persist the MPE-on setting. That should cover my needs. Just puzzled why the RPN isn't working for me.

(Sorry for dup'ed message -- when reloaded the page, it didn't show this message, so I thought I needed to resubmit.)

(Also, here's an example of 8th-tone microtuning working perfectly in sfizz -- for upstream maintainers, this is good stuff, just hammering out a couple of final details. https://www.youtube.com/watch?v=UtpvPEGn0dA )

[jamshark70]

FWIW, a quick survey of the few MPE capable VSTis on my system:

	MPE button	MPE RPN enable
sfizz	OK	no
Vital	OK	no
Six Sines	OK	no
Surge XT	OK	OK

So it seems that it's fairly common for VST instruments to ignore RPN for MPE, but there is also precedent where at least one VST instrument does respond to the RPN.

Surge also updates the UI upon receipt of the RPN.

[rullopat]

Thanks for the survey — useful. The engine intends to auto-enable on RPN 6 per §2.2.1, so the fact that it doesn't is a wrapper bug; tracing and will fix.

Will also add tooltips on the existing RPN checkboxes, plus a new "Ignore MCM RPN" opt-out (default off, per Appendix A.1) for anyone who prefers pinning MPE state to the UI toggle.

And good catch on Surge mirroring the UI on RPN receipt — our feedback path is wired for that, just needs the dispatch bug fixed first.

[rullopat]

Fixes are in (791c0b0, engine bump to 6d02b0a6). The bug was on the wrapper side: when the host translated your CCs into VST3 parameter changes (which SuperCollider's VSTPlugin does), the wrapper was forwarding them as automation values instead of as MIDI — so they reached the engine but bypassed the RPN parser, which is why MPE never flipped on. Now they go through the MIDI path, so the parser sees the B0 65 00 / B0 64 06 / B0 06 0F sequence properly.

Also added the "Ignore MCM on/off" opt-out checkbox we discussed (default off, honors MCM per §2.2.1; checked gives the Surge-XT-style "panel toggle only" behavior, per Appendix A.1) and hover-text on all three "Ignore" checkboxes.

Same SC test should now hear 24ET after the RPN sequence without manually toggling the UI — let me know if it does.

[jamshark70]

when the host translated your CCs into VST3 parameter changes (which SuperCollider's VSTPlugin does)

D'oh! I see. So the other VSTis may also support MIDI RPN but not parameter changes.

Sorry for noise then, I hadn't realized that was the mechanism. (But, nice to cover another base.)

I think I have no further complaints (though I'm sure I haven't tested all MPE features). Really hope this makes it into the main branch; I'm going to use it routinely.

[rullopat]

Really hope this makes it into the main branch; I'm going to use it routinely.

I'm not that confident now that I look at the project state: last release tagged is from 2 years and a half ago and I don't see much activity in the main branch, but I really hope to be proven wrong.

Worst case scenario I'll continue in my own fork.

[jamshark70]

last release tagged is from 2 years and a half ago and I don't see much activity in the main branch, but I really hope to be proven wrong.

"Circumstances beyond one's control" -- in any case, I am going to keep using the MPE features! I've been waiting over a year to get arbitrary microtuning back. I'm crazy about this development -- thanks for doing it!