Hugging Face's logo

RAM2118
/
pluginbridge

ml-intern
Model card Files
xet
 Community
pluginbridge / MACHINE-CONTEXT.md
Sitar118
docs: Sprint 7 task + update paths after folder move to AI MUSIC PRODUCTION
29b4c18
preview code
|
Raw
History Blame Contribute Delete
15 kB

Machine Context — Verified System Info + ML Intern Workflow

ML Intern (HuggingFace) writes code but CANNOT run it. Claude Code (local) CAN run code and fills this file with verified facts.

RULE: Before ML Intern writes any platform-specific code, Claude Code fills this file and pushes it. ML Intern reads it first.

SYSTEM INFO (Last verified: 2026-05-17)

Machine: MacBook M4, 24 GB RAM
macOS: macOS 15.x (Sequoia)
Architecture: arm64 (Apple Silicon)
Xcode / CLT: 2410+
Compiler: /usr/bin/cc (Apple Clang)
CMake: 3.28 via pip (⚠️ system CMake 4.x is incompatible with JUCE 8 CMake scripts — do not use)

KEY PATHS

What Path
Home directory /Volumes/T7 Shield/Users/Aditya/ (external T7 Shield SSD)
User VST3 plugins /Volumes/T7 Shield/Users/Aditya/Library/Audio/Plug-Ins/VST3/
System VST3 plugins /Library/Audio/Plug-Ins/VST3/
User AU plugins /Volumes/T7 Shield/Users/Aditya/Library/Audio/Plug-Ins/Components/
System AU plugins /Library/Audio/Plug-Ins/Components/
PluginBridge install ~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3
PluginBridge data ~/Library/PluginBridge/ (safety_db.json, debug.log, blocklist.txt, scan.log)
Build dir /Volumes/T7 Shield/Users/Aditya/Downloads/AI MUSIC PRODUCTION/pluginbridge/build/
Ableton log ~/Library/Preferences/Ableton/Live 12.4/Log.txt
Crash reports ~/Library/Logs/DiagnosticReports/

Note: juce::File::getSpecialLocation(juce::File::userHomeDirectory) returns the T7 Shield path, not /Users/Aditya/.
Both /Library/ and ~/Library/ must be checked to find all installed plugins — most plugins install to both.

CURRENT BUILD STATE (Last updated: 2026-05-17)

Last build: 2026-05-17 (after folder move to AI MUSIC PRODUCTION)
Result: ✅ Clean — [100%] Built target PluginBridge_VST3
Build command:

cd "/Volumes/T7 Shield/Users/Aditya/Downloads/AI MUSIC PRODUCTION/pluginbridge/build"
cmake --build . --target PluginBridge_VST3 -- -j4

Re-cmake needed after fresh clone:

cd "/Volumes/T7 Shield/Users/Aditya/Downloads/AI MUSIC PRODUCTION/pluginbridge/build"
/opt/homebrew/lib/python3.14/site-packages/cmake/data/bin/cmake .. -G 'Unix Makefiles' \
  -DCMAKE_C_COMPILER=/Library/Developer/CommandLineTools/usr/bin/clang \
  -DCMAKE_CXX_COMPILER=/Library/Developer/CommandLineTools/usr/bin/clang++ \
  -DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

RUNTIME STATE (Last verified: 2026-05-17)

What happens when plugin loads (SAFE path):

  1. Picker shows manufacturer tree, user selects plugin
  2. Safety DB checked → if Unknown, Helper --scan runs (waits for live Helper to exit first)
  3. Helper --load spawned for audio routing
  4. Plugin loaded in-process → createEditor() → embedded in PluginBridge editor window

Verified working plugins (with full GUI):

  • FabFilter Pro-Q 4 (737 params, 761×405)
  • Cradle The God Particle (11 params, 666×302)
  • Little MicroShift (4 params, AU, 855×359)
  • LIMITER / Mastering the Mix (13 params, 855×572)

Audio-only (unsafe) plugins:

  • iZotope Ozone 12, Neutron 5, RX components — SIGABRT during scan
  • ANIMATE, Gullfoss, ZENOLOGY, Cradle The God Particle AU version

MCP server: Running on port 16620, verified working
Debug log: ~/Library/PluginBridge/debug.log — timestamped per-session

VST3 BUNDLE STRUCTURE ON THIS MACHINE

Most third-party VST3 bundles do NOT include moduleinfo.json. Only Info.plist is present:

Plugin.vst3/Contents/
├── Info.plist    ← use this for metadata
├── MacOS/
├── PkgInfo
├── Resources/
└── _CodeSignature/

Verified Info.plist fields for manufacturer name:

Field Example Use
NSHumanReadableCopyright "Copyright © 2002-2025 FabFilter" Strip copyright prefix → "FabFilter" ✅ best source
CFBundleGetInfoString "FabFilter Pro-Q 4.02, Copyright © …" Before comma → first word → "FabFilter" ✅
CFBundleIdentifier "com.fabfilter.Pro-Q.Vst3.4" Second segment capitalised → backup
manufacturer FabF 4-char code — useless for display

Known bad vendor values: Pure version strings like "16.7.33.200" appear as "vendor" in some plugins' moduleinfo.json. Detect with containsOnly("0123456789.") and fall back to filename heuristic.

API VERIFICATION TABLE

macOS Private APIs

API Works? Notes
CAContext contextWithCGSConnection:options: ❌ Compiles, runs, no error — but rendering never appears in Ableton's window. See FAILED-APPROACHES #10
CALayerHost (remote layer client) ❌ Same — layer attached, blank. Ableton process isolation blocks cross-process compositor sharing
CGSMainConnectionID() ✅ compiles Returns valid ID but CAContext still doesn't render cross-process
NSMachBootstrapServer ❌ deprecated Not needed; use IPC socket to transfer contextId as string
CARemoteLayerServer ❌ wrong API Does NOT share a hidden NSWindow. See FAILED-APPROACHES #10
posix_spawn ✅ Reliable for spawning Helper from plugin process
shm_open / mmap ✅ Cross-process shared memory for audio — works reliably
sem_open ✅ Named semaphores for audio sync — works reliably

JUCE 8 APIs

API Works? Notes
formatManager.addFormat(new juce::VST3PluginFormat()) ✅ Explicit registration required
formatManager.addFormat(new juce::AudioUnitPluginFormat()) ✅ Explicit registration required
addDefaultFormats() ❌ Deleted in JUCE 8
plugin->createEditor() ✅ Message thread only
juce::Thread::setCurrentThreadPriority() ❌ Removed — use native pthread
getStringWidthFloat() ✅ Use this; getStringWidth() deprecated
getStringWidth() ❌ Deprecated — use getStringWidthFloat()
juce::Rectangle::getTransformToFit() ❌ Does not exist
juce::Array<CustomStruct> initializer list ❌ Not supported — use std::vector<CustomStruct>
addChildComponent(comp) ✅ Adds without forcing visible. Use instead of addAndMakeVisible when component starts hidden
addAndMakeVisible(comp) after setVisible(false) ❌ addAndMakeVisible forces setVisible(true) — invisible comp sits on top eating mouse events
juce::TreeView + TreeViewItem ✅ Working; custom LookAndFeel needed for arrow rendering
juce::File::getSpecialLocation(userHomeDirectory) ✅ Returns T7 Shield path

macOS Gotchas

Issue Notes
MSG_NOSIGNAL Linux only → use signal(SIGPIPE, SIG_IGN) + SO_NOSIGPIPE
Two processes same shm_open name Both crash — scanner must wait for live Helper to exit first
NSApplicationActivationPolicyRegular Steals focus from DAW — use Accessory
activateIgnoringOtherApps:YES Switches away from Ableton — use orderFrontRegardless

ABLETON LOG COMMANDS 

# PluginBridge debug log (live)
tail -f ~/Library/PluginBridge/debug.log

# Crash reports
ls -lt ~/Library/Logs/DiagnosticReports/ | grep -i ableton | head -5

# Helper process
ps aux | grep PluginBridgeHelper

# Blocklist
cat ~/Library/PluginBridge/blocklist.txt 2>/dev/null || echo "(empty)"

# Safety DB
cat ~/Library/PluginBridge/safety_db.json | python3 -m json.tool | head -30

# Test helper manually
~/Library/Audio/Plug-Ins/VST3/PluginBridge.vst3/Contents/Resources/PluginBridgeHelper.app/Contents/MacOS/PluginBridgeHelper --scan "/Library/Audio/Plug-Ins/VST3/FabFilter Pro-Q 4.vst3"; echo "EXIT: $?"

ERROR REPORT TEMPLATE (Claude Code fills when something breaks)

Build Errors 

[Full compiler error — not just the first line. Include file + line number + 5 lines context]
[What the code is trying to do at that line]

Runtime Errors 

[Exact behavior: what user sees, what should happen instead]
[Relevant debug.log lines]
[Helper process state]

Claude Code's Analysis 

[Root cause hypothesis]
[What was already tried]
[Verified API facts]

DO NOT just report "it doesn't work." Always provide the above.

WHO DOES WHAT — READ THIS FIRST 

┌─────────────────────────────────────────────────────────────────┐
│  ML INTERN (HuggingFace)          CLAUDE CODE (local Mac)       │
│  ─────────────────────────        ──────────────────────────    │
│  Writes code                      Runs code                     │
│  Pushes to HF repo                Pulls, builds, tests          │
│  Cannot run anything              Fills this file with facts    │
│  Cannot see the Mac               Is ML Intern's eyes + hands   │
│  Cannot check if it compiles      Reports errors with full diag │
└─────────────────────────────────────────────────────────────────┘

The ML Intern has NO Mac access. It cannot:

  • Run a build to see if code compiles
  • Check if an API exists in the local JUCE version
  • Verify a macOS behavior
  • See what's currently on screen or in the logs
  • Know if a file was committed or is only local

Claude Code is the ML Intern's eyes and hands on the Mac. Every question about "does X work on this machine?" must go through Claude Code.

WORKFLOW 

1. ML Intern is given a task (e.g. "add audio analysis to MCP")
2. If the task touches a new API or macOS behavior:
     ML Intern asks Claude Code: "verify [API]. Fill MACHINE-CONTEXT.md"
     Claude Code tests it, writes result here, pushes
     ML Intern reads this file → writes code based on FACTS
3. ML Intern writes ONLY the files needed for the task
     (see SCOPE RULES below — do NOT touch other files)
4. ML Intern pushes to HF repo
5. Claude Code pulls, builds, tests
6. If error: Claude Code fills ERROR REPORT section — full diagnostic
7. ML Intern reads diagnostic → fixes based on FACTS only
8. Repeat from step 4 until Claude Code confirms: ✅ working

SCOPE RULES — CRITICAL

The single most important rule:

Only modify files that are directly required for the task you were given. If a file is not listed in the task, do NOT touch it.

What "touching" includes:

  • Rewriting the file
  • Removing code from it
  • Replacing its architecture
  • Removing logging/debug calls

Concrete examples of scope violations that broke the project:

Task given Files that should be touched Files that must NOT be touched
"Add AudioAnalyser to MCP" AudioAnalyser.h, McpServer.cpp/.h, PluginBridgeProcessor.h/.cpp (add 3 lines) PluginBridgeEditor.mm, PluginPickerComponent.mm, CMakeLists.txt
"Fix manufacturer names" PluginBridgeProcessor.cpp (getPluginManufacturer) Everything else
"Fix picker duplicates" PluginBridgeProcessor.cpp (getInstalledPluginFiles) Everything else

When in doubt: ask Claude Code which files to touch. Do not guess.

DO NOT REWRITE WORKING FILES

If a file is currently working (confirmed by Claude Code in RUNTIME STATE), do not rewrite it. Work around it, extend it, or add to it. Never replace it.

Files that are locked unless explicitly told to change them:

  • Source/Plugin/PluginBridgeEditor.mm — in-process GUI embedding, took 3 sprints to get right
  • Source/Plugin/PluginPickerComponent.mm — Ableton-style TreeView picker
  • Source/Helper/HelperPluginHost.mm — Helper audio routing + process lifecycle
  • Source/Plugin/HelperConnection.cpp — IPC + shared memory protocol

DO NOT REMOVE LOGGING

PBLOG(...) calls in the processor and editor are how Claude Code diagnoses runtime errors. Never remove PBLOG calls. If you don't understand a log line, leave it.

WHAT TO DO WHEN YOU ARE UNSURE

Stop. Write a message to Claude Code in this format:

QUESTION FOR CLAUDE CODE:
Task: [what you're trying to do]
Uncertainty: [what you don't know]
Files you plan to touch: [list]
Please verify and update MACHINE-CONTEXT.md before I proceed.

Claude Code will test it on the Mac and write the answer here.

ARCHITECTURE — DO NOT CHANGE WITHOUT DISCUSSION

Current architecture is v0.5.2 — hybrid safety-scan:

Safe plugin  → in-process load → createEditor() → GUI embedded in Ableton window ✅
Unsafe plugin → Helper-only  → audio routing only, no GUI (MCP still works) ✅

This took 4 sprints to reach. The following are DEAD ENDS — do not revisit:

Approach Why it failed Documented in
CAContext + CALayerHost Ableton process isolation blocks cross-process compositor FAILED-APPROACHES #10
Floating window from Helper Opens in separate Space in fullscreen Ableton FAILED-APPROACHES #1
PluginDirectoryScanner Executes plugin code during scan → crashes FAILED-APPROACHES #5
Helper-only load (no in-process) Plugin GUI never appears — no createEditor() called This session (2026-05-17)

WORKFLOW (detailed steps) 

1. ML Intern wants to use [API/approach]
2. ML Intern asks: "Claude Code — verify [API] works. Fill MACHINE-CONTEXT.md"
3. Claude Code: writes test, runs it, fills verified API table, pushes
4. ML Intern: reads this file, writes ONLY the required files
5. ML Intern: pushes to HF repo
6. Claude Code: pulls, builds, tests, updates BUILD STATE + RUNTIME STATE sections
7. If error: Claude Code fills ERROR REPORT section with full diagnostic
8. ML Intern reads diagnostic, writes fix based on FACTS
9. Repeat until Claude Code confirms ✅ working

NOTES FOR ML INTERN

  • Never assume an API works — always ask Claude Code to verify first via this file
  • Never use deprecated macOS APIs without Claude Code confirming they still function
  • ObjC++ (.mm) files — only use if Claude Code confirms the ObjC API is available in current SDK
  • JUCE version matters — APIs change between JUCE 7 and 8. Claude Code can check JUCE/modules/ headers
  • Never push more than ONE conceptual change at a time — if it breaks, you know exactly what caused it
  • If you don't know why something failed, DON'T GUESS — ask Claude Code to investigate and fill the error report
  • CAContext/CALayerHost is a dead end — already tried, documented in FAILED-APPROACHES #10. Do not revisit.
  • If you add a new .cpp or .mm file, tell Claude Code — it needs to add it to CMakeLists.txt. You cannot do this yourself (you can't verify the build).