>_EXECUTIVE SUMMARY
zpwr-midi-fx is a modular MIDI effect / generator plugin built on JUCE 8.0.13 (C++20), packaged as VST3, AU (macOS), CLAP (note-effect) and Standalone. Its DSP is the shared zpwr-patch-core (zpc) patch graph — the same engine that drives zpwr-fx and zpwr-synth — here instantiated over a note-event stream rather than audio samples; the audio path is pass-through. The graph carries 111 note-stream modules and is evaluated once per audio block in topological order, with note-offs scheduled across block boundaries so nothing hangs. JUCE and clap-juce-extensions are vendored via CMake FetchContent, so the build needs no system install. Numbers below are read directly from the source, CMake and headers.
~MODULE MAP
The note engines and the graph have no GUI dependency: only PluginProcessor and PluginEditor touch JUCE, so the entire signal layer is testable without audio hardware or a plugin host.
| Module | Layer | Role |
|---|---|---|
| zpwr-patch-core (zpc) | Engine submodule | Shared note-event patch graph; dynamic blocks, summed cables, topological per-block evaluation; consumed by all four plugins. |
| ChordDictionary / ChordEngine | src/midi (headless) | One key → voiced chord; 150+ chord types with inversion, spread, octave-double, transpose and strum. |
| Scale | src/midi (headless) | Snap incoming notes to the nearest in-key pitch (key + scale quantizer). |
| Euclidean | src/midi (headless) | Bjorklund Euclidean rhythm-gate generator for the SeqEuclid block. |
| Arpeggiator | src/midi (headless) | Host-synced arpeggiator: 9 play modes, divisions, gate, octaves, swing, latch. |
| GameOfLife / BrianBrain / Langton | src/midi (headless) | Cellular-automaton sequencer cores feeding the MidiGameOfLife / MidiBrianBrain / MidiLangton blocks. |
| MidiModules | zpc src/midi | Registry of the 111 note-stream modules plus the note-stream signal policy on the zpc graph. |
| PluginProcessor | src (JUCE shell) | APVTS soft keys + auto-param pool, MIDI/MPE capture, transport-driven processBlock feeding zpc::PatchEngine<NoteStream>. |
| PluginEditor | src (JUCE shell) | Thin host over zpc::WebEditor — the shared cyberpunk WebView patcher, catalog and preset bridge. |
~HOST-AUTOMATION FOOTPRINT
Host-automation footprint is fixed and preset-safe: kMaxSoftKeys = 32 (16 active by default) plus kMaxAutoParams = 96, totalling 128 CC-mappable slots, one per MIDI CC.
Soft Keys
An expandable pool of host-automatable macros — ceiling kMaxSoftKeys = 32, 16 active by default, the active count saved in plugin state.
Auto-Param Pool
A reserved pool of kMaxAutoParams = 96 Auto N host params; right-click any block param to bind it (the Kontakt/Reaktor model), so any module parameter becomes host-automatable / CC-mappable.
128 CC-Mappable Slots
32 soft keys + 96 auto params = 128 CC-mappable slots, one per MIDI CC. Everything else lives in the patch, saved as zpc JSON in plugin state.
~DEPENDENCIES
JUCE and clap-juce-extensions are vendored via CMake FetchContent, so the build needs no system install.
| Dependency | Version | Role |
|---|---|---|
| JUCE | 8.0.13 | Plugin framework (C++20); VST3 / AU / CLAP / Standalone wrappers, WebView editor host, APVTS host-automation pool. |
| clap-juce-extensions | FetchContent | CLAP note-effect wrapper layered onto the JUCE shell. |
| zpwr-patch-core (zpc) | submodule | Shared note-event patch graph engine and cyberpunk WebView patcher consumed by all four plugins. |
~VERIFICATION
Two headless C++ smoke suites ship in tests/ and run under ctest --test-dir build with no audio hardware or host. The packaged plugins are validated externally with pluginval (VST3) and clap-validator (CLAP).
| Suite | Source | Covers |
|---|---|---|
| DSP smoke | tests/dsp_smoke.cpp | The JUCE-independent engines — chord dictionary and voicing, scale quantizer, Euclidean generator, arpeggiator traversal and the cellular-automaton cores. |
| Patch-graph smoke | tests/patchgraph_smoke.cpp | The zpc graph itself: routing, pass-through, every module, the mod matrix (soft-key / aftertouch / envelope modulation) and patch JSON round-tripping. |
Generated Reference
The module reference (reference.html) is generated from the live module registry via the gen_reference target, so it cannot drift from the build.
External Validation
The packaged plugins are validated externally with pluginval (VST3) and clap-validator (CLAP).