|
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:
- Hosts any third-party VST3/AU plugin in a separate crash-safe process
- Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
- Audio routes through shared memory (zero added latency)
- 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.hfor 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 registrationformatManager.addFormat(new juce::AudioUnitPluginFormat())β explicit registrationinstance->enableAllBuses()β MUST call before usingplugin->getParameters()βArray<AudioProcessorParameter*>dynamic_cast<juce::AudioPluginInstance::HostedParameter*>(param)for stable IDparam->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. Usesignal(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. UseAccessory(policy 1) - β
activateIgnoringOtherApps:YESβ switches away from Ableton. UseorderFrontRegardlessinstead - β
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