pluginbridge / CLAUDE.md
RAM2118's picture
Update CLAUDE.md β€” reflects out-of-process architecture, current status, lessons learned
2aa5050 verified
|
Raw History Blame
6.86 kB
# 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<AudioProcessorParameter*>`
- `dynamic_cast<juce::AudioPluginInstance::HostedParameter*>(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