156 lines
6.9 KiB
Markdown
156 lines
6.9 KiB
Markdown
# AGENTS.md
|
|
|
|
This repository drives Ableton Live 12 through an MCP server plus a Remote Script.
|
|
Read this file before changing code. See `CLAUDE.md` for expanded context.
|
|
|
|
## What This Repo Is For
|
|
|
|
- Inspect the current Live set
|
|
- Generate arrangements and clips
|
|
- Edit already-open `.als` projects
|
|
- Analyze references and local samples
|
|
- Leave the final set audible, editable, and stable in Ableton
|
|
|
|
**This is not a toy loop generator. Do not optimize for "it returned success"; optimize for runtime truth in Live.**
|
|
|
|
## The Three Layers
|
|
|
|
Keep these separate — most bad fixes happen because someone patched the wrong layer:
|
|
|
|
1. **MCP transport and public tool layer** — `server.py`, `mcp_wrapper.py`
|
|
2. **Socket protocol / runtime bridge** — `abletonmcp_runtime.py`
|
|
3. **Ableton Remote Script / Live API layer** — `abletonmcp_init.py`, Live objects
|
|
|
|
## Active Paths
|
|
|
|
| Purpose | Path |
|
|
|---------|------|
|
|
| MCP wrapper | `...\mcp_wrapper.py` |
|
|
| MCP server | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py` |
|
|
| Song generator | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py` |
|
|
| Reference listener | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py` |
|
|
| Spectral engine | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\spectral_engine.py` |
|
|
| Arrangement intelligence | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\arrangement_intelligence.py` |
|
|
| Melody generator | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\melody_generator.py` |
|
|
| Build spectral index | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\build_spectral_index.py` |
|
|
| Coherence analyzer | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\coherence_analyzer.py` |
|
|
| Bus routing fix | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\bus_routing_fix.py` |
|
|
| Human feel | `...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\human_feel.py` |
|
|
| Runtime shim | `...\abletonmcp_init.py` |
|
|
| Runtime mirror | `...\AbletonMCP_AI\abletonmcp_runtime.py` |
|
|
| Open project target | `C:\Users\ren\Desktop\song Project\song.als` |
|
|
| Ableton log | `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt` |
|
|
|
|
All `...` paths share the root `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`.
|
|
|
|
## Source of Trust Order
|
|
|
|
1. Current Live state
|
|
2. MCP responses and exact tool call results
|
|
3. Ableton log
|
|
4. Code
|
|
5. Old sprint reports or manifests
|
|
|
|
Do not trust a report that says `COMPLETED` if Live still shows an empty or repetitive arrangement.
|
|
|
|
## Build / Test Commands
|
|
|
|
Use PowerShell and absolute Windows paths.
|
|
|
|
### Compile individual files
|
|
|
|
```powershell
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py"
|
|
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
|
|
```
|
|
|
|
### Compile the entire MCP tree
|
|
|
|
```powershell
|
|
python -m compileall "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI"
|
|
```
|
|
|
|
### Run tests
|
|
|
|
```powershell
|
|
# All tests
|
|
python -m unittest discover "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests"
|
|
|
|
# Single test file
|
|
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"
|
|
|
|
# Single test (pytest preferred)
|
|
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py::TestRuntimeTruthHelpers::test_public_set_device_parameter_supports_parameter_name"
|
|
```
|
|
|
|
### Diagnostics
|
|
|
|
```powershell
|
|
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
|
|
netstat -an | findstr 9877
|
|
opencode mcp list --print-logs
|
|
```
|
|
|
|
## High-value test files
|
|
|
|
All under `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\`:
|
|
|
|
- `test_runtime_truth.py` — core MCP tool behaviour
|
|
- `test_selection_coherence.py` — selection and coherence helpers
|
|
- `test_piano_forward.py` — harmonic MIDI placement
|
|
- `test_sample_selector.py` — sample selection logic
|
|
- `test_human_feel.py` — humanization and groove
|
|
- `test_integration.py` — end-to-end integration smoke tests
|
|
- `test_spectral_integration.py` — spectral engine tests (T018-T043)
|
|
- `test_arrangement_intelligence.py` — arrangement logic tests (T086-T094)
|
|
- `test_gain_staging.py` — gain staging tests (T079-T087)
|
|
- `test_melody_generator.py` — melody generation tests (T121-T135)
|
|
- `test_reggaeton_coherence.py` — reggaeton structure coherence
|
|
|
|
## Mandatory Questions Before Patching
|
|
|
|
1. Which file is the **active entrypoint**?
|
|
2. Which **layer** owns the bug (transport, bridge, or Live API)?
|
|
3. Can the bug be reproduced with logs, MCP calls, tests, or Live inspection?
|
|
4. How will you **prove the fix** after the patch?
|
|
|
|
## Coding Rules
|
|
|
|
- Use PowerShell, not bash. Use absolute Windows paths.
|
|
- Standard library imports first, third-party second, local last.
|
|
- No wildcard imports. Use narrow `try/except ImportError` for optional modules.
|
|
- Follow existing file style; do not reformat whole files.
|
|
- Keep functions small, especially those touching Live API objects.
|
|
- Preserve `typing` annotations in MCP/server-side Python.
|
|
- Functions: `snake_case`. Classes: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
|
|
- Return structured dicts from MCP tools. Log with searchable prefixes: `[MCP]`, `[ARRANGEMENT]`, `[HOOK]`, `[COHERENCE]`, `[ERROR]`.
|
|
- Never swallow exceptions around runtime mutations.
|
|
|
|
## Product Rules
|
|
|
|
- Editing an open project is more important than creating a new one.
|
|
- Reduce silent gaps and rigid mirror symmetry.
|
|
- Harmonic MIDI should span the arrangement and fill structural holes.
|
|
- Do not force "piano" as a sound design direction; harmonic MIDI is a musical backbone, not a timbral mandate.
|
|
- Avoid automatic vocals.
|
|
- Avoid visually repetitive 4-second blocks unless explicitly required.
|
|
|
|
## Validation Checklist
|
|
|
|
- [ ] Changed Python files compile without errors
|
|
- [ ] Relevant tests pass
|
|
- [ ] MCP still connects (`get_session_info` and `get_tracks` return valid data)
|
|
- [ ] If editing the open set: inspect tracks, clips, devices after mutation
|
|
- [ ] If claiming coherence improvement: provide before/after evidence
|
|
- [ ] If claiming Arrangement MIDI exists: prove it from Live, not only from a manifest
|
|
|
|
## Anti-Patterns
|
|
|
|
- Do not patch dead or backup files before active entrypoints.
|
|
- Do not trust stale sprint reports over current code and Live state.
|
|
- Do not close a sprint on documentation alone.
|
|
- Do not confuse harmonic MIDI with "must sound like a piano preset".
|
|
- Do not optimize only for manifest metrics while the actual set still sounds empty or repetitive.
|
|
- Do not treat a timeout as definitive proof of failure without inspecting Live. |