pluginbridge / CLAUDE.md
RAM2118's picture
Update CLAUDE.md β€” reflects out-of-process architecture, current status, lessons learned
2aa5050 verified
|
Raw History Blame
6.86 kB

PluginBridge β€” Claude Code Context

What This Is

A JUCE-based VST3/AU plugin that:

  1. Hosts any third-party VST3/AU plugin in a separate crash-safe process
  2. Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
  3. Audio routes through shared memory (zero added latency)
  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
  • Sprint 2: βœ… Done β€” out-of-process plugin hosting, crash-safe, GUI working
  • Sprint 3: Next β€” full MCP client integration test (search/get/set params via curl)
  • Sprint 4: Pending β€” real-time audio analysis (LUFS, FFT)

Architecture: OUT-OF-PROCESS (Crash-Safe)

β”Œβ”€ Ableton Process ─────────────────┐     β”Œβ”€ PluginBridgeHelper Process ─────┐
β”‚                                    β”‚     β”‚                                   β”‚
β”‚  PluginBridge.vst3 (thin shell)    β”‚     β”‚  Standalone executable            β”‚
β”‚  β”œβ”€β”€ McpServer (port 16620)        β”‚     β”‚  β”œβ”€β”€ Loads third-party plugin     β”‚
β”‚  β”œβ”€β”€ HelperConnection              β”‚     β”‚  β”œβ”€β”€ processBlock via shared mem  β”‚
β”‚  β”‚   β”œβ”€β”€ Shared memory (audio)     │◄───►│  β”œβ”€β”€ Shows plugin GUI (floating)  β”‚
β”‚  β”‚   β”œβ”€β”€ Semaphores (sync)         β”‚     β”‚  └── Handles param get/set        β”‚
β”‚  β”‚   └── Unix socket (IPC/cmds)    │◄───►│                                   β”‚
β”‚  └── processBlock():               β”‚     β”‚  If crash β†’ only helper dies      β”‚
β”‚       write shm β†’ signal β†’ wait    β”‚     β”‚  Ableton stays alive              β”‚
β”‚       read output from shm         β”‚     β”‚                                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Why out-of-process: Some plugins (Ozone 12, Kickstart 2) call abort() or show NSAlert during loading, which crashes the entire host process. By running in a separate process, crashes are isolated β€” Ableton never dies.

Build System

  • JUCE 8 via CMake (git submodule at /JUCE)
  • Two build targets:
    • PluginBridge β€” VST3/AU plugin (loaded in DAW)
    • PluginBridgeHelper β€” standalone executable (bundled inside .vst3/Contents/Resources/)
  • cpp-httplib β€” libs/httplib.h (MIT, header-only)
  • nlohmann/json β€” libs/json.hpp (MIT, header-only)
  • Build: cd build && cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++ && cmake --build . --config Release
  • CMake 3.28 required (via pip β€” system CMake 4.x incompatible with JUCE 8)

Project Decisions (Confirmed)

  • Platform: macOS only
  • License: GPL (JUCE GPL mode)
  • VST3 install: ~/Library/Audio/Plug-Ins/VST3/
  • Test plugins: Pro-Q 4, LA-2A, Kickstart 2 (crash test)
  • Xcode CLI tools: 2410+
  • DAW: Ableton Live 12 (primary)

IPC Between Plugin ↔ Helper

  • Audio: POSIX shared memory (shm_open + mmap) β€” zero-copy
  • Sync: Named semaphores (sem_open) β€” ~microsecond wakeup
  • Commands: Unix domain socket, newline-delimited JSON
  • Protocol: See Source/Shared/IPCProtocol.h for all message formats

MCP Protocol

  • Endpoint: POST http://127.0.0.1:16620/mcp
  • Health: GET http://127.0.0.1:16620/health
  • Wire format: JSON-RPC 2.0
  • 5 tools: list_plugins, search_param, get_params, set_params, get_analysis

Plugin GUI Behavior

  • GUI runs in Helper process as a floating window (always-on-top)
  • Uses NSApplicationActivationPolicyAccessory β€” no Dock icon, no focus steal
  • orderFrontRegardless β€” shows without switching away from Ableton
  • Toggle via "Open GUI" / "Close GUI" button in PluginBridge's panel
  • If plugin crashes β†’ GUI disappears, PluginBridge shows "Plugin crashed - click Reload"

Key JUCE 8 APIs (Verified Working)

  • formatManager.addFormat(new juce::VST3PluginFormat()) β€” explicit registration
  • formatManager.addFormat(new juce::AudioUnitPluginFormat()) β€” explicit registration
  • instance->enableAllBuses() β€” MUST call before using
  • plugin->getParameters() β†’ Array<AudioProcessorParameter*>
  • dynamic_cast<juce::AudioPluginInstance::HostedParameter*>(param) for stable ID
  • param->beginChangeGesture() / setValueNotifyingHost(val) / endChangeGesture()
  • juce_add_gui_app() for Helper target in CMake

Key JUCE 8 APIs (BROKEN β€” do NOT use)

  • ❌ addDefaultFormats() β€” deleted
  • ❌ juce::Thread::setCurrentThreadPriority() β€” removed, use native pthread
  • ❌ getParameter(int) / setParameter(int, float) β€” deprecated, asserts

macOS-Specific Gotchas (Learned the Hard Way)

  • ❌ MSG_NOSIGNAL β€” doesn't exist on macOS. Use signal(SIGPIPE, SIG_IGN) + SO_NOSIGPIPE
  • ❌ Plugin scanning in background thread β€” some plugins show NSAlert β†’ crash. Solution: don't scan at all, just list .vst3/.component files from disk
  • ❌ NSApplicationActivationPolicyRegular β€” steals focus from DAW. Use Accessory (policy 1)
  • ❌ activateIgnoringOtherApps:YES β€” switches away from Ableton. Use orderFrontRegardless instead
  • βœ… posix_spawn β€” works for launching helper from within a plugin process

File Structure

pluginbridge/
β”œβ”€β”€ CMakeLists.txt              (builds PluginBridge + PluginBridgeHelper)
β”œβ”€β”€ JUCE/                       (git submodule)
β”œβ”€β”€ libs/
β”‚   β”œβ”€β”€ httplib.h
β”‚   └── json.hpp
β”œβ”€β”€ Source/
β”‚   β”œβ”€β”€ Plugin/                 ← VST3/AU (runs inside Ableton)
β”‚   β”‚   β”œβ”€β”€ PluginBridgeProcessor.h/.cpp
β”‚   β”‚   β”œβ”€β”€ PluginBridgeEditor.h/.cpp
β”‚   β”‚   β”œβ”€β”€ HelperConnection.h/.cpp
β”‚   β”‚   └── McpServer.h/.cpp
β”‚   β”œβ”€β”€ Helper/                 ← Standalone exe (separate process)
β”‚   β”‚   β”œβ”€β”€ main.cpp
β”‚   β”‚   β”œβ”€β”€ HelperPluginHost.h/.cpp
β”‚   β”‚   └── HelperIPC.h/.cpp
β”‚   └── Shared/                 ← Used by both targets
β”‚       β”œβ”€β”€ SharedAudioBuffer.h
β”‚       β”œβ”€β”€ IPCProtocol.h
β”‚       └── Constants.h
β”œβ”€β”€ CLAUDE.md
β”œβ”€β”€ ROADMAP.md
└── SYNC.md

What NOT To Do

  • Don't load plugins in-process β€” crashes DAW with misbehaving plugins
  • Don't use PluginDirectoryScanner β€” triggers plugin code execution β†’ crash
  • Don't use addDefaultFormats() β€” deleted in JUCE 8
  • Don't steal focus when showing GUI β€” use Accessory policy
  • Don't use MSG_NOSIGNAL β€” macOS doesn't have it
  • Don't use juce::Thread::setCurrentThreadPriority() β€” removed in JUCE 8