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)