# 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