|
Download CLAUDE.md from RAM2118/pluginbridge: direct link, hf CLI and curl.
- Browser
- Download file 6.14 kB
-
https://huggingface.co/RAM2118/pluginbridge/resolve/1dd0405171bf6efd5a8dfd67bc5b5d3a24dc7aee/CLAUDE.md
- Command line
-
hf download hf://RAM2118/pluginbridge@1dd0405171bf6efd5a8dfd67bc5b5d3a24dc7aee/CLAUDE.md
-
curl -L -o CLAUDE.md https://huggingface.co/RAM2118/pluginbridge/resolve/1dd0405171bf6efd5a8dfd67bc5b5d3a24dc7aee/CLAUDE.md
6.14 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
Current Status
- Sprint 1: β Done β plugin shell + MCP server responding
- Sprint 2: β Done β hosts Pro-Q 4 (737 params), routes audio, MCP tools wired
- Sprint 3: Next β full MCP client integration test from Claude Code
- Sprint 4: Pending β real-time audio analysis
Project Decisions (Confirmed)
- Platform: macOS only (for now)
- License: GPL (JUCE GPL mode β no commercial license needed, doesn't hamper project)
- VST3 install path:
~/Library/Audio/Plug-Ins/VST3/ - AU install path:
~/Library/Audio/Plug-Ins/Components/ - Test plugins: FabFilter Pro-Q 4 (EQ, 737 params), LA-2A compressor (fewer params)
- Xcode: CLI tools 2410+ (no full Xcode.app needed)
- CMake: 3.28 via pip (system CMake 4.x incompatible with JUCE 8)
- DAW: Ableton Live (primary), Logic Pro (secondary AU test)
- Build generator: Unix Makefiles or Ninja (NOT Xcode generator β no Xcode.app)
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 β hostManager.processBlock(buffer, midi)
β output (audio routed through hosted plugin)
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) β Sprint 4 - Target formats: VST3 + AU (macOS only)
- Build:
cd build && cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++ && cmake --build . --config Release - Install:
COPY_PLUGIN_AFTER_BUILD=TRUEcopies to~/Library/Audio/Plug-Ins/VST3/
MCP Protocol
- Transport: Streamable HTTP (NOT stdio β we're inside a DAW process)
- Endpoint:
POST http://127.0.0.1:16620/mcp - Health check:
GET http://127.0.0.1:16620/health - Wire format: JSON-RPC 2.0
- Handshake:
initializeβnotifications/initializedβ then tools/list, tools/call - 5 tools:
list_plugins,search_param,get_params,set_params,get_analysis
Key JUCE 8 APIs (Verified β these WORK)
formatManager.addFormat(new juce::VST3PluginFormat())β explicit registrationformatManager.addFormat(new juce::AudioUnitPluginFormat())β explicit registrationinstance->enableAllBuses()β MUST call before usingplugin->getParameters()βArray<AudioProcessorParameter*>- Cast to
juce::AudioPluginInstance::HostedParameter*forgetParameterID() param->beginChangeGesture()/setValueNotifyingHost(val)/endChangeGesture()juce::dsp::FFTfor spectral analysisjuce::PluginDirectoryScannerfor system plugin scanjuce::KnownPluginListfor storing scan results
Key JUCE 8 APIs (BROKEN β do NOT use)
- β
addDefaultFormats()β deleted in JUCE 8, use explicit addFormat() calls - β
addDefaultFormatsToManager()β also deleted - β
getParameter(int)/setParameter(int, float)β deprecated, asserts
Plugin Discovery UX
- Click "Select Plugin..." button β first click triggers background scan
- Button shows "Scanning..." while scanning (background thread, non-blocking)
- After scan: popup menu grouped by manufacturer β plugin name
- Subsequent clicks: instant menu (cached scan results)
- NO file browser β clean DAW-style UX
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
- Plugin scan runs in background thread β NOT message thread (crashes DAW otherwise)
- Use
CriticalSection/ScopedLockfor plugin hot-swap in processBlock - Cap httplib thread pool to 2 threads
httplib::Serverlifecycle: constructor starts thread, destructor calls stop()+join()
What NOT To Do
- Don't use
AudioProcessorGraphβ we host ONE plugin, not a graph - Don't scan plugins on editor open β scan only on button click, in background thread
- Don't use
addDefaultFormats()β deleted in JUCE 8 - Don't use stdio MCP transport β plugin is inside DAW, not a subprocess
- Don't target Windows yet β macOS only for now
Repo Structure
pluginbridge/
βββ CLAUDE.md β this file
βββ ROADMAP.md β full technical roadmap
βββ SYNC.md β coordination between HF Claude and Claude Code
βββ CMakeLists.txt β JUCE 8 CMake (LANGUAGES C CXX)
βββ .gitignore
βββ JUCE/ β git submodule
βββ libs/
β βββ README.md β download instructions
β βββ httplib.h β cpp-httplib
β βββ json.hpp β nlohmann/json
βββ Source/
βββ PluginBridgeProcessor.h/.cpp β main AudioProcessor, owns HostedPluginManager + McpServer
βββ PluginBridgeEditor.h/.cpp β GUI: status + plugin selector popup menu
βββ HostedPluginManager.h/.cpp β loads VST3/AU, enumerates params, routes audio
βββ McpServer.h/.cpp β HTTP server, JSON-RPC dispatch, 5 tools
βββ AudioAnalyser.h/.cpp β stub (Sprint 4)