Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

2026-04-08 17:58:47 -03:00
parent c9d3528900
commit 6d080d43b3
372 changed files with 189715 additions and 8590 deletions
--- a/docs/REPORTE_FALLO_MCP_SONG_GENERATION.md
+++ b/docs/REPORTE_FALLO_MCP_SONG_GENERATION.md
@@ -0,0 +1,475 @@
+# REPORTE TÉCNICO: FALLA EN GENERACIÓN DE CANCIÓN MCP
+
+**Fecha:** 2026-04-07  
+**Proyecto:** AbletonMCP-AI Song Generation  
+**Solicitante:** Antigravity (arquitecto)  
+**Executor:** Claude (OpenCode/GLM)  
+**Reviewer asignado:** Codex
+
+---
+
+## 1. RESUMEN EJECUTIVO
+
+**Objetivo:** Crear canción reggaeton completa de 1:30 (142 beats @ 95 BPM) usando TODAS las herramientas MCP disponibles.
+
+**Resultado:** **FALLA PARCIAL** - Canción generada pero con gaps críticos que la hacen inusable.
+
+**Estado actual:**
+- drum_coverage_ratio: **44.4%** (objetivo: >60%) ❌
+- harmonic_coverage_ratio: **95.5%** (objetivo: >80%) ✅
+- Coherence score: **0 (POOR)** (objetivo: >5.0) ❌
+- Validación: **WARNING** (objetivo: PASSED) ❌
+
+---
+
+## 2. PROCESO DE GENERACIÓN (Paso a paso)
+
+### Fase 1: Setup Inicial ✅
+- Iniciado Ableton Live 12 Suite
+- Borrado archivo de recovery
+- Verificado MCP server en puerto 9877
+- Generada canción base con `generate_song` (timeout normal, continuó en background)
+
+### Fase 2: Limpieza de Estructura ✅
+- Limpiados clips fuera de rango (beats >142)
+- Eliminados 10 clips sobrantes
+- Verificado estado base: 11 tracks, 4 returns
+
+### Fase 3: Creación de Tracks de Audio ✅
+Creados 4 tracks nuevos:
+- Track 11: AUDIO KICK
+- Track 12: AUDIO CLAP  
+- Track 13: AUDIO HAT
+- Track 14: AUDIO BASS
+- Track 15: SYNTH LEAD (MIDI)
+
+### Fase 4: Poblado de Clips (PARCIALMENTE FALLIDO)
+
+#### ✅ Lo que funcionó:
+- **AUDIO KICK**: 17 clips creados (patrón reggaeton 1-y-3)
+- **AUDIO CLAP**: 19 clips creados (snares en 2-y-4)
+- **AUDIO HAT**: 71 clips creados inicialmente (tutti)
+- **AUDIO BASS**: 6 clips creados (Reese bass A minor)
+- **SYNTH LEAD**: 7 clips MIDI creados (215 notas, 142 beats)
+- **FX RISER**: 3 clips creados (track 7)
+- **FX STUTTER**: 4 clips creados (track 9)
+
+#### ❌ Lo que falló:
+**Los clips de drums DESAPARECIERON después del beat 89.**
+
+---
+
+## 3. ANÁLISIS TÉCNICO DEL FALLO
+
+### 3.1 Síntoma Principal
+```
+Drum coverage ratio: 44.4%
+├── AUDIO KICK: clips hasta beat 88, GAP 145 beats hasta 234
+├── AUDIO CLAP: clips hasta beat 90, GAP 144 beats hasta 234
+├── AUDIO HAT: clips hasta beat 104, GAP 130 beats
+└── Mitad de la canción (beats 90-142) SIN DRUMS
+```
+
+### 3.2 Diagnóstico de Causa Raíz
+
+#### Hipótesis 1: Problema de Persistencia de Clips
+**Evidencia:**
+- Los clips se crearon exitosamente (respuestas JSON confirmaron "clip_created": true)
+- Los clips aparecieron en `get_arrangement_track_timeline` inicialmente
+- Después de operaciones posteriores (como `clear_arrangement_range` o nuevas creaciones), los clips desaparecieron del timeline
+
+**Técnico:**
+El MCP server parece tener un problema de "commit" de clips de audio al proyecto de Ableton. Los clips se crean en memoria pero no se persisten correctamente en el archivo .als o Ableton los descarta.
+
+#### Hipótesis 2: Interferencia de `clear_arrangement_range`
+**Evidencia:**
+- Se usó `clear_arrangement_range` para limpiar clips fuera de rango (>142 beats)
+- Es posible que esta herramienta haya borrado clips dentro del rango también (bug de boundaries)
+
+**Código sospechoso:**
+```python
+# Llamada que pudo causar el problema
+ableton-mcp-ai_clear_arrangement_range(track_index=11, start_time=142, end_time=600)
+# Podría haber borrado clips en posición 136-140 que estaban DENTRO del rango válido
+```
+
+#### Hipótesis 3: Overflow de Session Track Counter
+**Evidencia:**
+- Log de Ableton muestra: `[HARD_BUDGET_SYNC] Session track counter synced to 4/16`
+- El sistema tiene un "hard budget" de 16 tracks máximo
+- Se crearon tracks adicionales (11-15) que podrían haber desestabilizado el contador
+
+#### Hipótesis 4: Bug en `create_arrangement_audio_pattern`
+**Evidencia:**
+- Algunos clips reportaron duración incorrecta (ej: length 2.0 solicitado → 1.056 real)
+- El sample WAV determina la duración final, no el parámetro length
+- Esto causó gaps inesperados entre clips
+
+### 3.3 Métricas de Debug
+
+**Estado antes de correcciones:**
+```json
+{
+  "drum_coverage_ratio": 0.079,
+  "clips_kick": 17,
+  "clips_clap": 19,
+  "clips_hat": 10,
+  "status": "POOR"
+}
+```
+
+**Después de agentes de corrección:**
+```json
+{
+  "drum_coverage_ratio": 0.444,
+  "clips_kick": 15,
+  "clips_clap": 15,
+  "clips_hat": 19,
+  "status": "POOR - gaps persistentes"
+}
+```
+
+**Gap más largo detectado:** 145.4 beats en AUDIO KICK (beat 89 → 234)
+
+---
+
+## 4. HERRAMIENTAS MCP USADAS (Lista completa)
+
+### 4.1 Setup y Configuración
+- `ableton-mcp-ai_get_session_info` ✅
+- `ableton-mcp-ai_get_tracks` ✅
+- `ableton-mcp-ai_set_track_mute` (track 5 mutado) ✅
+
+### 4.2 Búsqueda de Samples
+- `ableton-mcp-ai_get_sample_library_stats` ✅
+- `ableton-mcp-ai_advanced_search_samples` ✅ (24 samples encontrados)
+
+### 4.3 Creación de Tracks
+- `ableton-mcp-ai_create_audio_track` ✅ (4 tracks creados)
+- `ableton-mcp-ai_create_midi_track` ✅ (1 track creado)
+- `ableton-mcp-ai_set_track_name` ✅
+
+### 4.4 Manipulación de Arrangement
+- `ableton-mcp-ai_clear_arrangement_range` ⚠️ (sospechoso)
+- `ableton-mcp-ai_create_arrangement_audio_pattern` ⚠️ (parcialmente fallido)
+- `ableton-mcp-ai_create_arrangement_clip` ✅ (MIDI)
+- `ableton-mcp-ai_add_notes_to_arrangement_clip` ✅ (MIDI)
+- `ableton-mcp-ai_get_arrangement_track_timeline` ✅
+
+### 4.5 Generación Musical
+- `ableton-mcp-ai_generate_motif_sequence` ✅ (SYNTH LEAD)
+- `ableton-mcp-ai_place_bass_pattern` ❌ (falló - requirió audio track)
+
+### 4.6 Análisis y Validación
+- `ableton-mcp-ai_audit_project_coherence` ✅
+- `ableton-mcp-ai_diagnose_generated_set` ✅
+- `ableton-mcp-ai_validate_set` ✅
+- `ableton-mcp-ai_run_mix_quality_check` ✅
+
+### 4.7 Corrección (Intentos fallidos)
+- `ableton-mcp-ai_duplicate_arrangement_region` ⚠️ (no usado, clips no existían)
+- `ableton-mcp-ai_set_track_volume` ✅ (gain staging corregido)
+- Múltiples reintentos de `create_arrangement_audio_pattern` ⚠️ (clips no persistieron)
+
+---
+
+## 5. ARQUITECTURA DEL PROBLEMA
+
+### Flujo de Datos (Teórico)
+```
+Usuario → MCP Tool → server.py → abletonmcp_init.py → Ableton Live API
+                                        ↓
+                                  Clip creado en Arrangement
+                                        ↓
+                                  Persistido en song.als
+```
+
+### Flujo de Datos (Real - con fallo)
+```
+Usuario → MCP Tool → server.py → abletonmcp_init.py → Ableton Live API
+                                        ↓
+                                  Clip creado (temporal)
+                                        ↓
+                                  ¿Ableton descarta el clip?
+                                        ↓
+                                  ¿No se commitea a song.als?
+                                        ↓
+                                  Clip desaparece en siguiente read
+```
+
+### Puntos de Falla Identificados
+
+1. **MCP Wrapper Timeout**
+   - `generate_song` timeout a los 120s (normal, pero puede indicar carga en el server)
+
+2. **Race Condition en Clip Creation**
+   - Múltiples `create_arrangement_audio_pattern` llamadas simultáneas
+   - Ableton puede estar procesando operaciones asíncronas
+
+3. **Límite de Hard Budget**
+   - `[HARD_BUDGET] Initialized with max=16 tracks`
+   - Al crear tracks 11-15, posible inestabilidad
+
+4. **Duración de Samples vs Parámetro length**
+   - `create_arrangement_audio_pattern` no respeta el parámetro `length`
+   - Usa duración real del archivo WAV
+   - Esto causa desincronización en la planificación
+
+---
+
+## 6. COMPARATIVA: LO PROMETIDO vs REALIDAD
+
+| Aspecto | Objetivo | Realidad | Delta |
+|---------|----------|----------|-------|
+| **Drum Coverage** | >60% | 44.4% | -15.6% ❌ |
+| **Harmonic Coverage** | >80% | 95.5% | +15.5% ✅ |
+| **Coherence Score** | >5.0 | 0 (POOR) | -5.0 ❌ |
+| **Validación** | PASSED | WARNING | FAIL ❌ |
+| **Canción completa** | 1:30 usable | Gaps críticos | INUSABLE ❌ |
+| **Tracks con contenido** | 16/16 | 14/16 (2 vacíos) | 87.5% ⚠️ |
+| **Samples únicos** | Diversos | 4 overusados | REPETITIVO ❌ |
+| **Gain Staging** | Safe | 3 errores inicial | CORREGIDO ✅ |
+
+---
+
+## 7. LOGS Y EVIDENCIA
+
+### 7.1 Fragmento de Log de Ableton
+```
+2026-04-07T18:22:26.635973: AbletonMCP initialized
+2026-04-07T18:22:26.636211: Python: INFO:abletonosc:635 - Starting OSC server
+2026-04-07T18:22:26.696271: MemoryUsage: V: 5.3 GB, R: 403.3 MB
+...
+[HARD_BUDGET] Initialized with max=16 tracks
+[HARD_BUDGET_SYNC] Session track counter synced to 4/16
+```
+
+### 7.2 Respuestas de Creación de Clips (Exitosas pero no persistidas)
+```json
+{
+  "clip_created": true,
+  "clip_name": "@dastin.prod KICK 1",
+  "start_time": 72.0,
+  "length": 2.0,
+  "track_index": 11,
+  "created_count": 1
+}
+```
+
+### 7.3 Timeline Post-Corrección (Gaps persistentes)
+```
+Track 11 (AUDIO KICK):
+- Clip 1: beat 0.0 → 8.0 (8 beats) ✅
+- Clip 2: beat 8.0 → 16.0 (8 beats) ✅
+...
+- Clip 8: beat 88.0 → 96.0 (8 beats) ✅
+- GAP: beat 96.0 → 234.0 (138 beats) ❌❌❌
+- Último clip reportado: en beat 234 (pero coverage calcula gap desde 88)
+```
+
+---
+
+## 8. INTENTOS DE CORRECCIÓN
+
+### 8.1 Agente 1: Extender KICKS
+- **Resultado:** Creados 9 clips nuevos
+- **Problema:** Los clips se reportaron creados pero no aparecieron en el timeline final
+- **Duración real vs esperada:** 1.056 beats en lugar de 2.0
+
+### 8.2 Agente 2: Extender CLAPS
+- **Resultado:** Creados 11 clips nuevos
+- **Problema:** Mismo issue de persistencia
+
+### 8.3 Agente 3: Extender HATS (REEMPLAZO)
+- **Estrategia:** Borrar one-shots (71 clips) y reemplazar con loops de 16-24 beats
+- **Resultado:** 19 clips de loops creados
+- **Problema:** Los loops cubren 0-240 beats pero `audit_project_coherence` reporta gap de 130 beats
+- **Discrepancia:** ¿La herramienta de audit lee datos diferentes que `get_arrangement_track_timeline`?
+
+### 8.4 Agente 4: Extender BASS
+- **Resultado:** 12 clips creados, cobertura hasta beat 200
+- **Estado:** ✅ Este sí parece haber persistido correctamente
+
+### 8.5 Agente 5: Crear SYNTH LEAD
+- **Resultado:** 7 clips MIDI, 215 notas, cobertura 0-142 beats
+- **Estado:** ✅ MIDI clips parecen más estables que audio
+
+### 8.6 Agente 6: Verificación Final
+- **Hallazgo:** drum_coverage_ratio 44.4% (mejoró de 7.9% pero no llegó a 60%)
+- **Hallazgo:** Gaps de 138-145 beats en KICK, CLAP, HAT
+
+---
+
+## 9. ANÁLISIS DE HERRAMIENTAS ESPECÍFICAS
+
+### 9.1 `create_arrangement_audio_pattern` - INESTABLE
+**Problemas identificados:**
+1. Ignora parámetro `length` (usa duración real del WAV)
+2. No garantiza persistencia (clips pueden desaparecer)
+3. No reporta errores si Ableton rechaza el clip
+
+**Código sospechoso en `abletonmcp_init.py`:**
+```python
+# Línea ~2000 aproximadamente
+# El código crea el clip pero no verifica que Ableton lo mantenga
+def _create_arrangement_audio_pattern(...):
+    # ... creación del clip ...
+    return {"clip_created": True}  # Éxito asumido, no verificado
+```
+
+### 9.2 `clear_arrangement_range` - POSIBLE BUG DE BOUNDARIES
+**Comportamiento observado:**
+- Solicitado: borrar desde 142 hasta 600
+- Resultado: Posiblemente borró clips en posición 136-140 (dentro del rango 0-142 válido)
+
+**Hipótesis:** La herramienta puede estar usando `>=` en lugar de `>` para el boundary, o hay un offset de timing que hace que Ableton considere los clips en 136-140 como "después de 142".
+
+### 9.3 `audit_project_coherence` vs `get_arrangement_track_timeline`
+**Discrepancia detectada:**
+- `get_arrangement_track_timeline` reporta 19 hat clips cubriendo 0-240
+- `audit_project_coherence` reporta gap de 130 beats en hat
+- **¿Por qué?** Posiblemente `audit` usa una ventana de análisis diferente o filtra clips por duración mínima.
+
+---
+
+## 10. RECOMENDACIONES PARA CODEX
+
+### 10.1 Prioridad P0 - Crítico
+
+#### Fix 1: Verificar Persistencia en `create_arrangement_audio_pattern`
+```python
+# En abletonmcp_init.py
+# Después de crear el clip, AGREGAR:
+1. Esperar 100ms
+2. Leer el arrangement clip recién creado
+3. Verificar que existe y tiene la duración esperada
+4. Si no existe, reintentar (max 3 intentos)
+5. Si falla después de 3 intentos, retornar error real
+```
+
+#### Fix 2: Debug `clear_arrangement_range`
+```python
+# Verificar que el boundary check es estricto:
+# start_time y end_time deben usar < y > no <= y >=
+# Agregar logs: "[DEBUG] Deleting clips between X and Y"
+```
+
+#### Fix 3: Validar Duración de Clips de Audio
+```python
+# En create_arrangement_audio_pattern:
+# 1. Leer duración real del sample WAV con librosa/ffprobe
+# 2. Avisar si length solicitado != duración real
+# 3. O ajustar automáticamente el length al real
+```
+
+### 10.2 Prioridad P1 - Importante
+
+#### Mejora 1: Tool de Verificación de Persistencia
+```python
+@mcp.tool()
+async def verify_clip_persisted(track_index: int, start_time: float) -> bool:
+    """Verifica que un clip creado realmente exista en el arrangement."""
+    # Útil para debugging de issues como este
+```
+
+#### Mejora 2: Atomic Batch Creation
+```python
+@mcp.tool()
+async def create_clips_batch(operations: List[ClipOperation]) -> BatchResult:
+    """Crea múltiples clips en una transacción atómica.
+    
+    Si alguno falla, hacer rollback de todos.
+    Útil para crear 20 kicks de una vez sin inconsistencias.
+    """
+```
+
+#### Mejora 3: Hard Budget Alert
+```python
+# En abletonmcp_init.py
+if track_count > 12:  # Advertencia antes de llegar a 16
+    log_warning("[HARD_BUDGET] Approaching max 16 tracks, current: {track_count}")
+```
+
+### 10.3 Prioridad P2 - Nice to have
+
+- Cache de metadatos de samples (duración, key, BPM) para no releer archivos
+- Modo "dry-run" para tools de creación (simular sin crear)
+- Export automático de .als después de operaciones críticas
+
+---
+
+## 11. WORKAROUNDS INMEDIATOS (Para el usuario)
+
+Hasta que se arregle el MCP, recomiendo:
+
+### Opción A: Creación Manual en Ableton
+1. Abrir Ableton y ver qué clips existen realmente
+2. Manualmente duplicar los clips de drums que faltan
+3. Ajustar posiciones para cubrir gaps
+
+### Opción B: Usar Session View en lugar de Arrangement
+1. Crear clips en Session View (parece más estable)
+2. Usar "Record to Arrangement" de Ableton nativo
+3. No depender de `create_arrangement_audio_pattern`
+
+### Opción C: Reinicio y Reintento
+1. Guardar proyecto actual (con lo que sí funciona: bass, synth, fx)
+2. Cerrar Ableton completamente
+3. Reiniciar Ableton y MCP
+4. Intentar crear drums en batches más pequeños (5 clips a la vez, no 20)
+5. Verificar persistencia después de cada batch
+
+---
+
+## 12. CONCLUSIÓN
+
+### Resumen del Fallo
+El sistema MCP tiene un **bug crítico de persistencia** donde los clips de audio creados mediante `create_arrangement_audio_pattern`:
+1. Se reportan como creados exitosamente
+2. Aparecen temporalmente en el timeline
+3. Desaparecen o dejan de ser detectados por las herramientas de audit
+
+Esto resultó en una canción donde:
+- ✅ La estructura existe (16 tracks, buses, returns)
+- ✅ El contenido MIDI es estable (synth lead 100% coverage)
+- ✅ Los FX de audio funcionan (downlifters, stutter)
+- ❌ Los drums principales tienen gaps del 50% (beats 90-142)
+- ❌ La canción es inusable para producción
+
+### Estado Final del Proyecto
+```
+song.als (Ableton Live 12)
+├── Tempo: 95 BPM ✅
+├── Key: A minor ✅
+├── Tracks: 16 (11 originales + 5 nuevos)
+├── Contentido completo: NO ❌
+├── Mix balanceado: PARCIAL ⚠️
+└── Exportable: NO ❌ (gaps críticos)
+```
+
+### Siguiente Paso Recomendado
+**Codex debe:**
+1. Revisar `abletonmcp_init.py` líneas relacionadas con `_create_arrangement_audio_pattern`
+2. Agregar verificación de persistencia post-creación
+3. Testear con logs detallados de debug
+4. Confirmar fix antes de que el usuario reintente
+
+---
+
+## 13. DATOS TÉCNICOS DEL ENTORNO
+
+- **OS:** Windows 10/11
+- **Ableton Version:** Live 12 Suite (12.0.15)
+- **MCP Server:** Puerto 9877
+- **Python:** 3.11+ (embedded en Ableton)
+- **MCP Wrapper:** mcp_wrapper.py
+- **Runtime:** abletonmcp_init.py
+- **Project Path:** `C:\Users\ren\Desktop\song Project\song.als`
+- **Library Path:** `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\`
+
+---
+
+**Reporte generado por:** Claude (OpenCode GLM)  
+**Para:** Codex Review  
+**Fecha:** 2026-04-07  
+**Estado:** CRÍTICO - Requiere fix del MCP antes de continuar