>_EXECUTIVE SUMMARY
zpwr-fx (project ZpwrFX, v0.1.23) is a JUCE 8 modular patch-effects
plugin. The audio engine is a dynamic patch graph of mono DSP blocks wired by per-input source selection,
summing into two stereo output buses. The block palette is not built here — it is the shared audio module
pack from zpwr-patch-core (registered via zpc::registerAudioModules, re-exported as
zfx::registerAudioModules): 3346 audio blocks across 19 categories (4218 total
across the wider audio/synth/MIDI stack). This repo is the FX host: the JUCE processor/editor, the host-param and
automation surface, factory presets, and the embedded WebView UI. The plugin's own C++ is compact —
src/ is ~1,400 lines (PluginProcessor.cpp 812, PluginEditor.cpp 340, plus headers and
FxConfig.h) — with the heavy DSP and registry living in the shared submodule.
~MODULE MAP
The host-side components in this repo, plus the shared engine they delegate to. The FX
C++ is small and focused; the DSP catalog and graph engine live in the zpwr-patch-core submodule.
| Module | Source | Role |
|---|---|---|
| ZpwrFxProcessor | src/PluginProcessor.cpp/.h | AudioProcessor: patch graph host, processBlock, state save/restore, factory programs, MIDI PC/Bank Select, master-insert plugin host |
| ZpwrFxEditor | src/PluginEditor.cpp/.h | JUCE 8 WebBrowserComponent editor; binds native JS↔C++ functions and the soft-key sliders |
| FxConfig | src/FxConfig.h | Host layout constants: 16 active / 32 max soft keys, 96 auto-param pool, 11 MIDI/MPE sources, 12 default nodes, source-id map |
| Audio module pack | libs/zpwr-patch-core | The 3346-block palette + graph engine (topological sort, one-sample feedback resolution); registered onto the core |
| ScriptEngine (Expr) | zpwr-patch-core (Expr block) | RT-safe expression VM for user per-sample code; tested here via tests/ScriptEngineTest.cpp |
| Soft keys + Auto pool | PluginProcessor (APVTS) | 32 soft-key host params + 96 reserved Auto N slots = 128 CC-mappable, bind any block param for host automation |
| Master insert host | zpc::PluginInsert / PluginHost | Hosts one external VST3/AU on the master path (JUCE_PLUGINHOST_VST3/AU enabled) |
| WavRecorder | zpc::WavRecorder | RT-safe 32-bit float capture of the master output to ~/Music/zpwr |
| gen_reference | tools/gen_reference.cpp | Console app generating reference.html/PDF from the live module registry so docs never drift |
~BLOCK CATEGORIES
The 3346 blocks are grouped into 19 categories: Oscillator, Filter, Distortion, Amp, Modulation, Delay, Reverb, Dynamics, Pitch, Utility, EQ, Effect, Envelope, Routing, Sequencing, Spectral, Stereo, Physical, and Tape. Each block exposes three inputs (In 1, In 2, Mod), six parameters, and one output. The set includes a large circuit-modeled group (zero-delay-feedback ladders/SVFs, Shockley-diode and Ebers-Moll clippers, Koren triode/EL34 stages, Jiles-Atherton tape, Lambert-W wavefolder, four-diode ring mod). The authoritative per-block listing is the generated Module Reference.
~DEPENDENCY FOOTPRINT
No external package registry: every dependency is a git submodule. The plugin links a focused set of JUCE modules and the shared patch-core engine.
| Dependency | Kind | Use |
|---|---|---|
| JUCE | submodule (libs/JUCE) | Framework. Linked modules: juce_audio_utils, juce_gui_extra, juce_dsp (+ recommended config/warning flags) |
| zpwr-patch-core | submodule (libs/zpwr-patch-core) | The audio module pack, patch graph engine, and shared WebView UI assets |
| clap-juce-extensions | submodule (libs/clap-juce-extensions) | Wraps the same plugin as a CLAP (CLAP_ID com.menketechnologies.zpwrfx, features audio-effect/multi-effects) |
| zpwr-clip-engine | submodule (libs/zpwr-clip-engine) | Clip/pattern engine for the Clip tab (from zpwr-daw) |
Build System
CMake (≥ 3.22), juce_add_plugin with FORMATS VST3 / AU / Standalone, plus a CLAP target via clap-juce-extensions — four shipped formats.
Embedded UI
UI is embedded via juce_add_binary_data (JUCE_WEB_BROWSER=1, JUCE_USE_CURL=0, no node build) — self-contained, no external files.
Submodules
All four dependencies are git submodules: JUCE, zpwr-patch-core, clap-juce-extensions, and zpwr-clip-engine. No external package registry.
~VERIFICATION
Two headless C++ test console apps ship in the repo (built as JUCE console targets) and each returns a non-zero exit code on any failure.
| Test | File | Coverage |
|---|---|---|
| ScriptEngineTest | tests/ScriptEngineTest.cpp | ~27 cases over the Expr VM: arithmetic/precedence, pow, params, math funcs, clamp/if/lerp, persistent state, div-by-zero / log(0) finiteness, tap() feedback stability, comments, and 8 expected compile-failure cases (dangling assignment, unknown func/var, assign to read-only, wrong arity, empty) |
| PatchGraphTest | tests/PatchGraphTest.cpp | The audio module pack on zpwr-patch-core: registry lookups (Filter/Expr/Comb present), output finiteness across runs, Drive output bounded, chained Drive→Filter finiteness, and PathLFO axis behaviour (flat path centred, bipolar sweep within ±1) |
Scope
These are correctness/sanity checks (registry integrity, numerical finiteness, output bounding, compile-time rejection of unsafe scripts) rather than a perceptual audio-quality suite. The tests here target the FX-side integration and the Expr VM.
No Committed CI
There is no CI workflow committed in this repo, and the broader 3346-block catalog is validated upstream in zpwr-patch-core.
RT-Safety
Both suites are RT-safety oriented — the engine guarantees finite, sanitized output (NaN/Inf → 0) and rejects over-limit scripts at compile time.