# PluginBridge — Claude Code Context ## What This Is A JUCE-based VST3/AU plugin that: 1. Hosts any third-party VST3/AU plugin inside itself (audio passes through) 2. Exposes ALL hosted plugin parameters via a local MCP server (port 16620) 3. Provides real-time audio analysis (LUFS, FFT bands, stereo width) 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 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=TRUE` copies 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 registration - `formatManager.addFormat(new juce::AudioUnitPluginFormat())` — explicit registration - `instance->enableAllBuses()` — MUST call before using - `plugin->getParameters()` → `Array` - Cast to `juce::AudioPluginInstance::HostedParameter*` for `getParameterID()` - `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()` - `juce::dsp::FFT` for spectral analysis - `juce::PluginDirectoryScanner` for system plugin scan - `juce::KnownPluginList` for 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` / `ScopedLock` for plugin hot-swap in processBlock - Cap httplib thread pool to 2 threads - `httplib::Server` lifecycle: 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) ```