ableton-mcp-ai/docs/TROUBLESHOOTING.md

TROUBLESHOOTING - AbletonMCP_AI

Guia de solucion de problemas para el sistema AbletonMCP_AI.

Tabla de Contenidos

1. Diagnosticos Iniciales
2. Problemas deConexion con Ableton
3. Problemas de Carga de Samples
4. Problemas de Clips
5. Problemas de Generacion Musical
6. Problemas de Mezcla
7. Problemas de Export/Render
8. Mensajes de Error Comunes
9. Como Reiniciar el Sistema Correctamente
10. Log de Ableton Live
11. 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):

{
  "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:

{
  "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:

{
  "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:

   netstat -an | findstr 9877
   

   Deberia mostrar una linea con LISTENING en 127.0.0.1:9877.

5. Revisar el log de Ableton:

   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:

   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:

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

   {
     "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:

   Test-Path "C:\Users\ren\Desktop\stems\"
   

2. Crear el directorio si no existe:

   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:

   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

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