File size: 6,143 Bytes
312ea17 47e9eca 61c48cb 47e9eca 61c48cb 47e9eca 61c48cb 47e9eca 61c48cb 312ea17 47e9eca 312ea17 47e9eca 61c48cb 47e9eca 312ea17 47e9eca 312ea17 47e9eca 312ea17 47e9eca 312ea17 47e9eca 312ea17 61c48cb 312ea17 47e9eca 312ea17 47e9eca 312ea17 61c48cb 312ea17 47e9eca 61c48cb 312ea17 47e9eca 61c48cb 312ea17 47e9eca 312ea17 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | # 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<AudioProcessorParameter*>`
- 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)
```
|