AbletonMCP_AI/AGENTS.md

# 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

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

## Commands

```powershell
# 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:
1. **Kill processes** (Live, Index, Push)
2. **Delete recovery files** (`CrashDetection.cfg`, `CrashRecoveryInfo.cfg`, `Undo.cfg`)
3. **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:**
```python
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:**
1. **Ableton** loads `__init__.py` as a Control Surface → starts TCP server on port 9877
2. **MCP Server** (`server.py`) runs via `mcp_wrapper.py` (stdio transport)
3. Each MCP tool opens a **new TCP connection** to Ableton, sends JSON command, gets response, closes
4. 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
1. **No Placeholders**: Every component does exactly what it claims
2. **No Silent Failures**: Errors are explicit and actionable
3. **Arrangement-First**: All high-level tools create in Arrangement View by default
4. **Dependency Isolation**: Production workflow doesn't require numpy/librosa
5. **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
1. Run migration: `python migrate_to_senior.py --analyze full`
2. Update workflow: Use `build_arrangement_timeline()` instead of `produce_with_library()`
3. Verify: Run `get_arrangement_status()` to confirm clips appear

#### For Developers
1. Use `HybridExtractor` for sample analysis (cache-first)
2. Use `ArrangementRecorder` for any recording operations
3. Use `LiveBridge` to execute engine configs
4. 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
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:**
1. Continue using existing projects without changes
2. For new projects, use `build_arrangement_timeline()` and related new tools
3. 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:**
1. Immediate: Use `build_arrangement_timeline()` for new projects
2. Short-term: Update existing scripts to use new API
3. 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

**Drum Presets:**
- `kick_punch` - Punchy kick compression
- `parallel_drum` - Fast attack, auto release (for parallel processing)

**Bass Presets:**
- `bass_glue` - Glue bass compression

**Vocal Presets:**
- `aggressive_vocal` - Medium attack, fast release

**Bus/Group Presets:**
- `buss_glue` - Standard buss glue
- `buss_tight` - Slow attack, medium release (tight groups)
- `glue_light` - Subtle cohesion
- `glue_heavy` - Strong cohesion

**Master Presets:**
- `master_loud` - Loud master compression

**Special Effects:**
- `pumping_sidechain` - Aggressive pumping effect
- `transparent_leveling` - Subtle, natural dynamics

### Usage Example

```python
# Configure EQ using extended preset
eq_config = EQConfiguration(device_manager)
eq_config.configure_eq_eight(track_index=0, settings={"preset": "kick_sub"})

# Configure compressor using extended preset
comp_settings = CompressionSettings(device_manager)
comp_settings.configure_compressor(track_index=0, preset="parallel_drum")
```

---

## Legacy Design Decisions (v2.x)

- `__init__.py` is all-in-one — Ableton's discovery only reads this file
- One TCP connection per command — no persistent state, no thread queue bugs
- No `request_refresh()` in `update_display()` — causes CPU loop that blocks Ableton

## Workflow

**Kimi** codes features → **Qwen** verifies/compiles/debugs/assigns next sprint

All sprints saved to `AbletonMCP_AI/docs/sprint_N_description.md`

## What NOT to modify

- `libreria/` — user samples (read-only)
- `librerias/` — organized samples (read-only)
- `_Framework/`, `_APC/`, `_Komplete_Kontrol/`, etc. — Ableton's built-in scripts
- Any directory not under `AbletonMCP_AI/`

## OpenCode config

MCP server configured in `~/.config/opencode/opencode.json` pointing to `mcp_wrapper.py`.