Hugging Face's logo

RAM2118
/
pluginbridge

ml-intern
Model card Files
xet
 Community
pluginbridge / CLAUDE.md
Sitar118
docs: bump CLAUDE.md to v0.6.0, add Sprint 4-6 features + Sprint 7 warning
6f6ce59
preview code
|
Raw
History Blame Contribute Delete
10.5 kB

PluginBridge — Claude Code Context

What This Is

A JUCE-based VST3/AU plugin that:

  1. Hosts any third-party VST3/AU plugin with full GUI embedded in Ableton's window
  2. Crash-isolates unsafe plugins by loading them in a separate Helper process (audio-only mode)
  3. Exposes ALL hosted plugin parameters via a local MCP server (port 16620)
  4. Audio routes through shared memory (zero added latency)
  5. Any AI that speaks MCP (Claude Code, Codex CLI, Gemini CLI) can control any plugin

Current Status (v0.6.0 — 2026-05-17)

  • ✅ In-process GUI hosting (full GUI for safe plugins)
  • ✅ Safety scanning system (Helper-based pre-test, results cached in safety_db.json)
  • ✅ Audio-only mode for unsafe plugins (iZotope, etc.)
  • ✅ Ableton-style plugin picker (manufacturer TreeView, search, safety badges)
  • ✅ MCP server (port 16620, HTTP JSON-RPC 2.0)
  • ✅ Live spectrum analyzer (LUFS / FFT bands / stereo width / centroid / true peak)
  • ✅ Multi-instance support + channel dropdown (any PluginBridge track addressable by name)
  • ✅ Verified working: Pro-Q 4, God Particle, Little MicroShift, LIMITER
  • ⚠️ Sprint 7 in progress — MCP param ops route through Helper (not in-process) → EQ changes invisible in GUI

Architecture: HYBRID SAFETY-SCAN 

┌─ Ableton Process ──────────────────────────────────────────────┐
│                                                                  │
│  PluginBridge.vst3                                               │
│  ├── PluginBridgeProcessor                                       │
│  │   ├── getInstalledPluginFiles() — scans VST3+AU dirs         │
│  │   ├── getPluginManufacturer()  — reads Info.plist, cached    │
│  │   ├── PluginSafetyDB          — safe/unsafe/unknown JSON DB  │
│  │   ├── startBackgroundScan()   — pre-tests all unknown plugins │
│  │   ├── loadPlugin()            — orchestrates load flow        │
│  │   └── McpServer               — HTTP MCP port 16620          │
│  │                                                               │
│  ├── PluginBridgeEditor                                          │
│  │   ├── PluginPickerComponent   — manufacturer TreeView + search│
│  │   └── pluginEditor            — hosted plugin's own editor   │
│  │                                                               │
│  └── HelperConnection            — IPC + shared memory to Helper│
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
         │ Unix socket + shared memory
         ▼
┌─ PluginBridgeHelper.app (separate process) ─────────────────────┐
│  Bundled in PluginBridge.vst3/Contents/Resources/               │
│                                                                  │
│  Modes:                                                          │
│  --load <path>    Load plugin, route audio via shared memory     │
│  --scan <path>    Test-load plugin, exit 0=safe / crash=unsafe   │
└──────────────────────────────────────────────────────────────────┘

Plugin Load Flow 

User selects plugin in picker
         │
         ▼
loadPlugin() checks PluginSafetyDB
         │
    ┌────┴──────────────────┐
    │                       │
 Unknown                 Safe/Unsafe already known
    │                       │
    ▼                       │
Wait for Helper to exit     │
Spawn: Helper --scan        │
    │                       │
 Crashed? → mark Unsafe     │
 Exit 0?  → mark Safe       │
    │                       │
    └────────────┬──────────┘
                 │
         ┌───────┴────────┐
         │                │
       Safe             Unsafe
         │                │
         ▼                ▼
  Helper --load      Helper --load
  (audio routing)    (audio routing)
         │                │
         ▼                ▼
  loadInProcess()   showAudioOnlyUI()
  createEditor()    (MCP still works)
  embed in window

Key constraint: Only ONE Helper process at a time. Scanner must wait for live Helper to finish before spawning a scan subprocess (same shared memory name → conflict).

File Structure 

pluginbridge/
├── CMakeLists.txt
├── JUCE/                         (git submodule)
├── libs/
│   ├── httplib.h                 (MIT, header-only HTTP server)
│   └── json.hpp                  (MIT, header-only JSON)
├── Source/
│   ├── Plugin/                   ← VST3/AU (runs inside Ableton)
│   │   ├── PluginBridgeProcessor.h/.cpp    — main logic
│   │   ├── PluginBridgeEditor.h/.mm        — editor window
│   │   ├── PluginPickerComponent.h/.mm     — plugin browser UI (new v0.5)
│   │   ├── HelperConnection.h/.cpp         — IPC + shared memory
│   │   ├── McpServer.h/.cpp                — HTTP MCP server
│   │   ├── PluginSafetyDB.h                — safe/unsafe JSON DB
│   │   ├── Blocklist.h                     — persistent crash blocklist
│   │   └── PBLog.h                         — timestamped logger
│   ├── Helper/                   ← Standalone exe (separate process)
│   │   ├── main.cpp              — --load and --scan modes
│   │   ├── HelperPluginHost.h/.mm
│   │   └── HelperIPC.h/.cpp
│   └── Shared/
│       ├── SharedAudioBuffer.h   — shared memory layout
│       ├── IPCProtocol.h         — JSON message formats
│       └── Constants.h
├── CLAUDE.md                     ← this file
├── MACHINE-CONTEXT.md            ← system paths, verified APIs, plugin behaviors
├── SYNC.md                       ← what was built/fixed and when
├── FAILED-APPROACHES.md          ← what didn't work and why
└── ROADMAP.md

Build 

cd "/Volumes/T7 Shield/Users/Aditya/Downloads/AI MUSIC PRODUCTION/pluginbridge/build"
cmake --build . --target PluginBridge_VST3 -- -j4
# Auto-installs to ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3

Two targets:

  • PluginBridge_VST3 — builds + installs both plugin and Helper
  • PluginBridgeHelper — Helper standalone only

CMake 3.28 required (system CMake 4.x incompatible with JUCE 8).

Key Runtime Data

File Purpose
~/Library/PluginBridge/safety_db.json Safe/unsafe status per plugin path+mtime
~/Library/PluginBridge/debug.log Session-tagged timestamped log
~/Library/PluginBridge/scan.log Background scan output
~/Library/PluginBridge/blocklist.txt Plugins that crashed Helper during use

PluginPickerComponent (v0.5)

Source/Plugin/PluginPickerComponent.h/.mm

  • Entry struct: { file, name, manufacturer, blocked, safety }
  • Callbacks: onPluginSelected, onClose, onClearBlocklist, onClearSafetyCache
  • static constexpr int kWidth = 420, kHeight = 500
  • Tree: ManufacturerTreeItem (folder) → PluginTreeItem (leaf, 24px height)
  • Safety badges: Safety::Safe → ✓ green; Safety::Unsafe → audio only orange; blocked → ⚠ red
  • Search: addChildComponent(searchList) — NOT addAndMakeVisible (see FAILED-APPROACHES)
  • Custom TreeLF LookAndFeel overrides drawTreeviewPlusMinusBox for Ableton-style arrows

JUCE 8 APIs — Verified

Working

  • formatManager.addFormat(new juce::VST3PluginFormat())
  • formatManager.addFormat(new juce::AudioUnitPluginFormat())
  • plugin->createEditor() — message thread only
  • plugin->hasEditor()
  • plugin->getParameters() → Array<AudioProcessorParameter*>
  • juce::MessageManager::callAsync(lambda) — cross-thread UI updates
  • addChildComponent(comp) — adds hidden; use instead of addAndMakeVisible when starting invisible
  • juce::TreeView + juce::TreeViewItem with custom LookAndFeel
  • juce::File::findChildFiles(findDirectories, false, "*.vst3")

Broken — Do NOT Use

  • ❌ addDefaultFormats() — deleted in JUCE 8
  • ❌ juce::Thread::setCurrentThreadPriority() — removed, use native pthread
  • ❌ getParameter(int) / setParameter(int, float) — deprecated
  • ❌ getStringWidth() — use getStringWidthFloat()
  • ❌ juce::Rectangle<float>::getTransformToFit() — does not exist
  • ❌ juce::Array<CustomStruct> initializer list — use std::vector<CustomStruct>

macOS Gotchas

  • ❌ MSG_NOSIGNAL — Linux only → signal(SIGPIPE, SIG_IGN) + SO_NOSIGPIPE
  • ❌ Two processes with same shm_open name → both crash — scanner must wait for Helper
  • ❌ addAndMakeVisible(comp) after comp.setVisible(false) → addAndMakeVisible forces visible, invisible comp sits on top intercepting all mouse events → use addChildComponent(comp) instead
  • ❌ CAContext + CALayerHost for cross-process GUI → doesn't work in Ableton (see FAILED-APPROACHES #10)
  • ✅ posix_spawn — safe for spawning from plugin process
  • ✅ shm_open / mmap — reliable cross-process shared memory

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
  • Tools: list_plugins, search_param, get_params, set_params, get_analysis

What NOT To Do

  • Don't load plugins in-process without safety scan — crash-prone plugins (iZotope, some Waves) call abort() and kill Ableton
  • Don't use PluginDirectoryScanner — triggers plugin code on scan → crash
  • Don't spawn Helper --scan while live Helper is running — shared memory conflict → false UNSAFE results
  • Don't use addAndMakeVisible on a component that should start hidden — use addChildComponent
  • Don't try CAContext/CALayerHost for cross-process GUI — see FAILED-APPROACHES #10