renato97/AbletonMCP_AI

Fork 0

Files

Administrator 34f75676ca Initial commit: AbletonMCP_AI v3.0 Senior Architecture

2026-04-12 22:14:35 -03:00

12 KiB

Raw Blame History

AGENTS.md - AbletonMCP_AI

Project

MCP-based system that lets AI agents control Ableton Live 12 Suite via TCP socket.

Note: This project uses the Senior Architecture (v3.0). See below for migration details.

Critical Rules

NEVER touch libreria/ or librerias/ — user's 511 sample library
Overwrite files, never delete+create — prevents accidental data loss
No debug .md files in project root — all go to AbletonMCP_AI/docs/
Compile after every change: python -m py_compile "<absolute_path>"
Restart Ableton Live after changes to __init__.py (no hot-reload)

Commands

# Compile check (always after edits)
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\mcp_server\server.py"

# Verify Ableton is listening
netstat -an | findstr 9877

# Test MCP server directly
python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"

Skills Reference

Skill 1: Reinicio Correcto de Ableton

File: AbletonMCP_AI/docs/skill_reinicio_ableton.md

Proceso de 3 pasos para reiniciar Ableton limpiamente:

Kill processes (Live, Index, Push)
Delete recovery files (CrashDetection.cfg, CrashRecoveryInfo.cfg, Undo.cfg)
Start Ableton + verify TCP 9877

When to use: After modifying __init__.py, when changes don't reflect, after crashes.

Skill 2: Producción Senior de Audio

File: AbletonMCP_AI/docs/skill_produccion_audio.md

Flujo profesional completo para producción con inyección automática:

5 Métodos Automáticos:

M1: track.insert_arrangement_clip() (Live 12+ direct)
M2: track.create_audio_clip() (Live 11+ direct)
M3: arrangement_clips.add_new_clip() (Live 12+ API)
M4: Session → duplicate_clip_to_arrangement (legacy)
M5: Session → Recording (universal fallback)

Zero configuración manual - Sistema elige automáticamente.

Usage:

ableton-live-mcp_create_arrangement_audio_pattern(
    track_index=3,
    file_path="C:\\...\\kick 1.wav",
    positions=[0, 4, 8, 12],
    name="KickPattern"
)

Workflow: Health check → Library scan → Create tracks → Inject audio → Verify arrangement.

Critical: Always use Skill 1 (restart) before starting production with Skill 2 if __init__.py was modified.

Architecture

Legacy Architecture (v2.x - Deprecated)

The original architecture focused on Session View as the primary workflow:

AbletonMCP_AI/
├── __init__.py          # Remote Script — ALL Live API code here (~300 lines)
├── README.md            # Project documentation
├── docs/                # Sprints and project docs only
└── mcp_server/
    ├── server.py        # FastMCP server over stdio (~300 lines)
    └── engines/         # Music logic (sample_selector, song_generator)
mcp_wrapper.py           # Launcher for OpenCode

Legacy workflow:

Ableton loads __init__.py as a Control Surface → starts TCP server on port 9877
MCP Server (server.py) runs via mcp_wrapper.py (stdio transport)
Each MCP tool opens a new TCP connection to Ableton, sends JSON command, gets response, closes
Mutations to Live are queued in _pending_tasks and drained by update_display()

Senior Architecture (v3.0)

Overview

The Senior Architecture represents a complete redesign of AbletonMCP_AI with:

Arrangement View as primary workflow (not Session View)
SQLite-based metadata store (no numpy required for production)
Robust state machine for arrangement recording
LiveBridge for real execution of engine configurations
Explicit API design without ambiguous names

Key Principles

No Placeholders: Every component does exactly what it claims
No Silent Failures: Errors are explicit and actionable
Arrangement-First: All high-level tools create in Arrangement View by default
Dependency Isolation: Production workflow doesn't require numpy/librosa
Musical Timing: All timing uses bars/beats, not wall-clock

New Components

1. Metadata Store (metadata_store.py)

SQLite database storing pre-analyzed sample features:

511 samples analyzed once, reused forever
0 runtime dependency on numpy/librosa for queries
Fast BPM/key/spectral feature lookups

2. Hybrid Extractor (abstract_analyzer.py)

Abstract feature extraction with multiple implementations:

LibrosaExtractor: Full analysis (requires numpy)
DatabaseExtractor: Fast lookups (no dependencies)
HybridExtractor: Cache-first with fallback analysis

3. Arrangement Recorder (arrangement_recorder.py)

Robust state machine for Session→Arrangement recording:

7 states: IDLE → ARMED → PRE_ROLL → RECORDING → COOLDOWN → COMPLETED/FAILED
Musical quantization (waits for bar boundaries)
Verification: Compares before/after clip sets
Progress callbacks and error handling

4. LiveBridge (live_bridge.py)

Direct Ableton Live API execution:

Applies mixing_engine configurations for real
Writes automation envelopes to clips
Creates Arrangement clips directly
Bus/return routing with actual track modifications

5. Integration Coordinator (integration.py)

Central coordinator wiring all components:

Dependency detection and auto-configuration
High-level operations (build_timeline, record_session)
Graceful degradation with clear mode reporting

API Changes

Deprecated (Session-View-First)

produce_with_library() - Old: Creates Session, optional Arrangement
produce_reggaeton() - Old: Session View only
build_arrangement_structure() - Old: Actually builds Session scenes

New (Arrangement-First)

build_arrangement_timeline() - Creates clips directly at bar positions
create_section_at_bar() - Places intro/verse/chorus at specific bars
create_arrangement_track() - Timeline-ready track creation
arrange_record_start() - Robust recording with state machine

Migration Guide

For Users

Run migration: python migrate_to_senior.py --analyze full
Update workflow: Use build_arrangement_timeline() instead of produce_with_library()
Verify: Run get_arrangement_status() to confirm clips appear

For Developers

Use HybridExtractor for sample analysis (cache-first)
Use ArrangementRecorder for any recording operations
Use LiveBridge to execute engine configs
Query SampleMetadataStore for sample features (no numpy)

File Structure Changes

AbletonMCP_AI/
├── mcp_server/
│   ├── engines/
│   │   ├── __init__.py (updated exports)
│   │   ├── metadata_store.py (NEW)
│   │   ├── abstract_analyzer.py (NEW)
│   │   ├── arrangement_recorder.py (NEW)
│   │   ├── live_bridge.py (NEW)
│   │   ├── sample_selector.py (updated)
│   │   └── ...
│   ├── integration.py (NEW)
│   ├── migrate_library.py (NEW)
│   ├── migrate_to_senior.py (NEW)
│   ├── test_arrangement.py (NEW)
│   └── server.py (updated)
├── __init__.py (updated)
└── AGENTS.md (this file)

Testing

Run verification:

python -m test_arrangement --test-all

Expected results:

✓ Arrangement clips created directly (no Session intermediate)
✓ No numpy required for sample queries
✓ Recording uses musical timing (bars/beats)
✓ Post-recording verification confirms clips exist

Backward Compatibility

The Senior Architecture maintains backward compatibility with existing workflows:

Old tools still work: produce_with_library(), produce_reggaeton(), etc. continue to function
Session View not removed: Clips can still be created and fired in Session View
Gradual migration: Users can mix old and new API calls during transition

However, old tools are deprecated and will be removed in v4.0:

They may have reduced performance compared to new Arrangement-first tools
They won't benefit from new features like the metadata store
Documentation and examples will focus on new API

Recommended approach:

Continue using existing projects without changes
For new projects, use build_arrangement_timeline() and related new tools
Migrate critical existing projects when convenient

Current Status

Completed:

✅ SQLite metadata store
✅ Hybrid extractor architecture
✅ ArrangementRecorder state machine
✅ LiveBridge implementation
✅ New Arrangement-first API tools
✅ Integration coordinator
✅ Migration tools
✅ Extended EQ and Compressor presets (Agente 10)

In Progress:

🔄 Comprehensive testing
🔄 Performance optimization

Migration Path:

Immediate: Use build_arrangement_timeline() for new projects
Short-term: Update existing scripts to use new API
Long-term: Deprecate Session-View-first tools

Extended EQ and Compressor Presets (Agente 10)

EQ Presets

Drum Presets:

kick - Standard kick drum EQ
kick_sub - Sub-bass emphasis at 60Hz (for heavy kicks)
kick_punch - Beater punch at 3kHz (for clicky kicks)
snare - Standard snare EQ
snare_body - Body emphasis at 200Hz (full snare)
snare_crack - Crack at 5kHz (snappy snare)

Bass Presets:

bass - Standard bass EQ
bass_clean - Clean bass with controlled mids
bass_dirty - Bass with midrange grit

Synth & Melodic Presets:

synth - Standard synth EQ
synth_air - 10kHz air boost (bright synths)
pad_warm - Low shelf boost (warm pads)
vocal_presence - 3-5kHz presence boost (vocals/adlibs)

Master Presets:

master - Standard master EQ
master_tame - High shelf taming (for bright mixes)

Compressor Presets