|
Download CLAUDE.md from RAM2118/pluginbridge: direct link, hf CLI and curl.
- Browser
- Download file 6.86 kB
-
https://huggingface.co/RAM2118/pluginbridge/resolve/ddb115bf829f00a019effbe2c307028edd9a0d27/CLAUDE.md
- Command line
-
hf download hf://RAM2118/pluginbridge@ddb115bf829f00a019effbe2c307028edd9a0d27/CLAUDE.md
-
curl -L -o CLAUDE.md https://huggingface.co/RAM2118/pluginbridge/resolve/ddb115bf829f00a019effbe2c307028edd9a0d27/CLAUDE.md
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 | |