Files
ableton-mcp-ai/docs/GUIA_DE_USO.md
OpenCode Agent 5ce8187c65 feat: Implement senior audio injection with 5 fallback methods
- Add _cmd_create_arrangement_audio_pattern with 5-method fallback chain
- Method 1: track.insert_arrangement_clip() [Live 12+]
- Method 2: track.create_audio_clip() [Live 11+]
- Method 3: arrangement_clips.add_new_clip() [Live 12+]
- Method 4: Session->duplicate_clip_to_arrangement [Legacy]
- Method 5: Session->Recording [Universal]

- Add _cmd_duplicate_clip_to_arrangement for session-to-arrangement workflow
- Update skills documentation
- Verified: 3 clips created at positions [0, 4, 8] in Arrangement View

Closes: Audio injection in Arrangement View
2026-04-12 14:02:32 -03:00

24 KiB

GUIA DE USO - AbletonMCP_AI

Sistema MCP para control de Ableton Live 12 Suite mediante agentes de inteligencia artificial.

Tabla de Contenidos

  1. Introduccion
  2. Herramientas MCP Completas
  3. Categoria: Informacion
  4. Categoria: Transporte
  5. Categoria: Pistas
  6. Categoria: Clips
  7. Categoria: Samples y Libreria
  8. Categoria: Mezcla y Efectos
  9. Categoria: Arrangement
  10. Categoria: Generacion y Produccion
  11. Categoria: Inteligencia Musical
  12. Categoria: Workflow y Export
  13. Categoria: Diagnosticos
  14. Categoria: Sistema
  15. Orden Recomendado para Produccion

Introduccion

AbletonMCP_AI es un servidor MCP (Model Context Protocol) que permite a agentes de IA controlar Ableton Live 12 Suite de forma programatica. El sistema se comunica con Ableton a traves de un socket TCP en el puerto 9877.

Requisitos

  • Ableton Live 12 Suite (obligatorio)
  • Python 3.10+
  • Dependencias: mcp>=1.0.0, numpy, librosa (opcional para analisis espectral)
  • Biblioteca de samples: libreria/reggaeton con samples organizados por rol

Arquitectura

Agente IA <--> MCP Server (server.py) <--> Socket TCP:9877 <--> Ableton Remote Script

Herramientas MCP Completas

El sistema cuenta con 118+ herramientas MCP organizadas en las siguientes categorias:

Categoria Cantidad Proximas
Informacion 5 get_session_info, get_tracks, get_scenes, get_master_info, health_check
Transporte 4 start_playback, stop_playback, toggle_playback, stop_all_clips
Pistas 9 create_midi_track, create_audio_track, set_track_name, set_track_volume, set_track_pan, set_track_mute, set_track_solo, set_master_volume, set_tempo
Clips 6 create_clip, add_notes_to_clip, fire_clip, fire_scene, set_scene_name, create_scene
Samples y Libreria 8 analyze_library, get_library_stats, get_similar_samples, find_samples_like_audio, get_user_sound_profile, get_recommended_samples, compare_two_samples, browse_library
Mezcla y Efectos 10 create_bus_track, route_track_to_bus, create_return_track, set_track_send, insert_device, configure_eq, configure_compressor, setup_sidechain, auto_gain_staging, apply_master_chain
Arrangement 8 create_arrangement_audio_pattern, load_sample_to_clip, load_sample_to_drum_rack, set_warp_markers, reverse_clip, pitch_shift_clip, time_stretch_clip, slice_clip
Generacion y Produccion 15 generate_track, generate_song, select_samples_for_genre, generate_complete_reggaeton, generate_from_reference, produce_reggaeton, produce_from_reference, produce_arrangement, complete_production, batch_produce, generate_midi_clip, generate_dembow_clip, generate_bass_clip, generate_chords_clip, generate_melody_clip
Inteligencia Musical 10 analyze_project_key, harmonize_track, generate_counter_melody, detect_energy_curve, balance_sections, variate_loop, add_call_and_response, generate_breakdown, generate_drop_variation, create_outro
Workflow y Export 14 export_project, get_project_summary, suggest_improvements, validate_project, humanize_track, render_stems, render_full_mix, render_instrumental, full_quality_check, fix_quality_issues, duplicate_project, create_radio_edit, create_dj_edit, get_production_report
Diagnosticos 3 health_check, get_memory_usage, get_progress_report
Sistema 7 ping, help, get_workflow_status, undo, redo, save_checkpoint, set_time_signature, set_metronome

TOTAL: 118+ herramientas


Categoria: Informacion

get_session_info

Obtiene informacion completa de la sesion actual de Ableton Live.

Respuesta: tempo, numero de pistas, numero de escenas, estado de reproduccion, tiempo actual,ometro, volumen master.

Ejemplo de uso:

Primera herramienta a ejecutar despues de abrir Ableton.

get_tracks

Obtiene la lista de todas las pistas del proyecto actual.

Respuesta: indice, nombre, tipo (MIDI/audio), volumen, paneo, mute, solo de cada pista.

get_scenes

Obtiene la lista de todas las escenas en Session View.

Respuesta: indice, nombre, clips asociados.

get_master_info

Obtiene informacion de la pista master.

Respuesta: volumen master, dispositivos en la cadena master.

health_check

Verificacion completa del sistema AbletonMCP_AI. Ejecuta 5 chequeos:

  1. Conexion al servidor TCP
  2. Accesibilidad de la cancion
  3. Accesibilidad de pistas
  4. Accesibilidad del navegador
  5. Estado del bucle de actualizacion

Respuesta: puntuacion 0-5 con estado detallado de cada chequeo.

Ejemplo de uso:

SIEMPRE ejecutar como primer comando despues de abrir Ableton.
Si el score es menor a 3/5, reiniciar el Remote Script.

Categoria: Transporte

start_playback

Inicia la reproduccion del proyecto.

stop_playback

Detiene la reproduccion.

toggle_playback

Alterna entre reproduccion y parada.

stop_all_clips

Detiene todos los clips en Session View.


Categoria: Pistas

create_midi_track

Crea una nueva pista MIDI.

  • Parametros: index (int, default -1 = al final)

create_audio_track

Crea una nueva pista de audio.

  • Parametros: index (int, default -1 = al final)

set_track_name

Establece el nombre de una pista.

  • Parametros: track_index (int), name (str)

set_track_volume

Establece el volumen de una pista.

  • Parametros: track_index (int), volume (float, 0.0-1.0)

set_track_pan

Establece el paneo de una pista.

  • Parametros: track_index (int), pan (float, -1.0 a 1.0)

set_track_mute

Silencia o reactiva una pista.

  • Parametros: track_index (int), mute (bool)

set_track_solo

Activa o desactiva solo en una pista.

  • Parametros: track_index (int), solo (bool)

set_master_volume

Establece el volumen master.

  • Parametros: volume (float, 0.0-1.0)

set_tempo

Establece el tempo del proyecto.

  • Parametros: tempo (float, 20-300 BPM)

set_time_signature

Establece la firma de tiempo.

  • Parametros: numerator (int, default 4), denominator (int, default 4)

set_metronome

Activa o desactiva el metroonomo.

  • Parametros: enabled (bool)

Categoria: Clips

create_clip

Crea un clip MIDI en Session View.

  • Parametros: track_index (int), clip_index (int, default 0), length (float, default 4.0)

add_notes_to_clip

Aniade notas MIDI a un clip.

  • Parametros: track_index (int), clip_index (int), notes (lista de dicts con pitch, start_time, duration, velocity)

Ejemplo:

{
  "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}
  ]
}

fire_clip

Dispara un clip en Session View.

  • Parametros: track_index (int), clip_index (int, default 0)

fire_scene

Dispara una escena completa en Session View.

  • Parametros: scene_index (int)

set_scene_name

Establece el nombre de una escena.

  • Parametros: scene_index (int), name (str)

create_scene

Crea una nueva escena.

  • Parametros: index (int, default -1 = al final)

Categoria: Samples y Libreria

analyze_library

Analiza todos los samples en la libreria de reggaeton. Extrae BPM, tonalidad, MFCCs, etc.

  • Parametros: force_reanalyze (bool, default False)

Ejemplo de uso:

Primer paso antes de cualquier produccion. Analiza la biblioteca completa.
Puede tardar varios minutos dependiendo del numero de samples.

get_library_stats

Obtiene estadisticas de la libreria analizada.

Respuesta: total de archivos, distribucion por rol (kick, snare, hat, bass, etc.), distribucion por BPM y tonalidad.

get_similar_samples

Encuentra samples similares a uno dado usando embeddings.

  • Parametros: sample_path (str), top_n (int, default 10)

find_samples_like_audio

Encuentra samples similares a un archivo de audio externo.

  • Parametros: audio_path (str), top_n (int, default 20), role (str, opcional)

get_user_sound_profile

Obtiene el perfil de sonido del usuario basado en reggaeton_ejemplo.mp3.

Respuesta: caracteristicas sonicAs preferidas del usuario.

Obtiene samples recomendados para un rol basado en el perfil del usuario.

  • Parametros: role (str, opcional), count (int, default 5)

Ejemplo:

{"role": "kick", "count": 5}

compare_two_samples

Compara dos samples y devuelve puntuacion de similitud.

  • Parametros: path1 (str), path2 (str)

browse_library

Navega la libreria con filtros.

  • Parametros: pack (str), role (str), bpm_min (float), bpm_max (float), key (str)

Ejemplo:

{"role": "kick", "bpm_min": 90, "bpm_max": 100}

Categoria: Mezcla y Efectos

create_bus_track

Crea un grupo (bus) para mezcla.

  • Parametros: bus_type (str, default "Group")

route_track_to_bus

Rutea una pista a un bus/grupo.

  • Parametros: track_index (int), bus_name (str)

create_return_track

Crea una pista de retorno con un efecto.

  • Parametros: effect_type (str, default "Reverb")
  • Efectos disponibles: REVERB, DELAY, CHORUS, FLANGER, PHASER, COMPRESSOR, EQ

set_track_send

Configura el envio de una pista a una pista de retorno.

  • Parametros: track_index (int), return_index (int), amount (float, 0.0-1.0)

insert_device

Inserta un dispositivo/plugin en una pista.

  • Parametros: track_index (int), device_name (str)

configure_eq

Configura EQ Eight en una pista con un preset.

  • Parametros: track_index (int), preset (str, default "default")

configure_compressor

Configura un compresor en una pista.

  • Parametros: track_index (int), preset (str), threshold (float, default -20.0), ratio (float, default 4.0)

setup_sidechain

Configura compresion sidechain de una pista a otra.

  • Parametros: source_track (int), target_track (int), amount (float, 0.0-1.0)

auto_gain_staging

Ajusta automaticamente los niveles de ganancia de todas las pistas.

apply_master_chain

Aplica una cadena de mastering al master.

  • Parametros: preset (str, default "standard")
  • Presets disponibles: reggaeton_streaming, vinyl, club

Categoria: Arrangement

create_arrangement_audio_pattern

Crea clips de audio en Arrangement View desde un archivo .wav.

  • Parametros: track_index (int), file_path (str), positions (lista, default [0]), name (str)

load_sample_to_clip

Carga un sample en un slot de clip de Session View.

  • Parametros: track_index (int), clip_index (int), sample_path (str)

load_sample_to_drum_rack

Carga un sample en un pad especifico de un Drum Rack.

  • Parametros: track_index (int), sample_path (str), pad_note (int, default 36 = C1)

set_warp_markers

Configura marcadores de warp para un clip de audio.

  • Parametros: track_index (int), clip_index (int), markers (lista de dicts con position y warp_to)

reverse_clip

Invierte un clip de audio o MIDI.

  • Parametros: track_index (int), clip_index (int)

pitch_shift_clip

Cambia el tono de un clip sin afectar el tempo (usa Complex Pro).

  • Parametros: track_index (int), clip_index (int), semitones (float, -24 a +24)

time_stretch_clip

Estira el tiempo de un clip sin afectar el tono.

  • Parametros: track_index (int), clip_index (int), factor (float, 0.25 a 4.0)

slice_clip

Divide un clip de audio en multiples segmentos.

  • Parametros: track_index (int), clip_index (int), num_slices (int, default 8, max 64)

Categoria: Generacion y Produccion

generate_track

Genera una pista usando IA.

  • Parametros: genre (str), style (str), bpm (float), key (str), structure (str)

generate_song

Genera una cancion completa.

  • Parametros: genre (str), style (str), bpm (float), key (str), structure (str)

select_samples_for_genre

Selecciona samples para un genero de la libreria local.

  • Parametros: genre (str), key (str), bpm (float)

generate_complete_reggaeton

Genera un proyecto completo de reggaeton con todos los elementos.

  • Parametros: bpm (float, default 95), key (str, default "Am"), style (str: "classic", "dembow", "perreo", "moombahton"), structure (str: "verse-chorus", "full", "intro-drop"), use_samples (bool, default True)

generate_from_reference

Genera una pista usando un audio de referencia para匹配 de estilo.

  • Parametros: reference_audio_path (str)

produce_reggaeton

Pipeline completo de produccion de reggaeton.

  • Parametros: bpm (float, default 95), key (str, default "Am"), style (str), structure (str)

produce_from_reference

Genera produccion desde un audio de referencia.

  • Parametros: audio_path (str)

produce_arrangement

Genera produccion directamente en Arrangement View.

  • Parametros: bpm (float, default 95), key (str, default "Am"), style (str)

complete_production

Pipeline completo de produccion con renderizado.

  • Parametros: bpm (float, default 95), key (str, default "Am"), style (str), output_dir (str)

batch_produce

Produce multiples canciones en lote.

  • Parametros: count (int, default 3, max 10), style (str), bpm_range (str: "min-max")

generate_midi_clip

Crea un clip MIDI con notas especificas.

  • Parametros: track_index (int), clip_index (int, default 0), notes (lista)

generate_dembow_clip

Genera un clip MIDI con patron dembow clasico de reggaeton.

  • Parametros: track_index (int), clip_index (int, default 0), bars (int, default 4), variation (str: "standard", "minimal", "complex", "fill")

generate_bass_clip

Genera un clip MIDI de linea de bajo estilo reggaeton.

  • Parametros: track_index (int), clip_index (int, default 0), bars (int, default 4), root_notes (lista), style (str: "standard", "melodic", "staccato", "slides")

generate_chords_clip

Genera un clip MIDI de progresion de acordes.

  • Parametros: track_index (int), clip_index (int, default 0), bars (int, default 4), progression (str: "i-v-vi-iv", "i-iv-v", "i-vi-iv-v", etc.), key (str, default "Am")

generate_melody_clip

Genera un clip MIDI de linea melodica para reggaeton.

  • Parametros: track_index (int), clip_index (int, default 0), bars (int, default 4), scale (str: "minor", "major", "harmonic_minor", "pentatonic"), density (str: "sparse", "medium", "dense")

load_samples_for_genre

Selecciona y carga samples para un genero.

  • Parametros: genre (str), key (str), bpm (float)

create_drum_kit

Crea un drum kit cargando samples en un Drum Rack.

  • Parametros: track_index (int), kick_path (str), snare_path (str), hat_path (str), clap_path (str)

build_track_from_samples

Construye una pista completa desde samples de la libreria.

  • Parametros: track_type (str: "drums", "bass", "melody", "fx"), sample_role (str)

generate_full_song

Genera una cancion completa con drums, bass, chords y melody.

  • Parametros: bpm (float, default 95), key (str, default "Am"), style (str), structure (str)

generate_track_from_config

Genera una pista desde una configuracion JSON.

  • Parametros: track_config_json (str JSON)

generate_section

Genera una seccion de cancion desde configuracion JSON.

  • Parametros: section_config_json (str JSON), start_bar (int, default 0)

apply_human_feel

Aplica humanizacion a una pista MIDI.

  • Parametros: track_index (int), intensity (float, 0.0-1.0)

add_percussion_fills

Aniade fills de percusion en posiciones especificas.

  • Parametros: track_index (int), positions (lista de ints, default [7, 15, 23, 31])

Categoria: Inteligencia Musical

analyze_project_key

Detecta la tonalidad predominante del proyecto actual.

harmonize_track

Armoniza una pista con una progresion de acordes.

  • Parametros: track_index (int), progression (str: "I-V-vi-IV", "ii-V-I", "I-IV-V")

generate_counter_melody

Genera una contra-melodia que complementa la melodia principal.

  • Parametros: main_melody_track (int)

detect_energy_curve

Analiza la curva de energia por seccion del proyecto.

balance_sections

Ajusta automaticamente la energia entre secciones.

variate_loop

Cria variaciones de un loop para evitar repetitividad.

  • Parametros: track_index (int), intensity (float, 0.0-1.0)

add_call_and_response

Genera una respuesta musical a una frase existente.

  • Parametros: phrase_track (int), response_length (int, default 2)

generate_breakdown

Genera una seccion de breakdown/descanso.

  • Parametros: start_bar (int), duration (int, default 8)

generate_drop_variation

Genera una variacion de un drop existente.

  • Parametros: original_drop_bar (int), variation_type (str: "intense", "minimal", "double", "fill")

create_outro

Crea un outro con fade out automatico.

  • Parametros: fade_duration (int, default 8)

Categoria: Workflow y Export

export_project

Exporta el proyecto a un archivo de audio.

  • Parametros: path (str), format (str, default "wav")

get_project_summary

Obtiene un resumen del proyecto actual.

suggest_improvements

Obtiene sugerencias de IA para mejorar el proyecto.

validate_project

Valida la consistencia del proyecto y mejores practicas.

humanize_track

Aplica humanizacion a una pista MIDI.

  • Parametros: track_index (int), intensity (float, 0.0-1.0)

load_preset

Carga un preset en el proyecto actual.

  • Parametros: preset_name (str)

save_as_preset

Guarda el proyecto actual como preset.

  • Parametros: name (str), description (str)

list_presets

Lista todos los presets disponibles.

create_custom_preset

Crea un preset personalizado desde cero.

  • Parametros: name (str), description (str)

render_stems

Renderiza stems individuales para mezcla externa.

  • Parametros: output_dir (str)

render_full_mix

Renderiza el mix completo masterizado.

  • Parametros: output_path (str)

render_instrumental

Renderiza version instrumental (sin voces).

  • Parametros: output_path (str)

full_quality_check

Verificacion de calidad completa del proyecto.

fix_quality_issues

Arregla automaticamente problemas detectados.

  • Parametros: issues (lista, opcional)

duplicate_project

Duplica el proyecto actual con nuevo nombre.

  • Parametros: new_name (str)

create_radio_edit

Crea version radio edit (corta, sin intros largas).

  • Parametros: output_path (str)

create_dj_edit

Crea version DJ edit (extended intro/outro, cue points).

  • Parametros: output_path (str)

get_production_report

Genera un reporte completo de produccion.


Categoria: Diagnosticos

health_check

Verificacion completa del sistema (5 chequeos, score 0-5).

get_memory_usage

Obtiene el uso de memoria del sistema y del proyecto.

Respuesta: memoria del proceso, memoria del sistema, procesos de Ableton activos.

get_progress_report

Reporte detallado de progreso del proyecto actual.

Respuesta: porcentaje de completitud, fases completadas, fase actual, tareas hechas/total, tiempo invertido, hitos.


Categoria: Sistema

ping

Ping simple para verificar conectividad MCP sin necesitar Ableton.

help

Lista todas las herramientas disponibles con descripcion.

  • Sin parametros: lista todas las herramientas
  • Con parametro: ayuda detallada de una herramienta especifica

get_workflow_status

Obtiene el estado actual del workflow de produccion.

undo

Deshace la ultima accion.

redo

Rehace la ultima accion deshecha.

save_checkpoint

Guarda un checkpoint del proyecto actual.

  • Parametros: name (str, default "auto")

set_multiple_progressions

Configura progresiones de acordes para multiples secciones.

  • Parametros: progressions_config (lista de dicts)

modulate_key

Modula a una nueva tonalidad en una seccion especifica.

  • Parametros: section_index (int), new_key (str)

enable_parallel_processing

Activa/desactiva procesamiento paralelo.

  • Parametros: enabled (bool, default True)

Orden Recomendado para Produccion

Flujo Completo de Produccion de Reggaeton

Fase 1: Verificacion Inicial

  1. health_check() - Verificar que todo funciona (score debe ser 5/5)
  2. get_session_info() - Ver estado actual del proyecto
  3. analyze_library() - Analizar la biblioteca de samples (si no se ha hecho)
  4. get_user_sound_profile() - Conocer el perfil de sonido

Fase 2: Seleccion de Samples 5. get_recommended_samples(role="kick", count=5) - Obtener samples recomendados 6. browse_library(role="snare", bpm_min=90, bpm_max=100) - Navegar libreria 7. compare_two_samples(path1, path2) - Comparar samples candidatos

Fase 3: Configuracion del Proyecto 8. set_tempo(tempo=95) - Establecer tempo 9. set_time_signature(numerator=4, denominator=4) - Firma de tiempo 10. create_midi_track() - Crear pista de drums 11. create_audio_track() - Crear pista de audio para samples

Fase 4: Generacion Musical 12. generate_dembow_clip(track_index=0, bars=4, variation="standard") - Patron dembow 13. generate_bass_clip(track_index=1, bars=4, style="standard") - Linea de bajo 14. generate_chords_clip(track_index=2, bars=4, progression="i-v-vi-iv", key="Am") - Acordes 15. generate_melody_clip(track_index=3, bars=4, scale="minor", density="medium") - Melodia

Fase 5: Produccion Completa 16. produce_reggaeton(bpm=95, key="Am", style="classic", structure="verse-chorus") - Pipeline completo 17. apply_human_feel(track_index=0, intensity=0.3) - Humanizar drums 18. add_percussion_fills(track_index=0, positions=[7, 15, 23, 31]) - Aniade fills

Fase 6: Mezcla 19. create_bus_track(bus_type="Drums") - Crear bus de drums 20. route_track_to_bus(track_index=0, bus_name="Drums") - Rutear pistas al bus 21. configure_eq(track_index=0, preset="kick_boost") - Configurar EQ 22. configure_compressor(track_index=0, threshold=-20.0, ratio=4.0) - Configurar compresor 23. setup_sidechain(source_track=1, target_track=0, amount=0.5) - Sidechain bass a kick 24. auto_gain_staging() - Ajuste automatico de ganancia 25. apply_master_chain(preset="reggaeton_streaming") - Cadena de mastering

Fase 7: Verificacion 26. full_quality_check() - Verificacion de calidad 27. fix_quality_issues() - Arreglar problemas detectados 28. validate_project() - Validacion final

Fase 8: Export 29. render_stems(output_dir="C:\\Users\\ren\\Desktop\\stems\\") - Renderizar stems 30. render_full_mix(output_path="C:\\Users\\ren\\Desktop\\mix_final.wav") - Mix final 31. create_radio_edit(output_path="C:\\Users\\ren\\Desktop\\radio_edit.wav") - Version radio 32. create_dj_edit(output_path="C:\\Users\\ren\\Desktop\\dj_edit.wav") - Version DJ

Flujo Rapido (Produccion en 1 Comando)

Para produccion rapida, usar directamente:

produce_reggaeton(bpm=95, key="Am", style="classic", structure="verse-chorus")

Este comando ejecuta automaticamente todas las fases de generacion.

Flujo desde Referencia

Para producir basado en una pista de referencia:

produce_from_reference(audio_path="C:\\Users\\ren\\Desktop\\referencia.mp3")

Notas Importantes

  • Todos los tiempos estan en segundos. Algunas operaciones pueden tardar hasta 300s.
  • Las rutas de archivos deben ser rutas absolutas de Windows.
  • Los indices de pistas son 0-based (la primera pista es indice 0).
  • El puerto TCP por defecto es 9877. Si falla, verificar que el Remote Script este cargado en Ableton.
  • La biblioteca de samples debe estar en libreria/reggaeton con estructura de carpetas por rol (kick, snare, hat, bass, synths, fx).