Initial commit: AbletonMCP_AI v3.0 Senior Architecture

2026-04-12 22:14:35 -03:00
commit 34f75676ca
119 changed files with 89528 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,342 @@
+# 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`.