ableton-mcp-ai/docs/skill_reinicio_ableton.md

# Skill: Reinicio Correcto de Ableton Live + Inyección Senior de Audio

## Descripción
Procedimiento correcto para reiniciar Ableton Live y sistema profesional de inyección de audio en Arrangement View con 5 métodos de fallback automáticos.

## Cuándo Usar Reinicio
- Después de modificar `AbletonMCP_AI/__init__.py`
- Cuando los cambios no se reflejan en el comportamiento
- Cuando Ableton muestra comportamiento inconsistente
- Después de errores que requieren recarga completa del Remote Script

## Proceso de Reinicio (3 Pasos Obligatorios)

### Paso 1: Matar Todos los Procesos de Ableton
```powershell
Get-Process | Where-Object { $_.ProcessName -like "*Ableton*" } | ForEach-Object { 
    Write-Host "Killing $($_.ProcessName) ($($_.Id))"
    Stop-Process -Id $_.Id -Force 
}
```
Procesos a verificar:
- `Ableton Live 12 Suite` (principal)
- `Ableton Index` (indexador de archivos)
- `AbletonPushCpl` (controlador Push si está conectado)

### Paso 2: Eliminar Archivos de Recovery/Crash (CRÍTICO)
```powershell
# Archivos que causan popups de recuperación
Remove-Item "C:\Users\Administrator\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashDetection.cfg" -Force -ErrorAction SilentlyContinue
Remove-Item "C:\Users\Administrator\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashRecoveryInfo.cfg" -Force -ErrorAction SilentlyContinue

# Archivo de undo que puede causar inconsistencias
Remove-Item "C:\Users\Administrator\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Undo.cfg" -Force -ErrorAction SilentlyContinue
```

**⚠️ CRÍTICO:** Sin este paso, Ableton mostrará popups de recuperación y podría ignorar los cambios del Remote Script.

### Paso 3: Iniciar Ableton y Verificar
```powershell
# Iniciar Ableton
Start-Process "C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe"

# Esperar a que el servidor TCP esté listo (máximo 30 segundos)
$waited = 0
while ($waited -lt 30) {
    Start-Sleep 2
    $waited += 2
    if (netstat -an | findstr 9877) { 
        Write-Host "✓ TCP server ready on port 9877"
        break
    }
}

# Verificar salud
ableton-live-mcp_health_check
```

**Resultado esperado:** `score: "5/5"`, `status: "HEALTHY"`

---

## Inyección Senior de Audio en Arrangement View

### Arquitectura de Fallback Automático (5 Métodos)

La implementación senior intenta automáticamente 5 métodos en orden de preferencia:

```
┌─────────────────────────────────────────────────────────────┐
│  MÉTODO 1: track.insert_arrangement_clip()                  │
│  ├─ Disponibilidad: Live 12+                                │
│  ├─ Tipo: Directo a Arrangement View                        │
│  └─ Éxito → Fin del proceso                                 │
├─────────────────────────────────────────────────────────────┤
│  MÉTODO 2: track.create_audio_clip()                       │
│  ├─ Disponibilidad: Live 11.0+                              │
│  ├─ Tipo: Directo a Arrangement View                        │
│  └─ Éxito → Fin del proceso                                 │
├─────────────────────────────────────────────────────────────┤
│  MÉTODO 3: arrangement_clips.add_new_clip()               │
│  ├─ Disponibilidad: Live 12+                                │
│  ├─ Tipo: API de Arrangement                                │
│  └─ Éxito → Fin del proceso                                 │
├─────────────────────────────────────────────────────────────┤
│  MÉTODO 4: Session + duplicate_clip_to_arrangement         │
│  ├─ Disponibilidad: Live 10+ (varía por versión)            │
│  ├─ Tipo: Session → Arrangement                             │
│  └─ Éxito → Fin del proceso                                 │
├─────────────────────────────────────────────────────────────┤
│  MÉTODO 5: Session + Recording Fallback                    │
│  ├─ Disponibilidad: Todas las versiones                     │
│  ├─ Tipo: Grabación desde Session                           │
│  └─ Último recurso                                         │
└─────────────────────────────────────────────────────────────┘
```

### Uso Automático (Zero Configuración Manual)

```python
# Crear clips de audio en posiciones exactas
ableton-live-mcp_create_arrangement_audio_pattern(
    track_index=3,
    file_path="C:\\...\\libreria\\reggaeton\\kick\\kick 1.wav",
    positions=[0, 4, 8, 12],  # Beats exactos
    name="KickPattern"
)
```

**Respuesta esperada:**
```json
{
  "track_index": 3,
  "file_path": "...",
  "created_count": 4,
  "positions": [0.0, 4.0, 8.0, 12.0],
  "name": "KickPattern"
}
```

### Verificación de Clips en Arrangement

```python
ableton-live-mcp_get_arrangement_status
```

**Resultado exitoso:**
```json
{
  "view": "Arrangement",
  "total_clips": 4,
  "clips": [
    {
      "track_index": 3,
      "name": "KickPattern 1",
      "start_time": 0.0,
      "is_midi": false
    },
    {
      "track_index": 3,
      "name": "KickPattern 2", 
      "start_time": 4.0,
      "is_midi": false
    }
  ]
}
```

---

## Anti-Patrones (Qué NO Hacer)

❌ **NO** usar `File > Quit` (deja procesos colgados)  
❌ **NO** omitir el Paso 2 de eliminación de archivos crash  
❌ **NO** usar `duplicate_clip_to_arrangement` directamente (puede no estar disponible)  
❌ **NO** cargar samples manualmente en Session View antes de inyectar  
❌ **NO** usar métodos de grabación manual cuando existe la inyección automática  

---

## Solución de Problemas

### Problema: "created_count: 0"
**Causa:** Ningún método de los 5 funcionó  
**Solución:** Verificar que el archivo existe y es un audio válido (WAV, AIFF, MP3)

### Problema: Clips en posiciones incorrectas
**Causa:** Método de grabación (Método 5) activado como último recurso  
**Solución:** Normal, el Método 5 tiene tolerancia de ±1 beat. Verificar logs con `[MCP-AUDIO]`.

### Problema: Cambios no se reflejan después de reinicio
**Causa:** Archivos crash no fueron eliminados  
**Solución:** Repetir Proceso de Reinicio completo (3 pasos)

---

## Referencia Técnica

### Archivos Modificados
- `AbletonMCP_AI/__init__.py` - Métodos `_cmd_create_arrangement_audio_pattern` y `_cmd_duplicate_clip_to_arrangement`

### Métodos del Live Object Model Utilizados
- `track.insert_arrangement_clip(path, start_beat, end_beat)` - Live 12+ direct
- `track.create_audio_clip(path, position)` - Live 11.0+ direct  
- `arrangement_clips.add_new_clip(start, end)` - Live 12+ arrangement API
- `song.duplicate_clip_to_arrangement(track, slot, pos)` - Legacy workflow
- `clip_slot.create_audio_clip(path)` + grabación - Universal fallback

### Logs de Debug
Buscar en `C:\Users\Administrator\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt`:
- `[MCP-AUDIO] Using Method X` - Método que se intentó
- `[MCP-AUDIO] Method X SUCCESS` - Método que funcionó
- `[MCP-AUDIO] Method X FAILED` - Método que falló

---

## Historial
- **v1.0** (2026-04-12): Documento inicial con proceso de reinicio
- **v2.0** (2026-04-12): Agregada inyección senior de audio con 5 métodos de fallback
- **Autor:** AbletonMCP_AI Senior Architecture

---

## Ejemplo de Workflow Completo

```powershell
# 1. REINICIO (3 pasos)
Get-Process | Where-Object { $_.ProcessName -like "*Ableton*" } | Stop-Process -Force
Remove-Item "...\Crash*.cfg" -Force
Start-Process "...\Ableton Live 12 Suite.exe"

# 2. VERIFICACIÓN
ableton-live-mcp_health_check  # Debe retornar 5/5

# 3. INYECCIÓN AUTOMÁTICA
ableton-live-mcp_create_arrangement_audio_pattern `
    -track_index 3 `
    -file_path "C:\...\kick 1.wav" `
    -positions @(0, 4, 8, 12) `
    -name "KickPattern"

# 4. VERIFICACIÓN EN ARRANGEMENT
ableton-live-mcp_get_arrangement_status  # Debe mostrar 4 clips
```

**Resultado:** Audio clips en Arrangement View en posiciones exactas, sin intervención manual.