pluginbridge / CLAUDE.md
RAM2118's picture
Update CLAUDE.md β€” reflect Sprint 2 complete, fix API notes, update status
47e9eca verified
|
Raw History Blame
6.14 kB
# 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)
```