ableton-mcp-ai/AbletonMCP_AI_BAK_20260328_200801/README.md

# AbletonMCP-AI

Sistema hibrido para controlar Ableton Live 12 desde MCP y generar proyectos musicales complejos, orientados a Arrangement View.

Combina:

- un Remote Script dentro de Live
- un servidor MCP en Python (52+ tools)
- seleccion de samples desde biblioteca local con busqueda semantica ML
- reconstruccion guiada por referencias
- fallback de audio y capas MIDI/instrumentos
- buses, returns y snapshots de mezcla por seccion
- mezcla harmonica Camelot wheel para DJ sets
- generacion Tech House DJ-ready con intro/outro extendidas

Esta es la snapshot del proyecto al 2026-03-28.

## Estado actual

El sistema ya puede:

- generar proyectos completos en Arrangement View con samples de la biblioteca local
- crear estructura, tracks, scenes, cue points y guide track
- combinar MIDI, instrumentos stock y audio de biblioteca local (827 samples indexados)
- analizar un track de referencia y reconstruir un resultado original inspirado en ese material
- materializar capas `AUDIO ...` con samples reales (kick, bass, synth, vocal, FX, etc.)
- aplicar snapshots por seccion a tracks y returns durante el commit Session -> Arrangement
- operar con returns desde el runtime y desde el MCP
- buses de mezcla (DRUM BUS, BASS BUS, MUSIC WIDE, VOCAL BUS, FX WASH)
- capas derivadas (RESAMPLE REVERSE FX, RISER, DOWNLIFTER, STUTTER)
- generar estructuras DJ-ready con intro/outro de 32 compases para beatmatching
- mezcla harmonica con Camelot wheel (compatible keys, sugerencias de transicion)
- auto-descubrir tracks de referencia desde `librerias/reference/`
- previsualizar blueprints sin crear nada en Ableton
- regenerar secciones individuales
- persistir historia de generaciones y diversidad de samples entre sesiones
- busqueda semantica enriquecida por genero (tech-house, house, techno, trance, etc.)
- auto-reindexar la biblioteca cuando cambian los archivos
- validar automaticamente el set post-generacion

## Arquitectura resumida

1. `__init__.py`
   Remote Script principal. Vive dentro de Ableton, abre el socket TCP y ejecuta comandos sobre la API de Live.
2. `MCP_Server/server.py`
   Servidor MCP/FastMCP. Expone tools, normaliza aliases y habla con el Remote Script.
3. `MCP_Server/song_generator.py`
   Generador musical. Construye blueprint de tracks, sections, performance, locators y returns.
4. `MCP_Server/reference_listener.py`
   Escucha el audio de referencia y arma un plan de reconstruccion usando la biblioteca local.
5. `MCP_Server/sample_manager.py`, `sample_selector.py`, `audio_analyzer.py`
   Indexado, busqueda, scoring y analisis de samples.
6. `MaxForLive/`
   Devices `.amxd` para la ruta hibrida con M4L.

## Layout del repo

```text
AbletonMCP_AI/
|-- __init__.py
|-- Remote_Script.py
|-- start_server.bat
|-- .mcp.json
|-- README.md
|-- CLAUDE.md
|-- MaxForLive/
|   |-- AbletonMCP_Engine.amxd
|   |-- AbletonMCP_Engine.maxpat
|   `-- AbletonMCP_SamplerPro.amxd
|-- MCP_Server/
|   |-- server.py
|   |-- song_generator.py
|   |-- reference_listener.py
|   |-- audio_analyzer.py
|   |-- sample_manager.py
|   |-- sample_selector.py
|   |-- sample_index.py
|   |-- socket_smoke_test.py
|   |-- template_analyzer.py
|   |-- ABLETUNES_TEMPLATE_NOTES.md
|   `-- requirements.txt
`-- docs/
    |-- AI_HANDOFF.md
    |-- ARCHITECTURE.md
    |-- GPU_DIRECTML.md
    |-- MCP_TOOLS.md
    |-- PROJECT_CONTEXT.md
    |-- REMOTE_PROTOCOL.md
    `-- SETUP_WINDOWS.md
```

## Documentacion

Leer primero:

- [CLAUDE.md](CLAUDE.md) - handoff amplio, cronologia completa, estado real, paths y notas operativas
- [AI_HANDOFF](docs/AI_HANDOFF.md) - handoff corto y operativo
- [PROJECT_CONTEXT](docs/PROJECT_CONTEXT.md) - direccion de producto y lecciones aprendidas

- [Arquitectura](docs/ARCHITECTURE.md)
- [Setup en Windows + Ableton](docs/SETUP_WINDOWS.md)
- [Tools MCP](docs/MCP_TOOLS.md)
- [Protocolo del Remote Script](docs/REMOTE_PROTOCOL.md)
- [GPU DirectML](docs/GPU_DIRECTML.md)
- [Notas del analisis de templates Abletunes](MCP_Server/ABLETUNES_TEMPLATE_NOTES.md)

## Quick start

### 1. Clonar y colocar en la carpeta de Ableton

```powershell
# Clonar el repo
git clone https://gitea.cbcren.online/renato97/ableton-mcp-ai.git

# Copiar a la carpeta de MIDI Remote Scripts
cp -r ableton-mcp-ai "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI"
```

### 2. Instalar dependencias Python

```powershell
cd "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\MCP_Server"
python -m pip install -r requirements.txt
```

### 3. Seleccionar el Control Surface en Live

- Abrir Ableton Live 12.
- Ir a `Preferences > Link/Tempo/MIDI`.
- Elegir `AbletonMCP_AI` como `Control Surface`.

### 4. Levantar el servidor MCP

```powershell
cd "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI"
python MCP_Server/server.py
```

O:

```powershell
start_server.bat
```

### 5. Probar conexion

```powershell
cd "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\MCP_Server"
python socket_smoke_test.py
```

## Ubicaciones externas esperadas

Este repo no incluye bibliotecas pesadas ni material generado. El stack espera estos recursos fuera del repo:

- biblioteca principal de samples (organizada por categorias):
  `..\librerias\organized_samples` (827 samples indexados)
- biblioteca raw original:
  `..\librerias\all_tracks`
- vector store para matching ML:
  `..\librerias\vector_store`
- Ableton User Library para instalar el sampler M4L:
  `%USERPROFILE%\Documents\Ableton\User Library`
- referencias MP3/WAV que se quieran analizar:
  `..\sample`
- proyectos `.als`, renders y stems

## Flujo recomendado

1. Resetear el set.
2. Generar un track desde MCP o por socket.
3. Validar que el commit termine en Arrangement View.
4. Revisar audio tracks `AUDIO ...` y returns.
5. Ajustar perfiles, matching y snapshots.

## Comandos utiles

Generacion completa:

```text
generate_track(genre="tech-house", style="latin-industrial", bpm=0, key="", structure="standard")
generate_track(genre="tech-house", style="groovy", bpm=126, key="Am", structure="tech-house-dj")
generate_song(genre="tech-house", style="latin-industrial", bpm=0, key="", structure="club")
```

DJ / Harmonic mixing:

```text
get_harmonic_keys(key="Am")
get_compatible_keys(key="Am")
export_stems_config()
discover_reference_track()
get_reference_suggestions()
```

Utilidades de generacion:

```text
preview_generation(genre="tech-house", style="groovy", bpm=126, key="Am", structure="tech-house-dj")
regenerate_section(section_name="DROP A")
get_generation_history()
```

Transporte:

```text
start_playback()
stop_playback()
set_tempo(126)
```

Samples:

```text
search_samples("kick", category="kick", limit=10)
advanced_search_samples(query="vocal", category="vocals", bpm=128, key="F#m")
analyze_audio_file("C:\\ruta\\track.mp3")
```

## Licencia

Sin licencia publicada por ahora. Tratar este repo como privado/interno hasta definirla.