pluginbridge / CLAUDE.md
RAM2118's picture
Update CLAUDE.md with confirmed project decisions
61c48cb verified
|
Raw History Blame
6.35 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
## 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<AudioProcessorParameter*>`
- 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<float>` for True Peak measurement (4Γ— oversample)
- `juce::dsp::WindowingFunction<float>::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<float>` 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
```