|
Download CLAUDE.md from RAM2118/pluginbridge: direct link, hf CLI and curl.
- Browser
- Download file 6.35 kB
-
https://huggingface.co/RAM2118/pluginbridge/resolve/3853310e85faaa511dd0f4cda9a29b3c4e8cd996/CLAUDE.md
- Command line
-
hf download hf://RAM2118/pluginbridge@3853310e85faaa511dd0f4cda9a29b3c4e8cd996/CLAUDE.md
-
curl -L -o CLAUDE.md https://huggingface.co/RAM2118/pluginbridge/resolve/3853310e85faaa511dd0f4cda9a29b3c4e8cd996/CLAUDE.md
6.35 kB
PluginBridge β Claude Code Context
What This Is
A JUCE-based VST3/AU plugin that:
- Hosts any third-party VST3/AU plugin inside itself (audio passes through)
- Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
- Provides real-time audio analysis (LUFS, FFT bands, stereo width)
- Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin
Project Decisions (Confirmed)
- Platform: macOS only (for now)
- License: GPL (JUCE GPL mode β no commercial license needed)
- VST3 install path:
~/Library/Audio/Plug-Ins/VST3/ - AU install path:
~/Library/Audio/Plug-Ins/Components/ - Test plugins: FabFilter Pro-Q 4 (EQ, many params), LA-2A compressor (fewer params)
- Xcode: 14+ required (user should verify with
xcode-select --version) - DAW: Ableton Live (primary), Logic Pro (secondary AU test)
Architecture (Single Plugin Host, Not a Graph)
PluginBridgeProcessor (AudioProcessor β the outer VST3/AU shell)
βββ HostedPluginManager β loads ONE inner VST3/AU, enumerates params
βββ McpServer (httplib) β JSON-RPC 2.0 on http://127.0.0.1:16620/mcp
βββ AudioAnalyser β LUFS + 7-band FFT + stereo width in processBlock
βββ processBlock():
buffer β analyser.process(buffer)
β hostedPlugin->processBlock(buffer, midi)
β output
Build System
- JUCE 8 via CMake (git submodule at
/JUCE) - cpp-httplib β single header
libs/httplib.h(MIT) - nlohmann/json β single header
libs/json.hpp(MIT) - LUFSMeter β 4 files in
Source/LufsMeter/(MIT, from klangfreund/LUFSMeter) - Target formats: VST3 + AU (macOS only)
- Build:
mkdir build && cd build && cmake .. && cmake --build . - Install:
COPY_PLUGIN_AFTER_BUILD=TRUEin CMake copies to system plugin dirs
MCP Protocol
- Transport: Streamable HTTP (NOT stdio β we're inside a DAW process)
- Endpoint:
POST http://127.0.0.1:16620/mcp - Wire format: JSON-RPC 2.0
- Handshake:
initializeβnotifications/initializedβ then tools/list, tools/call - 5 tools only:
list_plugins,search_param,get_params,set_params,get_analysis - Session: Server returns
Mcp-Session-Idheader on init, client echoes it back - Security: bind 127.0.0.1 only, validate Origin header
Key JUCE APIs (Correct, Verified Against JUCE 8 Source)
addDefaultFormatsToManager(formatManager)β NOT deprecatedaddDefaultFormats()formatManager.createPluginInstanceAsync(desc, sr, bs, callback)β ALWAYS async (AU requires it)instance->enableAllBuses()β MUST call before usingplugin->getParameters()βArray<AudioProcessorParameter*>- Cast to
AudioPluginInstance::HostedParameter*forgetParameterID()(stable string ID) param->beginChangeGesture()/setValueNotifyingHost(val)/endChangeGesture()β for DAW automationjuce::dsp::FFTfor spectral analysis (NOT KissFFT, NOT Gist β those are GPL)juce::dsp::Oversampling<float>for True Peak measurement (4Γ oversample)juce::dsp::WindowingFunction<float>::hannfor FFT windowing
Design Laws (Non-Negotiable)
- Never return all parameters β search first, fetch by ID
- Delta only after param changes
- Single-line compact responses (numbers only)
- Batch operations (set 10 params in one call)
- Silence detection (no analysis if RMS < -60dB)
- Target: <2,000 tokens per full mixing session
Thread Safety Rules
- HTTP handlers run on httplib's thread pool β NOT audio thread
- Use
std::atomic<float>for analysis values queried by HTTP - Use
CriticalSection/ScopedLockfor plugin hot-swap - Never call
getValue()directly from HTTP thread β read from atomic cache - Cap httplib thread pool to 2-4 threads (reduce OS pressure in plugin host)
httplib::Serverlifecycle: constructor starts thread, destructor calls stop()+join()
Sprint Order
- Sprint 1: Empty plugin shell + httplib server responding to curl β START HERE
- Sprint 2: Host Pro-Q 4, route audio, enumerate params
- Sprint 3: MCP JSON-RPC dispatch, all 5 tools working from Claude Code
- Sprint 4: Audio analysis (LUFS, FFT bands, stereo, True Peak)
What NOT To Do
- Don't use
AudioProcessorGraphβ we host ONE plugin, not a graph - Don't use
AudioPluginHost's settings file β use runtime file picker - Don't fork
getdunne/juce-plugin-wrapperβ dead, GPL, JUCE 6 - Don't use Gist or Sound-Analyser code β GPL license conflict (we're already GPL but want MIT deps)
- Don't use stdio MCP transport β plugin is inside DAW, not a subprocess
- Don't use
getParameter(int)/setParameter(int, float)β deprecated, asserts in debug - Don't target Windows yet β macOS only for now
- Don't scan system plugins on load β use file picker for explicit selection
First Steps for Claude Code
- Run
xcode-select --versionto verify Xcode 14+ - Run
cmake --versionto verify CMake 3.22+ - Clone JUCE 8 as submodule:
git submodule add https://github.com/juce-framework/JUCE.git - Download
httplib.hfrom yhirose/cpp-httplib intolibs/ - Download
json.hppfrom nlohmann/json intolibs/ - Create CMakeLists.txt (see ROADMAP.md for skeleton)
- Create Source/ files (empty stubs first)
- Build:
mkdir build && cd build && cmake .. -G Xcode && cmake --build . --config Release - Verify plugin appears in
~/Library/Audio/Plug-Ins/VST3/ - Load in Ableton β verify audio passthrough
- Verify
curl -X POST http://localhost:16620/mcp -d '{}'gets a response
Repo Structure
pluginbridge/
βββ CLAUDE.md β this file (Claude Code reads automatically)
βββ ROADMAP.md β full technical roadmap with code samples
βββ CMakeLists.txt
βββ JUCE/ β git submodule
βββ libs/
β βββ httplib.h β cpp-httplib (yhirose/cpp-httplib)
β βββ json.hpp β nlohmann/json
βββ Source/
βββ PluginBridgeProcessor.h/.cpp
βββ PluginBridgeEditor.h/.cpp
βββ HostedPluginManager.h/.cpp
βββ McpServer.h/.cpp
βββ AudioAnalyser.h/.cpp
βββ LufsMeter/
βββ Ebu128LoudnessMeter.h/.cpp
βββ SecondOrderIIRFilter.h/.cpp