# ROADMAP - AbletonMCP_AI v3.0 (Senior Architecture)

> **Generado:** 2026-04-13
> **Último sprint completado:** Sprint 7 (Session View Máster)
> **Sprint activo:** Sprint 8 (MIDI Instrument Loading + BPM Integration)

---

## 📊 Estado General del Proyecto

| Sprint | Nombre | Estado | Fecha |
|--------|--------|--------|-------|
| Sprint 1 | Librería Análisis Espectral | ✅ Completado | 2025 |
| Sprint 2 | 100 Tareas Calidad Profesional | ✅ Completado | 2025 |
| Sprint 3 | Producción Completa | ✅ Completado | 2025 |
| Sprint 4 | Bloque A + B (Mixing/Mastering) | ✅ Completado | 2025 |
| Sprint 5-6 | Session View Professional | ✅ Completado | 2025 |
| Sprint 7 | Session Máster (13 Scenes) | ✅ Completado | 2026-04-13 |
| **Sprint 8** | **MIDI Loading + BPM Integration** | 🔄 **Activo** | - |
| Sprint 9 | M4L / Arrangement Recording Auto | 📝 Planificado | - |
| Backlog | Warp, Vocals, Stems, Reference | 📋 Backlog | - |

---

## 🏁 Sprints Completados

### Sprint 1: Librería Análisis Espectral
**Archivos:** `docs/sprint_1_libreria_analisis_espectral.md`

- [x] Motor de análisis espectral con MFCC
- [x] Caché de embeddings para reutilización
- [x] Indexación de 375+ samples
- [x] Sistema de coherencia espectral

### Sprint 2: 100 Tareas Calidad Profesional
**Archivos:** `docs/sprint_2_100_tareas_calidad_profesional.md`

- [x] 50+ production engines
- [x] Extended EQ presets (15+ presets)
- [x] Extended compressor presets (12+ presets)
- [x] Bus architecture (Kick, Snare, Drums, Bass, Synths, FX)
- [x] Parallel compression NY-style
- [x] Auto gain staging
- [x] Master chain profesional

### Sprint 3: Producción Completa
**Archivos:** `docs/sprint_3_produccion_completa.md`

- [x] `generate_intelligent_track` - one-prompt complete track
- [x] `generate_expansive_track` - 12+ samples per category
- [x] `build_song` - full arrangement with sections
- [x] `produce_reggaeton` - complete reggaeton production
- [x] Coherence scoring (0.90+ threshold)

### Sprint 4: Bloque A + B (Mixing/Mastering)
**Archivos:** `docs/sprint_4_bloque_A.md`, `docs/sprint_4_bloque_B.md`

- [x] Mixing engine completo
- [x] EQ8 configuration profesional
- [x] Compressor presets por categoría
- [x] Sidechain automático
- [x] Parallel compression bus
- [x] Master chain con limiter

### Sprint 6: Session View Professional
**Archivos:** `docs/sprint_6_session_view_professional.md`

- [x] Session View como workflow principal
- [x] Scene naming y organización
- [x] Energy-based sample selection
- [x] Variation engine por sección

### Sprint 7: Session View Máster (13 Scenes)
**Archivos:** `docs/sprint_7_session_master.md`, `docs/sprint_7_implementation.md`
**Estado:** ✅ Completado 2026-04-13

- [x] 13 scenes completas: Intro → Verse A/B/C → Pre-Chorus → Chorus A/B/C → Bridge → Build Up → Final Chorus → Outro → End
- [x] 20 tracks: 14 audio + 6 MIDI (Kick layers, Snare layers, Drum Loop, Piano/Chords, Lead, Bass)
- [x] 100+ samples únicos por escena con energy-based selection
- [x] BPM coherence: Librosa analysis + spectral embeddings
- [x] Humanization: Per-instrument profiles con timing/velocity variation
- [x] Warp automation: Complex Pro para samples no matching
- [x] `produce_13_scenes()` tool funcional
- [x] Sistema de progresiones armónicas (16 progresiones con tensión)
- [x] SentimientoLatino2025 collection: 658 samples integrados

---

## 🔄 Sprint 8 (ACTIVO): MIDI Instrument Loading + BPM Integration

**Dueño:** Qwen + Kimi
**Meta:** MIDI tracks suenan sin intervención manual

### Feature 1: MIDI Instrument Loading - Robust Solution

| Tarea | Estado | Notas |
|-------|--------|-------|
| Device presence verification con retry (10 × 500ms) | ⚠️ Parcial | Polling 3s implementado, no 100% |
| Fallback chain: Wavetable → Operator → Analog → Simpler | ❌ Pendiente | |
| "Instrument Rack" preset approach | ❌ Pendiente | |
| `live.object` API para device creation directa | ❌ Pendiente | Investigar si disponible |
| M4L bridge (last resort) | 📋 Evaluado | Solo si Python falla consistentemente |

**Criterios de Aceptación:**
- [ ] `insert_device` retorna `device_inserted: true` Y `device_count > 0`
- [ ] Funciona para: Wavetable, Operator, Analog, Electric, Tension, Collision
- [ ] Máximo 5 segundos de espera total

**Workaround actual:** Polling loop con 3 segundos timeout, 15 intentos × 200ms

### Feature 2: BPM Analyzer Integration

| Tarea | Estado | Notas |
|-------|--------|-------|
| Run `analyze_all_bpm()` en 800 samples (~30 min) | ❌ Pendiente | Una vez, cache permanente |
| Store results en `metadata_store` tabla `samples_bpm` | ❌ Pendiente | |
| Modificar `produce_13_scenes` para usar BPM-coherent samples | ❌ Pendiente | |
| Agregar parámetro `force_bpm_coherence` a tools de producción | ❌ Pendiente | |
| Crear tool `get_bpm_recommendations()` | ❌ Pendiente | |

**Criterios de Aceptación:**
- [ ] 800 samples tienen BPM en database
- [ ] Producir a 95 BPM usa solo samples 90-100 BPM (±5 tolerancia)
- [ ] Samples fuera de tolerancia hacen auto-warp con Complex Pro

**Archivos listos:** `bpm_analyzer.py`, `spectral_coherence.py` (motores creados, no integrados)

### Feature 3: Single Drum Loop Architecture

| Tarea | Estado | Notas |
|-------|--------|-------|
| Crear `extend_loop_to_duration()` | ❌ Pendiente | |
| Usar `clip.loop_end` para extender sin re-trigger | ❌ Pendiente | |
| Desactivar sample rotation para drumloop | ❌ Pendiente | |
| Harmony layers (piano, pads) cambian por escena | ❌ Pendiente | |
| Drum loop constante, variar harmony/progressions | ❌ Pendiente | |

**Criterios de Aceptación:**
- [ ] Un drum loop toca continuamente por toda la duración de la canción
- [ ] Harmony/progressions cambian por escena (Intro≠Verse≠Chorus)
- [ ] Sin cortes/glitches audibles en el drum loop

---

## 📝 Sprint 9 (PLANIFICADO): M4L / Arrangement Recording Automation

### Feature 4: Max for Live Integration (Opcional)

| Tarea | Estado | Notas |
|-------|--------|-------|
| Crear M4L device "InstrumentLoader" | 📋 Evaluado | Solo si Python solución falla |
| OSC listener `/loadinstrument track_index, instrument_name` | ❌ Pendiente | |
| `live.object` para insert device directo | ❌ Pendiente | Más confiable que Python |
| Confirmación OSC de vuelta | ❌ Pendiente | |

**Decisión:** Solo implementar si solución Python falla consistentemente

### Feature 5: Arrangement Recording Automation

| Tarea | Estado | Notas |
|-------|--------|-------|
| `arrangement_overdub` + scene firing + time-based stop | ❌ Pendiente | |
| O `duplicate_clip_to_arrangement` por clip | ❌ Pendiente | Si API disponible |
| Tool `auto_record_session(duration_bars=70)` | ❌ Pendiente | |
| Post-recording: verificar clips en Arrangement | ❌ Pendiente | |

**Workaround actual:** Usuario presiona F9 manualmente

---

## 📋 Backlog (Prioridad Media)

### Feature 6: Advanced Warp Modes

| Tarea | Estado |
|-------|--------|
| Auto-detect best warp mode (Complex Pro vs Beats vs Tones) | ❌ |
| Per-sample warp configuration en metadata | ❌ |
| Real-time warp quality monitoring | ❌ |

### Feature 7: Stem Export Automation

| Tarea | Estado |
|-------|--------|
| `render_stems()` con track groups (Drums, Bass, Music, FX) | ❌ |
| Individual stems + mixed stem option | ❌ |
| Naming convention: `ProjectName_StemName.wav` | ❌ |

### Feature 8: Reference Track Matching

| Tarea | Estado |
|-------|--------|
| Terminar `produce_from_reference()` | ❌ |
| Análisis espectral de referencia vs generado | ❌ |
| Auto-adjust EQ/compression para match | ❌ |

### Feature 9: Batch Production

| Tarea | Estado |
|-------|--------|
| `batch_produce(count=5)` - 5 variaciones del mismo prompt | ❌ |
| Cada una con random seed diferente para samples | ❌ |
| Comparar y rankear por coherence score | ❌ |

---

## 🐛 Bug Tracker

### Bugs Activos

| ID | Bug | Severidad | Estado | Archivo | Notas |
|----|-----|-----------|--------|---------|-------|
| B001 | `device_count` queda en 0 después de `insert_device` | **Crítico** | ⚠️ Workaround | `__init__.py`, `server.py` | Polling ayuda pero no 100% |
| B002 | `apply_human_feel` falla sin numpy | Medio | ❌ Broken | `engines/` | Necesita numpy para humanization |
| B003 | Time stretch clip API mismatch | Medio | ❌ Broken | `server.py` | Signature mismatch en `get_notes` |

### Bugs Resueltos

| ID | Bug | Severidad | Estado | Resolución |
|----|-----|-----------|--------|------------|
| B004 | `analyze_library` typo cache path | Bajo | ✅ Fixed | Corregido `analyzer._cache_file` → `analyzer.cache_path` |
| B005 | Drum loop BPM mismatch | Bajo | ✅ Auto-handled | `warp_clip_to_bpm` aplica Complex Pro automáticamente |

### Bugs Cosméticos

| ID | Bug | Severidad | Estado | Notas |
|----|-----|-----------|--------|-------|
| B006 | `duplicate_project` renombra tracks raro | Bajo | ✅ Working | Issue cosmético solamente |

---

## ⚡ Performance Optimizations

| Optimización | Estado | Impacto |
|--------------|--------|---------|
| Parallel sample analysis (4 threads para 800 samples) | ❌ | Reducir 30min → ~8min |
| Lazy loading de engines pesados (librosa, sklearn) | ❌ | Menor startup time |
| Cache embeddings como binary blobs (no JSON) | ❌ | Menor uso de RAM |
| Incremental BPM analysis (solo nuevos samples) | ❌ | No re-analizar existentes |

---

## 📚 Documentación Pendiente

| Documento | Estado | Ubicación |
|-----------|--------|-----------|
| `docs/sprint_8_midi_loading.md` | ❌ | Technical deep dive |
| `docs/sprint_8_bpm_integration.md` | ❌ | BPM system guide |
| Actualizar `API_REFERENCE_PRO.md` con 5 nuevas tools | ❌ | API docs |
| Troubleshooting guide para MIDI issues | ❌ | User docs |
| Video/GIF demos de Session View workflow | ❌ | Media |

---

## 🎯 Próximos Pasos Inmediatos

1. **Sprint 8 - Fix MIDI loading:** Implementar retry logic robusto con fallback chain
2. **Sprint 8 - BPM integration:** Correr análisis en 800 samples (una vez, ~30 min)
3. **Sprint 8 - Single drum loop:** Extender loop 1:30 sin glitches
4. **Verificar:** Compilar todo + restart Ableton + health check
5. **Decidir:** Sprint 9 = M4L bridge o Arrangement recording automation

---

## 📈 Métricas de Progreso

| Métrica | Sprint 7 | Sprint 8 (meta) | Sprint 9 (meta) |
|---------|----------|-----------------|-----------------|
| MCP Tools | 114+ | 119+ | 124+ |
| Samples analizados | 735+ | 800+ | 800+ |
| MIDI tracks funcionales | 6/6 (manual) | 6/6 (auto) | 6/6 (auto) |
| Arrangement recording | Manual (F9) | Manual (F9) | Auto |
| BPM coherence | Parcial | Completo | Completo |
| Bugs críticos | 1 activo | 0 activos | 0 activos |
