# PluginBridge — Claude Code Context ## What This Is A JUCE-based VST3/AU plugin that: 1. Hosts any third-party VST3/AU plugin in a **separate crash-safe process** 2. Exposes ALL hosted plugin parameters via a local MCP server (port 16620) 3. Audio routes through shared memory (zero added latency) 4. Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin ## Current Status - **Sprint 1:** ✅ Done — plugin shell + MCP server - **Sprint 2:** ✅ Done — out-of-process plugin hosting, crash-safe, GUI working - **Sprint 3:** Next — full MCP client integration test (search/get/set params via curl) - **Sprint 4:** Pending — real-time audio analysis (LUFS, FFT) ## Architecture: OUT-OF-PROCESS (Crash-Safe) ``` ┌─ Ableton Process ─────────────────┐ ┌─ PluginBridgeHelper Process ─────┐ │ │ │ │ │ PluginBridge.vst3 (thin shell) │ │ Standalone executable │ │ ├── McpServer (port 16620) │ │ ├── Loads third-party plugin │ │ ├── HelperConnection │ │ ├── processBlock via shared mem │ │ │ ├── Shared memory (audio) │◄───►│ ├── Shows plugin GUI (floating) │ │ │ ├── Semaphores (sync) │ │ └── Handles param get/set │ │ │ └── Unix socket (IPC/cmds) │◄───►│ │ │ └── processBlock(): │ │ If crash → only helper dies │ │ write shm → signal → wait │ │ Ableton stays alive │ │ read output from shm │ │ │ └────────────────────────────────────┘ └───────────────────────────────────┘ ``` **Why out-of-process:** Some plugins (Ozone 12, Kickstart 2) call abort() or show NSAlert during loading, which crashes the entire host process. By running in a separate process, crashes are isolated — Ableton never dies. ## Build System - **JUCE 8** via CMake (git submodule at `/JUCE`) - **Two build targets:** - `PluginBridge` — VST3/AU plugin (loaded in DAW) - `PluginBridgeHelper` — standalone executable (bundled inside .vst3/Contents/Resources/) - **cpp-httplib** — `libs/httplib.h` (MIT, header-only) - **nlohmann/json** — `libs/json.hpp` (MIT, header-only) - **Build:** `cd build && cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++ && cmake --build . --config Release` - **CMake 3.28** required (via pip — system CMake 4.x incompatible with JUCE 8) ## Project Decisions (Confirmed) - **Platform:** macOS only - **License:** GPL (JUCE GPL mode) - **VST3 install:** `~/Library/Audio/Plug-Ins/VST3/` - **Test plugins:** Pro-Q 4, LA-2A, Kickstart 2 (crash test) - **Xcode CLI tools:** 2410+ - **DAW:** Ableton Live 12 (primary) ## IPC Between Plugin ↔ Helper - **Audio:** POSIX shared memory (`shm_open` + `mmap`) — zero-copy - **Sync:** Named semaphores (`sem_open`) — ~microsecond wakeup - **Commands:** Unix domain socket, newline-delimited JSON - **Protocol:** See `Source/Shared/IPCProtocol.h` for all message formats ## MCP Protocol - Endpoint: `POST http://127.0.0.1:16620/mcp` - Health: `GET http://127.0.0.1:16620/health` - Wire format: JSON-RPC 2.0 - 5 tools: `list_plugins`, `search_param`, `get_params`, `set_params`, `get_analysis` ## Plugin GUI Behavior - GUI runs in Helper process as a **floating window** (always-on-top) - Uses `NSApplicationActivationPolicyAccessory` — no Dock icon, no focus steal - `orderFrontRegardless` — shows without switching away from Ableton - Toggle via "Open GUI" / "Close GUI" button in PluginBridge's panel - If plugin crashes → GUI disappears, PluginBridge shows "Plugin crashed - click Reload" ## Key JUCE 8 APIs (Verified Working) - `formatManager.addFormat(new juce::VST3PluginFormat())` — explicit registration - `formatManager.addFormat(new juce::AudioUnitPluginFormat())` — explicit registration - `instance->enableAllBuses()` — MUST call before using - `plugin->getParameters()` → `Array` - `dynamic_cast(param)` for stable ID - `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()` - `juce_add_gui_app()` for Helper target in CMake ## Key JUCE 8 APIs (BROKEN — do NOT use) - ❌ `addDefaultFormats()` — deleted - ❌ `juce::Thread::setCurrentThreadPriority()` — removed, use native pthread - ❌ `getParameter(int)` / `setParameter(int, float)` — deprecated, asserts ## macOS-Specific Gotchas (Learned the Hard Way) - ❌ `MSG_NOSIGNAL` — doesn't exist on macOS. Use `signal(SIGPIPE, SIG_IGN)` + `SO_NOSIGPIPE` - ❌ Plugin scanning in background thread — some plugins show NSAlert → crash. Solution: don't scan at all, just list .vst3/.component files from disk - ❌ `NSApplicationActivationPolicyRegular` — steals focus from DAW. Use `Accessory` (policy 1) - ❌ `activateIgnoringOtherApps:YES` — switches away from Ableton. Use `orderFrontRegardless` instead - ✅ `posix_spawn` — works for launching helper from within a plugin process ## File Structure ``` pluginbridge/ ├── CMakeLists.txt (builds PluginBridge + PluginBridgeHelper) ├── JUCE/ (git submodule) ├── libs/ │ ├── httplib.h │ └── json.hpp ├── Source/ │ ├── Plugin/ ← VST3/AU (runs inside Ableton) │ │ ├── PluginBridgeProcessor.h/.cpp │ │ ├── PluginBridgeEditor.h/.cpp │ │ ├── HelperConnection.h/.cpp │ │ └── McpServer.h/.cpp │ ├── Helper/ ← Standalone exe (separate process) │ │ ├── main.cpp │ │ ├── HelperPluginHost.h/.cpp │ │ └── HelperIPC.h/.cpp │ └── Shared/ ← Used by both targets │ ├── SharedAudioBuffer.h │ ├── IPCProtocol.h │ └── Constants.h ├── CLAUDE.md ├── ROADMAP.md └── SYNC.md ``` ## What NOT To Do - Don't load plugins in-process — crashes DAW with misbehaving plugins - Don't use `PluginDirectoryScanner` — triggers plugin code execution → crash - Don't use `addDefaultFormats()` — deleted in JUCE 8 - Don't steal focus when showing GUI — use Accessory policy - Don't use `MSG_NOSIGNAL` — macOS doesn't have it - Don't use `juce::Thread::setCurrentThreadPriority()` — removed in JUCE 8