ableton-mcp-ai/docs/REPORTE_PHANTOM_CLIPS_P0.md

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)

// 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
  ]
}

// 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
  ]
}

// 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:

# 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:

# 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:

# 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

# 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

# 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

# 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

# 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:

# 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

# 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

# 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):

clip = track.create_midi_clip(start_time, length)
# ¿Live API tiene método específico?

Audio Clip Creation (No funciona):

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