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