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