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_PHANTOM_CLIPS_P0.md
+++ b/docs/REPORTE_PHANTOM_CLIPS_P0.md
@@ -0,0 +1,415 @@
+# REPORTE CRÍTICO: PHANTOM CLIPS - DISCREPANCIA API vs UI
+
+**Fecha:** 2026-04-07  
+**Proyecto:** AbletonMCP-AI Song Generation  
+**Tipo:** Bug crítico de sincronización API/UI  
+**Severidad:** P0 - Bloqueante para producción
+
+---
+
+## 1. RESUMEN EJECUTIVO
+
+**Problema crítico descubierto:** La API de MCP reporta clips de audio como "creados y existentes" cuando en realidad **NO están materializados en Ableton Live**. Los clips son "fantasmas" - visibles para la API pero inexistentes en la UI y silenciosos en reproducción.
+
+**Impacto:** Toda generación de canciones mediante MCP produce proyectos vacíos/incoherentes a pesar de reportar éxito.
+
+---
+
+## 2. EVIDENCIA IRREFUTABLE
+
+### 2.1 Screenshot de Ableton Live (UI Real)
+
+**Tracks mostrados en UI:**
+- Track 2 (KICK): Vacío, sin clips visibles
+- Track 3 (CLAP): Vacío, sin clips visibles  
+- Track 4 (HAT): Vacío, sin clips visibles
+- Track 5 (BASS): Vacío, sin clips visibles
+- Track 6 (SYNTH): 1 clip MIDI visible (únicamente este existe realmente)
+
+**Estado:** Verde (armado) pero **sin contenido en arrangement**.
+
+### 2.2 Respuesta de API MCP (Mismo momento)
+
+```json
+// GET /clips?track_index=2 (KICK)
+{
+  "arrangement_clip_count": 17,
+  "arrangement_clips": [
+    {
+      "name": "@dastin.prod KICK 1",
+      "start_time": 8.0,
+      "length": 1.333,
+      "is_audio_clip": true
+    },
+    // ... 16 clips más reportados
+  ]
+}
+```
+
+```json
+// GET /clips?track_index=3 (CLAP)
+{
+  "arrangement_clip_count": 16,
+  "arrangement_clips": [
+    {
+      "name": "Snare @dastin (1)",
+      "start_time": 10.0,
+      "length": 0.458,
+      "is_audio_clip": true
+    },
+    // ... 15 clips más reportados
+  ]
+}
+```
+
+```json
+// GET /clips?track_index=5 (BASS)
+{
+  "arrangement_clip_count": 9,
+  "arrangement_clips": [
+    {
+      "name": "Midilatino_Sativa_A_Min_94BPM_Reese",
+      "start_time": 3.204,
+      "length": 64.0,
+      "is_audio_clip": true
+    },
+    // ... 8 clips más reportados
+  ]
+}
+```
+
+### 2.3 La Discrepancia
+
+| Track | UI de Ableton | API de MCP | Estado Real |
+|-------|---------------|------------|-------------|
+| KICK | **0 clips** | 17 clips | ❌ **FANTASMA** |
+| CLAP | **0 clips** | 16 clips | ❌ **FANTASMA** |
+| BASS | **0 clips** | 9 clips | ❌ **FANTASMA** |
+| SYNTH | 1 clip | 2 clips | ⚠️ **PARCIAL** |
+
+**Conclusión:** La API está leyendo/escribiendo en un estado "virtual" que no se sincroniza con Ableton Live.
+
+---
+
+## 3. ANÁLISIS TÉCNICO
+
+### 3.1 Hipótesis del Origen del Bug
+
+#### **Hipótesis A: Session vs Arrangement Desincronización**
+**Descripción:** Los clips se están creando en **Session View** pero la API los reporta como si estuvieran en **Arrangement View**.
+
+**Evidencia:**
+- SYNTH (MIDI) muestra 1 clip en UI - posiblemente porque los clips MIDI se crean en Arrangement por defecto
+- Audio clips podrían estar creándose en Session y no "commiteándose" a Arrangement
+- La API de Live tiene dos objetos diferentes: `session_clip` y `arrangement_clip`
+
+**Verificación necesaria:**
+```python
+# En abletonmcp_init.py, verificar:
+song.view.selected_track = track
+for clip_slot in track.clip_slots:
+    if clip_slot.has_clip:
+        print(f"Session clip: {clip_slot.clip.name}")
+
+for clip in track.arrangement_clips:
+    print(f"Arrangement clip: {clip.name}")
+```
+
+#### **Hipótesis B: Referencias Fantasma en Cache de MCP**
+**Descripción:** MCP mantiene un diccionario interno de clips que no se sincroniza con el estado real de Live.
+
+**Evidencia:**
+- Los clips se crean exitosamente (sin errores)
+- Se reportan en `get_clips` incluso después de tiempo
+- Pero no son visibles ni audibles
+
+**Posible código problemático:**
+```python
+# En server.py o abletonmcp_init.py
+# El código podría estar manteniendo:
+self._clip_cache = {
+    track_index: [clip1, clip2, ...]  # Referencias locales
+}
+# Sin verificar si realmente existen en Live
+```
+
+#### **Hipótesis C: Commit Fallido de Audio Clips**
+**Descripción:** La creación del clip "sucede" pero Ableton Live descarta el audio porque:
+- El archivo de sample no existe en la ruta
+- El sample tiene formato incompatible
+- Ableton no tiene permisos para leer el archivo
+- El clip se crea pero sin referencia al audio (clip vacío)
+
+**Evidencia:**
+- Los clips de MIDI (SYNTH) SÍ aparecen - solo audio falla
+- Las rutas de samples son válidas (reportadas sin error)
+- Pero posiblemente Ableton no puede resolverlas
+
+**Verificación necesaria:**
+```python
+# Verificar que el archivo existe y es accesible
+import os
+sample_path = "C:\\...\\kick 1.wav"
+if not os.path.exists(sample_path):
+    print("ERROR: Sample no existe")
+# Verificar que Ableton puede cargarlo
+```
+
+#### **Hipótesis D: Problema de Timing y Sincronización**
+**Descripción:** Los clips se crean pero Ableton los descarta porque:
+- La operación asíncrona no completó antes del siguiente comando
+- Race condition entre creación y lectura
+- El clip existe "momentáneamente" pero luego se pierde
+
+**Evidencia:**
+- Fix de Codex agregó 100ms de espera - pero **NO funcionó**
+- Los clips persisten en la API (no son temporales)
+- Pero no están en la UI
+
+**Conclusión:** No es un problema de timing, es de persistencia real.
+
+---
+
+## 4. COMPORTAMIENTO ANTES vs DESPUÉS DE FIXES
+
+### 4.1 Antes de Fixes de Codex (2026-04-07 temprano)
+- Clips se creaban y desaparecían
+- `get_arrangement_timeline` mostraba clips → luego gaps
+- Inconsistencia temporal
+
+### 4.2 Después de Fixes de Codex (2026-04-07 tarde)
+- Clips se crean y **persisten en la API**
+- `get_arrangement_timeline` **SIEMPRE** muestra clips
+- Pero **UI de Ableton NUNCA** los muestra
+- **Situación peor:** Ahora tenemos "phantom clips" estables
+
+---
+
+## 5. DIAGNÓSTICO DIFERENCIAL
+
+### 5.1 Qué Funciona ✅
+- Creación de tracks ✅
+- Asignación de nombres ✅
+- Creación de clips MIDI (SYNTH visible en UI) ✅
+- Returns y buses ✅
+- Session info ✅
+
+### 5.2 Qué NO Funciona ❌
+- Materialización de clips de audio en Arrangement ❌
+- Referencia a archivos de audio en clips ❌
+- Sincronización API/UI para audio ❌
+
+### 5.3 Patrón Identificado
+**Audio Clips = Fantasmas**  
+**MIDI Clips = Reales**
+
+Esto apunta a un problema específico en la creación de `AudioClip` vs `MidiClip` en la API de Live.
+
+---
+
+## 6. POSIBLES SOLUCIONES
+
+### 6.1 Solución A: Forzar Commit a Arrangement
+```python
+# Después de crear el clip, llamar:
+song.view.selected_track = track
+song.view.follow_song = True
+# O posiblemente:
+track.flatten()  # Commitear session a arrangement
+```
+
+### 6.2 Solución B: Verificación de Sample Path
+```python
+# Antes de crear clip, verificar:
+import os
+if not os.path.exists(sample_path):
+    return {"error": "Sample no existe"}
+
+# Después de crear, verificar que el clip tiene audio:
+if clip and clip.file_path != sample_path:
+    return {"error": "Clip no referencia sample correctamente"}
+```
+
+### 6.3 Solución C: Usar Método Nativo de Live
+```python
+# En lugar de crear clip directamente, usar:
+track.create_audio_clip(start_time)
+# O:
+song.create_audio_track(insert_index)
+# Y luego asignar sample
+```
+
+### 6.4 Solución D: Sincronización Forzada
+```python
+# Después de operaciones de creación:
+song.request_show_in_browser()  # Forzar refresh
+# O:
+song.view.selected_track = track  # Trigger update
+```
+
+---
+
+## 7. TESTS DE VERIFICACIÓN NECESARIOS
+
+### Test 1: Creación Manual vs MCP
+```
+1. Crear clip de audio MANUALMENTE en Ableton
+2. Leer con get_clips → ¿Se ve igual?
+3. Comparar atributos: file_path, gain, warp_mode, etc.
+```
+
+### Test 2: Diferencia MIDI vs Audio
+```
+1. Crear clip MIDI con MCP
+2. Verificar en UI → ¿Aparece?
+3. Crear clip Audio con MCP
+4. Verificar en UI → ¿Aparece?
+5. Comparar diferencias en código
+```
+
+### Test 3: Persistencia Post-Guardado
+```
+1. Crear clips con MCP
+2. Guardar proyecto (Ctrl+S)
+3. Cerrar y reabrir Ableton
+4. Verificar si clips persisten
+```
+
+---
+
+## 8. REPRODUCCIÓN DEL BUG
+
+### Pasos Exactos:
+```bash
+# 1. Iniciar Ableton Live 12 Suite
+# 2. Ejecutar:
+ableton-mcp-ai_create_audio_track(index=2, name="TEST")
+
+# 3. Crear clip:
+ableton-mcp-ai_create_arrangement_audio_pattern(
+    track_index=2,
+    start_time=0,
+    length=4.0,
+    sample_path="C:\\...\\kick 1.wav"
+)
+
+# 4. Verificar API:
+ableton-mcp-ai_get_clips(track_index=2)
+# → Reportará 1 clip
+
+# 5. Verificar UI:
+# → Ableton mostrará track vacío
+
+# 6. Comparar:
+# API dice clip existe, UI dice no existe
+```
+
+---
+
+## 9. IMPACTO EN PRODUCCIÓN
+
+### 9.1 Bugs Dependientes de Este
+- Todos los `generate_song` fallan silenciosamente
+- `create_arrangement_audio_pattern` reporta éxito pero no crea
+- `audit_project_coherence` da métricas falsas
+- `diagnose_generated_set` no detecta el problema real
+
+### 9.2 Usuario Impactado
+- No puede generar canciones automáticamente
+- Tiempo perdido en debugging (como este caso)
+- Frustración por discrepancia reporte vs realidad
+
+---
+
+## 10. RECOMENDACIONES PRIORITARIAS
+
+### P0 - Crítico (Hoy)
+1. **Debuggear creación de AudioClip en Live API**
+   - Comparar código de MIDI vs Audio clip creation
+   - Identificar diferencia que causa phantom
+
+2. **Agregar verificación post-creación**
+   - Después de `create_arrangement_audio_pattern`, verificar con Live API (no cache)
+   - Si clip no existe realmente, retornar ERROR (no SUCCESS)
+
+3. **Test unitario de persistencia**
+   - Crear clip → Guardar → Reabrir → Verificar
+   - Debe fallar si hay phantom clips
+
+### P1 - Alto (Esta semana)
+4. **Sistema de logs de debug detallado**
+   - Loggear cada paso de creación de clip
+   - Incluir referencias de memoria vs Live
+
+5. **Modo "strict" para creación**
+   - Parámetro opcional: `verify_in_ui=True`
+   - Que la API espere y verifique que el clip aparece en UI
+
+### P2 - Medio (Próxima sprint)
+6. **Refactor de manejo de clips**
+   - Separar lógica de Session vs Arrangement
+   - Cache invalidation más agresivo
+
+---
+
+## 11. NOTAS PARA DESARROLLADOR
+
+### Código Sospechoso (Revisar)
+
+**Archivo:** `abletonmcp_init.py`
+```python
+# Líneas aproximadas 1800-1900
+# Buscar función _create_arrangement_audio_pattern
+
+# Posible problema:
+clip = track.create_audio_clip(start_time)  # ¿Esto existe en Live API?
+clip.file_path = sample_path  # ¿Se asigna correctamente?
+
+# O alternativa:
+audio_clip = track.create_clip(start_time, length)  # ¿Crea clip vacío?
+# ¿Falta asignar el sample?
+```
+
+**Archivo:** `abletonmcp_runtime.py`
+```python
+# Fix de Codex agregó:
+for attempt in range(3):
+    time.sleep(0.1)
+    # Verificar persistencia...
+    
+# Pero la verificación podría estar leyendo cache, no Live real
+```
+
+### Diferencia Clave a Investigar
+
+**MIDI Clip Creation (Funciona):**
+```python
+clip = track.create_midi_clip(start_time, length)
+# ¿Live API tiene método específico?
+```
+
+**Audio Clip Creation (No funciona):**
+```python
+clip = track.create_audio_clip(start_time)  # ¿Este método existe?
+# ¿O debe ser?
+audio_track.insert_audio_clip(sample_path, start_time)
+```
+
+---
+
+## 12. CONCLUSIÓN
+
+**Estado actual:** El sistema MCP está generando **phantom clips** - referencias vacías que la API reporta como existentes pero Ableton Live no reconoce.
+
+**Fixes aplicados:** Los de Codex (persistencia y boundaries) NO resolvieron el problema fundamental.
+
+**Acción requerida:** Debuggear la creación física de `AudioClip` en Ableton Live API y comparar con `MidiClip` que sí funciona.
+
+**Severidad:** P0 - Bloquea toda generación de audio.
+
+---
+
+**Reporte generado por:** Claude (OpenCode GLM)  
+**Basado en:** Screenshot de usuario + logs de API  
+**Fecha:** 2026-04-07  
+**Estado:** Abierto - Requiere fix de desarrollador