# TROUBLESHOOTING - AbletonMCP_AI

> Guia de solucion de problemas para el sistema AbletonMCP_AI.

## Tabla de Contenidos

1. [Diagnosticos Iniciales](#diagnosticos-iniciales)
2. [Problemas deConexion con Ableton](#problemas-de-conexion-con-ableton)
3. [Problemas de Carga de Samples](#problemas-de-carga-de-samples)
4. [Problemas de Clips](#problemas-de-clips)
5. [Problemas de Generacion Musical](#problemas-de-generacion-musical)
6. [Problemas de Mezcla](#problemas-de-mezcla)
7. [Problemas de Export/Render](#problemas-de-exportrender)
8. [Mensajes de Error Comunes](#mensajes-de-error-comunes)
9. [Como Reiniciar el Sistema Correctamente](#como-reiniciar-el-sistema-correctamente)
10. [Log de Ableton Live](#log-de-ableton-live)
11. [Herramientas de Diagnostico](#herramientas-de-diagnostico)

---

## Diagnosticos Iniciales

### Primer Paso: health_check()

**SIEMPRE** ejecutar este comando primero al abrir Ableton o despues de cualquier problema:

```
Command: health_check()
```

**Resultado esperado (sistema sano):**
```json
{
  "score": "5/5",
  "status": "HEALTHY",
  "checks": [
    "[OK] TCP Server: Connected on port 9877",
    "[OK] Song: Accessible",
    "[OK] Tracks: Accessible",
    "[OK] Browser: Accessible",
    "[OK] Update Display: Drain loop active"
  ],
  "recommendation": "System is healthy. Ready for production."
}
```

**Interpretacion de scores:**
- **5/5**: Sistema completamente funcional. Proceder con produccion.
- **4/5**: Un chequeo fallido. Generalmente no critico. Ver cual fallo.
- **3/5**: Dos chequeos fallidos. Posible problema de conectividad. Reiniciar Remote Script.
- **2/5 o menos**: Sistema no funcional. Reiniciar Required.

### Segundo Paso: get_session_info()

Verificar que Ableton responde correctamente:

```
Command: get_session_info()
```

**Resultado esperado:**
```json
{
  "tempo": 120,
  "num_tracks": 3,
  "num_scenes": 2,
  "is_playing": false,
  "current_song_time": 0.0,
  "metronome": false,
  "master_volume": 0.8
}
```

**Si este comando falla o tarda mas de 10 segundos:**
1. Verificar que Ableton Live esta abierto
2. Verificar que el Remote Script `AbletonMCP_AI` esta seleccionado en Preferences > Control Surfaces
3. Revisar el log de Ableton (ver seccion Log mas abajo)

### Tercer Paso: get_system_diagnostics()

Para un diagnostico mas detallado:

```
Command: get_memory_usage()
```

**Resultado esperado:**
```json
{
  "process_memory_mb": 250.5,
  "process_memory_percent": 2.3,
  "system_total_mb": 16384,
  "system_available_mb": 8192,
  "system_percent_used": 50,
  "live_processes": 1
}
```

**Si `live_processes` es 0:** Ableton no esta corriendo. Abrirlo.
**Si `system_percent_used` > 90%:** Memoria insuficiente. Cerrar otras aplicaciones.

---

## Problemas de Conexion con Ableton

### Sintoma: "Cannot connect to Ableton on 127.0.0.1:9877"

**Causa:** El Remote Script no esta cargado o el servidor TCP no esta escuchando.

**Solucion:**

1. **Verificar que Ableton Live esta abierto**
   - Mirar en el administrador de tareas que `Ableton Live 12 Suite.exe` esta corriendo.

2. **Verificar que el Remote Script esta seleccionado:**
   - En Ableton: `Options > Preferences > Link/Tempo/MIDI`
   - En la seccion "Control Surfaces", buscar "AbletonMCP_AI"
   - Asegurarse de que esta seleccionado (no en "None")
   - El puerto de entrada debe estar en "On"

3. **Reiniciar el Remote Script:**
   - Cambiar el Control Surface a "None"
   - Esperar 2 segundos
   - Volver a seleccionar "AbletonMCP_AI"
   - Esperar 5 segundos
   - Ejecutar `health_check()` de nuevo

4. **Verificar el puerto 9877:**
   ```powershell
   netstat -an | findstr 9877
   ```
   Deberia mostrar una linea con `LISTENING` en `127.0.0.1:9877`.

5. **Revisar el log de Ableton:**
   ```powershell
   Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
   ```
   Buscar errores que mencionen "AbletonMCP_AI" o "socket".

### Sintoma: Los comandos tardan mucho (timeout)

**Causa:** Ableton esta ocupado o el Remote Script esta bloqueado.

**Solucion:**

1. **Verificar que Ableton no esta renderizando o procesando algo pesado**
2. **Detener reproduccion:** `stop_playback()`
3. **Detener todos los clips:** `stop_all_clips()`
4. **Esperar 10 segundos y reintentar**
5. **Si persiste, reiniciar el Remote Script** (pasos arriba)

### Sintoma: `health_check()` devuelve score 3/5 o menos

**Causa:** Uno o mas componentes del sistema no responden.

**Solucion:**

1. Identificar cual chequeo fallo en la respuesta de `health_check()`
2. Si es "TCP Server": Reiniciar el Remote Script
3. Si es "Song": Cerrar y reabrir el proyecto en Ableton
4. Si es "Tracks": Verificar que hay al menos una pista en el proyecto
5. Si es "Browser": Problema con el navegador de samples. Reiniciar Ableton.
6. Si es "Update Display": El bucle de actualizacion esta colgado. Reiniciar Remote Script.

---

## Problemas de Carga de Samples

### Sintoma: "Sample not found: C:\...\sample.wav"

**Causa:** El archivo no existe en la ruta especificada.

**Solucion:**

1. **Verificar que el archivo existe:**
   ```powershell
   Test-Path "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton\kick\kick_01.wav"
   ```

2. **Si no existe, usar `browse_library()` para encontrar samples disponibles:**
   ```
   Command: browse_library(role="kick")
   ```

3. **Verificar que la libreria esta analizada:**
   ```
   Command: get_library_stats()
   ```
   Si devuelve 0 archivos, ejecutar `analyze_library()` primero.

### Sintoma: Los samples se cargan pero no suenan

**Causa:** Posiblemente el volumen de la pista esta en 0 o la pista esta muteada.

**Solucion:**

1. **Verificar volumen de la pista:**
   ```
   Command: get_tracks()
   ```
   Buscar el volumen del track donde se cargo el sample.

2. **Desmutear la pista si es necesario:**
   ```
   Command: set_track_mute(track_index=N, mute=False)
   ```

3. **Subir el volumen:**
   ```
   Command: set_track_volume(track_index=N, volume=0.8)
   ```

4. **Verificar que el sample tiene contenido de audio:**
   - Algunos samples pueden estar vacios o corruptos.
   - Probar con otro sample del mismo rol.

### Sintoma: `analyze_library()` tarda demasiado o falla

**Causa:** Libreria muy grande o problema con algunos archivos de audio.

**Solucion:**

1. **Verificar cuantos archivos hay en la libreria:**
   ```powershell
   (Get-ChildItem "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\libreria\reggaeton" -Recurse -Include *.wav,*.mp3,*.aif,*.flac).Count
   ```

2. **Si son mas de 1000 archivos, es normal que tarde 5-15 minutos.** Usar `force_reanalyze=False` para usar cache.

3. **Si falla con un error especifico:**
   - Revisar el mensaje de error para identificar el archivo problematico
   - Eliminar o mover el archivo corrupto
   - Reintentar con `force_reanalyze=True`

---

## Problemas de Clips

### Sintoma: Los clips no aparecen en Ableton

**Causa:** Posiblemente la pista no existe o el indice es incorrecto.

**Solucion:**

1. **Verificar que las pistas existen:**
   ```
   Command: get_tracks()
   ```

2. **Verificar el indice de pista:** Los indices son 0-based. La primera pista es indice 0.

3. **Si la pista no existe, crearla:**
   ```
   Command: create_midi_track(index=-1)  # para MIDI
   Command: create_audio_track(index=-1)  # para audio
   ```

4. **Despues de crear un clip, verificar con `get_tracks()`:**
   - Los clips deben aparecer en la seccion de la pista correspondiente.

### Sintoma: `fire_clip()` no reproduce el clip

**Causa:** El clip puede estar vacio o la pista muteada.

**Solucion:**

1. **Verificar que el clip tiene notas (si es MIDI):**
   ```
   Command: get_tracks()
   ```
   Buscar la pista y verificar que tiene clips con contenido.

2. **Verificar que la pista no esta muteada:**
   ```
   Command: set_track_mute(track_index=N, mute=False)
   ```

3. **Para clips MIDI, verificar que tienen notas:**
   - Si se creo el clip pero no se le aniadieron notas, estará vacio.
   - Usar `generate_dembow_clip()`, `generate_bass_clip()`, etc. para generar contenido.

4. **Para clips de audio, verificar que el sample se cargo correctamente:**
   - Usar `load_sample_to_clip()` con una ruta valida.

### Sintoma: `add_notes_to_clip()` falla

**Causa:** El clip no existe o el formato de las notas es incorrecto.

**Solucion:**

1. **Verificar que el clip existe primero:**
   ```
   Command: create_clip(track_index=0, clip_index=0, length=4.0)
   ```

2. **Verificar el formato de las notas:**
   ```json
   {
     "track_index": 0,
     "clip_index": 0,
     "notes": [
       {"pitch": 36, "start_time": 0.0, "duration": 0.25, "velocity": 100},
       {"pitch": 42, "start_time": 0.5, "duration": 0.25, "velocity": 80}
     ]
   }
   ```
   - `pitch`: MIDI note number (0-127, 60=C4)
   - `start_time`: Tiempo en beats desde el inicio del clip
   - `duration`: Duracion en beats
   - `velocity`: Velocidad (1-127)

---

## Problemas de Generacion Musical

### Sintoma: `produce_reggaeton()` falla o devuelve error

**Causa:** Posiblemente el engine de produccion no esta disponible o Ableton no responde.

**Solucion:**

1. **Verificar estado del sistema primero:**
   ```
   Command: health_check()
   ```
   Si el score es menor a 4/5, reiniciar antes de continuar.

2. **Verificar que la libreria esta analizada:**
   ```
   Command: get_library_stats()
   ```
   Si no hay datos, ejecutar `analyze_library()` primero.

3. **Probar con parametros mas simples:**
   ```
   Command: produce_reggaeton(bpm=95, key="Am", style="classic", structure="verse-chorus")
   ```

4. **Si persiste el error, revisar el mensaje especifico:**
   - "Production workflow engine not available": Problema con el engine. Reiniciar el servidor MCP.
   - "Failed to create track": Ableton no responde. Reiniciar Remote Script.

### Sintoma: `generate_dembow_clip()` no genera notas

**Causa:** La pista no existe o no es una pista MIDI.

**Solucion:**

1. **Crear la pista MIDI si no existe:**
   ```
   Command: create_midi_track(index=-1)
   ```

2. **Crear el clip antes de generar:**
   ```
   Command: create_clip(track_index=N, clip_index=0, length=4.0)
   ```

3. **Luego generar el dembow:**
   ```
   Command: generate_dembow_clip(track_index=N, clip_index=0, bars=4, variation="standard")
   ```

### Sintoma: Las notas MIDI generadas suenan mal o fuera de tono

**Causa:** El instrumento en la pista no coincide con el tipo de notas generadas.

**Solucion:**

1. **Verificar que la pista tiene un instrumento cargado:**
   ```
   Command: get_tracks()
   ```

2. **Para drums, usar un Drum Rack en la pista:**
   - La pista de drums debe tener un Drum Rack con samples en los pads correctos.
   - Nota 36 = Kick (C1)
   - Nota 38 = Snare (D1)
   - Nota 42 = Closed Hat (F#1)

3. **Para bass, usar un sintetizador de bajo:**
   - Las notas estan en el rango de C1-C2 (notas 36-48).

4. **Para acordes, usar un sintetizador o piano:**
   - Las notas estan en rango de C3-C5 (notas 60-84).

---

## Problemas de Mezcla

### Sintoma: `create_return_track()` falla

**Causa:** El tipo de efecto no es valido o Ableton no responde.

**Solucion:**

1. **Verificar los efectos disponibles:**
   - REVERB, DELAY, CHORUS, FLANGER, PHASER, COMPRESSOR, EQ

2. **Usar un nombre valido:**
   ```
   Command: create_return_track(effect_type="Reverb")
   ```

### Sintoma: `setup_sidechain()` no funciona

**Causa:** Las pistas no existen o no tienen los dispositivos correctos.

**Solucion:**

1. **Verificar que ambas pistas existen:**
   ```
   Command: get_tracks()
   ```

2. **Verificar que la pista target tiene un compresor:**
   - El sidechain requiere un compresor en la pista target.
   - Usar `configure_compressor()` primero si no tiene uno.

3. **Configurar sidechain:**
   ```
   Command: setup_sidechain(source_track=0, target_track=1, amount=0.5)
   ```

### Sintoma: `auto_gain_staging()` no ajusta nada

**Causa:** No hay pistas configuradas o las pistas ya tienen niveles adecuados.

**Solucion:**

1. **Verificar que hay pistas en el proyecto:**
   ```
   Command: get_tracks()
   ```

2. **Verificar que las pistas tienen contenido (clips):**
   - Sin clips, no hay senal para medir.

3. **Ejecutar de nuevo:**
   ```
   Command: auto_gain_staging()
   ```

---

## Problemas de Export/Render

### Sintoma: `render_stems()` no produce archivos

**Causa:** El directorio de salida no existe o Ableton no puede renderizar.

**Solucion:**

1. **Verificar que el directorio existe:**
   ```powershell
   Test-Path "C:\Users\ren\Desktop\stems\"
   ```

2. **Crear el directorio si no existe:**
   ```powershell
   New-Item -ItemType Directory -Path "C:\Users\ren\Desktop\stems\" -Force
   ```

3. **Verificar que hay contenido para renderizar:**
   - El proyecto debe tener pistas con clips.
   - Usar `get_project_summary()` para verificar.

4. **Ejecutar render:**
   ```
   Command: render_stems(output_dir="C:\\Users\\ren\\Desktop\\stems\\mi_track\\")
   ```

### Sintoma: `render_full_mix()` tarda demasiado

**Causa:** El proyecto es largo o el sistema esta lento.

**Solucion:**

1. **Verificar la duracion del proyecto:**
   ```
   Command: get_project_summary()
   ```

2. **El render puede tardar 1-5 minutos dependiendo de la duracion del proyecto.**
   - Timeout por defecto: 120 segundos.
   - Si tarda mas, puede ser un problema de rendimiento.

3. **Cerrar otras aplicaciones para liberar recursos.**

---

## Mensajes de Error Comunes

### "Cannot connect to Ableton on 127.0.0.1:9877"
- **Significado:** El servidor TCP de Ableton no esta escuchando.
- **Solucion:** Reiniciar el Remote Script en Ableton Preferences.

### "Command 'xxx' timed out after Xs"
- **Significado:** Ableton no respondio dentro del tiempo limite.
- **Solucion:** Ableton puede estar ocupado. Esperar y reintentar. Si persiste, reiniciar Remote Script.

### "Sample not found: ..."
- **Significado:** El archivo de audio no existe en la ruta especificada.
- **Solucion:** Verificar la ruta con `Test-Path` o usar `browse_library()` para encontrar samples validos.

### "Production workflow engine not available"
- **Significado:** El motor de produccion no se pudo importar.
- **Solucion:** Reiniciar el servidor MCP. Verificar que los archivos del engine existen en `mcp/engines/`.

### "Sample selector engine not available"
- **Significado:** El motor de seleccion de samples no esta disponible.
- **Solucion:** Verificar que la libreria `libreria/reggaeton` existe y tiene samples. Ejecutar `analyze_library()`.

### "Invalid tempo: X. Must be 20-300 BPM"
- **Significado:** El tempo esta fuera del rango valido.
- **Solucion:** Usar un valor entre 20 y 300. Para reggaeton, usar 88-112.

### "Invalid volume: X. Must be 0.0-1.0"
- **Significado:** El volumen esta fuera del rango valido.
- **Solucion:** Usar un valor entre 0.0 y 1.0.

### "Invalid pan: X. Must be -1.0 to 1.0"
- **Significado:** El paneo esta fuera del rango valido.
- **Solucion:** -1.0 = izquierda total, 0.0 = centro, 1.0 = derecha total.

### "Failed to create track"
- **Significado:** Ableton no pudo crear la pista.
- **Solucion:** Verificar que Ableton responde correctamente con `get_session_info()`. Reiniciar Remote Script si es necesario.

### "Unknown error"
- **Significado:** Error no especificado. Puede ser cualquier cosa.
- **Solucion:** Ejecutar `health_check()` para diagnosticar. Revisar el log de Ableton.

---

## Como Reiniciar el Sistema Correctamente

### Reinicio del Remote Script (sin cerrar Ableton)

1. **En Ableton Live:**
   - Ir a `Options > Preferences > Link/Tempo/MIDI`
   - En "Control Surfaces", cambiar `AbletonMCP_AI` a `None`
   - Esperar 2-3 segundos
   - Volver a seleccionar `AbletonMCP_AI`
   - Esperar 5-10 segundos

2. **Verificar la conexion:**
   ```
   Command: health_check()
   ```
   Deberia devolver score 5/5.

3. **Verificar el estado del proyecto:**
   ```
   Command: get_session_info()
   ```

### Reinicio Completo (cerrando Ableton)

1. **Guardar el proyecto en Ableton**
   - `File > Save` o `Ctrl+S`

2. **Cerrar Ableton Live**

3. **Esperar 5 segundos**

4. **Abrir Ableton Live de nuevo**

5. **Abrir el proyecto**
   - `File > Open Recent` o navegar al archivo `.als`

6. **Verificar que el Remote Script esta seleccionado:**
   - `Options > Preferences > Link/Tempo/MIDI`
   - Asegurarse de que `AbletonMCP_AI` esta seleccionado

7. **Esperar 10-15 segundos a que el Remote Script se inicialice**

8. **Ejecutar diagnosticos:**
   ```
   Command: health_check()
   Command: get_session_info()
   ```

### Reinicio del Servidor MCP

1. **Detener el servidor MCP actual** (Ctrl+C en la terminal donde corre)

2. **Reiniciar el servidor:**
   ```powershell
   python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py" --transport stdio
   ```

3. **Verificar la conexion desde el agente:**
   ```
   Command: ping()
   ```

---

## Log de Ableton Live

El log de Ableton es la fuente principal de informacion sobre errores del Remote Script.

### Ubicacion del Log
```
C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt
```

### Como leer el log

```powershell
# Ver las ultimas 120 lineas
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120

# Buscar errores especificos de AbletonMCP_AI
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" | Select-String "AbletonMCP"

# Buscar errores de socket
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" | Select-String "socket"
```

### Mensajes normales en el log
```
AbletonMCP_AI: Starting Remote Script
AbletonMCP_AI: TCP server listening on port 9877
AbletonMCP_AI: Connected client from 127.0.0.1
AbletonMCP_AI: Command received: get_session_info
AbletonMCP_AI: Response sent successfully
```

### Mensajes de error en el log
```
AbletonMCP_AI: ERROR - Failed to bind to port 9877
AbletonMCP_AI: ERROR - Connection refused
AbletonMCP_AI: ERROR - Invalid command: xxx
AbletonMCP_AI: ERROR - Exception in command handler: ...
```

---

## Herramientas de Diagnostico

### `health_check()` - Verificacion Principal

Ejecuta 5 chequeos automaticos:
1. **TCP Server** - Verifica conexion al puerto 9877
2. **Song** - Verifica que la cancion es accesible
3. **Tracks** - Verifica que las pistas son accesibles
4. **Browser** - Verifica que el navegador de samples es accesible
5. **Update Display** - Verifica que el bucle de actualizacion esta activo

### `get_memory_usage()` - Uso de Memoria

Requiere `psutil` instalado. Muestra:
- Memoria del proceso Python
- Memoria total del sistema
- Memoria disponible
- Numero de procesos de Ableton activos

### `get_progress_report()` - Progreso del Proyecto

Muestra:
- Porcentaje de completitud del proyecto
- Fases completadas
- Fase actual
- Tareas hechas vs total
- Tiempo invertido
- Hitos alcanzados

### `full_quality_check()` - Verificacion de Calidad

Analiza:
- Niveles de volumen
- Balance de frecuencias
- Imagen estereo
- Coherencia de fase
- Rango dinamico
- Conflictos de frecuencia
- Headroom disponible

### `validate_project()` - Validacion General

Verifica:
- Consistencia del proyecto
- Mejores practicas
- Problemas potenciales
- Puntuacion general

---

## Resumen de Acciones Rapidas

| Problema | Accion Rapida |
|----------|--------------|
| No conecta | Reiniciar Remote Script en Preferences |
| Timeouts | `stop_playback()` + `stop_all_clips()` + esperar 10s |
| Samples no cargan | Verificar ruta con `Test-Path` |
| Clips vacios | Verificar que tienen notas/audio |
| No suena | Verificar volumen y mute de pistas |
| Error desconocido | `health_check()` + revisar log |
| Sistema lento | `get_memory_usage()` + cerrar apps |
| Render falla | Verificar directorio de salida existe |

---

## Contacto y Soporte

Si ningun paso de troubleshooting resuelve el problema:

1. **Recolectar informacion:**
   - Resultado de `health_check()`
   - Ultimas 200 lineas del log de Ableton
   - Descripcion detallada del problema
   - Pasos que se intentaron

2. **Verificar versiones:**
   - Version de Ableton Live (debe ser 12 Suite)
   - Version de Python (debe ser 3.10+)
   - Version del Remote Script (ver en `__init__.py`)