File size: 6,143 Bytes
312ea17
 
 
 
 
 
 
 
 
47e9eca
 
 
 
 
 
61c48cb
 
47e9eca
61c48cb
 
47e9eca
 
 
61c48cb
47e9eca
61c48cb
312ea17
 
 
 
 
 
 
47e9eca
 
312ea17
 
 
 
 
 
47e9eca
61c48cb
47e9eca
 
312ea17
 
 
 
47e9eca
312ea17
 
47e9eca
312ea17
47e9eca
 
 
312ea17
 
47e9eca
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
312ea17
61c48cb
312ea17
 
 
 
 
 
 
 
 
47e9eca
 
 
312ea17
 
 
 
47e9eca
 
312ea17
61c48cb
312ea17
 
 
 
47e9eca
 
 
 
 
61c48cb
312ea17
47e9eca
 
61c48cb
312ea17
47e9eca
 
 
 
 
312ea17
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# 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)
```