|
Download CLAUDE.md from RAM2118/pluginbridge: direct link, hf CLI and curl.
- Browser
- Download file 6.35 kB
-
https://huggingface.co/RAM2118/pluginbridge/resolve/e99e9f97e97304dfd53cbc1ec4634ede3563ffb9/CLAUDE.md
- Command line
-
hf download hf://RAM2118/pluginbridge@e99e9f97e97304dfd53cbc1ec4634ede3563ffb9/CLAUDE.md
-
curl -L -o CLAUDE.md https://huggingface.co/RAM2118/pluginbridge/resolve/e99e9f97e97304dfd53cbc1ec4634ede3563ffb9/CLAUDE.md
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 | |
| ``` | |