# AbletonMCP-AI API Documentation

## MCP Tools Disponibles

### Generación

#### `generate_song(genre, bpm, key, style, structure)`
Genera un track completo con todas las capas de audio.

**Parámetros:**
- `genre` (str): Género musical (techno, house, trance, etc)
- `bpm` (float): BPM deseado (0 = auto)
- `key` (str): Tonalidad (ej: "F#m", "Am")
- `style` (str): Sub-estilo (industrial, deep, etc)
- `structure` (str): Tipo de estructura (standard, minimal, extended)

**Ejemplo:**
```python
result = generate_song("techno", 138, "F#m", "industrial", "standard")
```

#### `generate_with_human_feel(genre, bpm, key, humanize, groove_style)`
Genera un track con humanización aplicada.

**Parámetros adicionales:**
- `humanize` (bool): Aplicar variaciones de timing/velocity
- `groove_style` (str): Tipo de groove (straight, shuffle, triplet, latin)

**Ejemplo:**
```python
result = generate_with_human_feel("house", 124, "Am", True, "shuffle")
```

### Palette y Samples

#### `set_palette_lock(drums, bass, music)`
Fuerza carpetas ancla específicas para la generación.

**Parámetros:**
- `drums` (str): Path a carpeta de drums
- `bass` (str): Path a carpeta de bass
- `music` (str): Path a carpeta de music/synths

**Ejemplo:**
```python
set_palette_lock(
    drums="librerias/Kick Loops",
    bass="librerias/Bass Loops",
    music="librerias/Synth Loops"
)
```

#### `get_coverage_wheel_report()`
Retorna heatmap de uso de carpetas de samples.

**Retorna:**
- Lista de carpetas ordenadas por uso
- Heat levels (FROZEN, COOL, WARM, HOT)
- Sugerencias de carpetas bajo-usadas

#### `get_sample_fatigue_report()`
Retorna reporte de fatiga de samples.

**Retorna:**
- Top samples más usados
- Factor de fatiga por rol
- Thresholds de penalización

#### `reset_sample_fatigue(role)`
Resetea la fatiga de samples.

**Parámetros:**
- `role` (str, opcional): Si especificado, solo resetea ese rol

### Validación

#### `validate_set(check_routing, check_gain, check_clips)`
Valida el set completo de Ableton.

**Checks:**
- Routing de tracks
- Niveles de gain staging
- Clips vacíos
- Conflictos armónicos

#### `validate_audio_layers()`
Valida específicamente los tracks de audio.

#### `get_generation_manifest()`
Retorna el manifest de la última generación.

### Memory y Diversidad

#### `reset_diversity_memory()`
Limpia la memoria de diversidad entre generaciones.

#### `get_sample_coverage_report()`
Retorna reporte de cobertura de samples usados.

## Engines de Procesamiento

### HumanFeelEngine

Aplica humanización a patrones MIDI.

```python
from human_feel import HumanFeelEngine

engine = HumanFeelEngine(seed=42)
notes = [{'pitch': 60, 'start': 0.0, 'velocity': 100}]

# Aplicar timing variation
result = engine.apply_timing_variation(notes, amount_ms=5.0)

# Aplicar velocity humanize
result = engine.apply_velocity_humanize(result, variance=0.05)

# Aplicar groove
result = engine.apply_groove(result, style='shuffle', amount=0.5)

# Aplicar dinámica por sección
result = engine.apply_section_dynamics(result, section='drop')
```

### DJArrangementEngine

Genera estructuras DJ-friendly.

```python
from audio_arrangement import DJArrangementEngine

engine = DJArrangementEngine(seed=42)

# Generar estructura
structure = engine.generate_structure("standard")

# Verificar si es DJ-friendly
is_friendly = engine.is_dj_friendly(structure)

# Generar curva de energía
automation = engine.generate_energy_automation(structure)
```

### SoundscapeEngine

Gestiona ambientes y texturas.

```python
from audio_soundscape import SoundscapeEngine

engine = SoundscapeEngine()

# Detectar gaps
gaps = engine.detect_ambience_gaps(timeline)

# Llenar con atmos
atmos = engine.fill_with_atmos(gaps, genre="techno", key="F#m")
```

### MasterChain

Configura cadena de mastering.

```python
from audio_mastering import MasterChain, MasteringPreset

# Crear chain
chain = MasterChain()

# Aplicar preset
preset = MasteringPreset.get_preset("club")
chain.set_limiter_ceiling(preset['ceiling'])

# Obtener chain para Ableton
devices = chain.get_ableton_device_chain()
```

### AutoPrompter

Genera configuraciones desde descripciones de vibe.

```python
from self_ai import AutoPrompter

prompter = AutoPrompter()

# Generar desde vibe
params = prompter.generate_from_vibe("dark warehouse techno")
# Retorna: genre, bpm, key, style, structure
```

## Pipeline Completo

```python
from full_integration import generate_complete_track

# Generación completa con todas las fases
track = generate_complete_track("deep house sunset", seed=42)

# El resultado incluye:
# - vibe_params
# - structure
# - transitions
# - atmos_events
# - fx_events
# - master_chain
# - human_feel config
```

## Sistema de Fatiga

El sistema de fatiga evita la repetición de samples:

- 0 usos: factor 1.0 (sin penalización)
- 1-3 usos: factor 0.75
- 4-10 usos: factor 0.50
- 10+ usos: factor 0.20

## Palette Bonus

Sistema de scoring por compatibilidad de carpeta:

- Folder ancla exacto: 1.4x
- Subfolder del ancla: 1.3x
- Folder hermano (mismo padre): 1.2x
- Folder diferente: 0.9x

## Testing

Ejecutar tests:

```bash
cd AbletonMCP_AI/MCP_Server
python -m unittest tests.test_sample_selector tests.test_human_feel tests.test_integration -v
```

## Constantes Importantes

### Energy Profiles
- intro: 30%
- build: 70%
- drop: 100%
- break: 50%
- outro: 20%

### Loudness Targets
- streaming: -14 LUFS
- club: -8 LUFS
- safe: -12 LUFS

### Master Chain
- Utility (gain staging)
- Saturator (drive 1.5)
- Compressor (ratio 2:1)
- Limiter (ceiling -0.3dB)