# 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 ## 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=TRUE` in 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-Id` header 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 deprecated `addDefaultFormats()` - `formatManager.createPluginInstanceAsync(desc, sr, bs, callback)` — ALWAYS async (AU requires it) - `instance->enableAllBuses()` — MUST call before using - `plugin->getParameters()` → `Array` - Cast to `AudioPluginInstance::HostedParameter*` for `getParameterID()` (stable string ID) - `param->beginChangeGesture()` / `setValueNotifyingHost(val)` / `endChangeGesture()` — for DAW automation - `juce::dsp::FFT` for spectral analysis (NOT KissFFT, NOT Gist — those are GPL) - `juce::dsp::Oversampling` for True Peak measurement (4× oversample) - `juce::dsp::WindowingFunction::hann` for 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` for analysis values queried by HTTP - Use `CriticalSection` / `ScopedLock` for 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::Server` lifecycle: constructor starts thread, destructor calls stop()+join() ## Sprint Order 1. **Sprint 1**: Empty plugin shell + httplib server responding to curl ← START HERE 2. **Sprint 2**: Host Pro-Q 4, route audio, enumerate params 3. **Sprint 3**: MCP JSON-RPC dispatch, all 5 tools working from Claude Code 4. **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 1. Run `xcode-select --version` to verify Xcode 14+ 2. Run `cmake --version` to verify CMake 3.22+ 3. Clone JUCE 8 as submodule: `git submodule add https://github.com/juce-framework/JUCE.git` 4. Download `httplib.h` from yhirose/cpp-httplib into `libs/` 5. Download `json.hpp` from nlohmann/json into `libs/` 6. Create CMakeLists.txt (see ROADMAP.md for skeleton) 7. Create Source/ files (empty stubs first) 8. Build: `mkdir build && cd build && cmake .. -G Xcode && cmake --build . --config Release` 9. Verify plugin appears in `~/Library/Audio/Plug-Ins/VST3/` 10. Load in Ableton → verify audio passthrough 11. 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 ```