# 🎛️ AbletonMCP AI — Roadmap a Calidad DJ Profesional

> **Documento Maestro** | 28-Mar-2026
> Basado en: `server.py`, `sample_selector.py`, `glm_coherence_diversity.md`, `glm_sample_intelligence.md`, `human_feel.md`
>
> Objetivo: evolucionar el sistema desde un generador MIDI funcional a una herramienta de producción Tech House de **calidad de lanzamiento DJ profesional (DJ Hertz, Innervisions, Get Physical)**.

---

## 🗺️ Mapa de fases

| Fase | Nombre | Estado | Tareas |
|------|--------|--------|--------|
| **0** | Fundación y estabilidad | ✅ DONE | T001–T010 |
| **1** | Inteligencia de samples | 🔴 P1 | T011–T024 |
| **2** | Coherencia musical & Paleta | 🔴 P1 | T025–T039 |
| **3** | Human Feel & Dinámicas | 🟠 P2 | T040–T050 |
| **4** | Soundscape & Tonal | 🟠 P2 | T051–T062 |
| **5** | Arranjo y estructura DJ | 🟡 P3 | T063–T077 |
| **6** | Masterización & Lanzamiento | 🟡 P3 | T078–T090 |
| **7** | IA Autónoma y Aprendizaje | 🔵 FUTURO | T091–T110 |

---

## FASE 0 — Fundación y Estabilidad ✅

- [x] **T001** — Migrar proyecto a `C:\Users\ren\AbletonMCP_AI` con junction a `ProgramData`
- [x] **T002** — Crear `start_server.bat` con `PYTHONPATH` correcto
- [x] **T003** — Sincronizar `opencode.json` y `.opencode.json` apuntando a ruta nueva
- [x] **T004** — Verificar que `server.py` arranca sin errores en log
- [x] **T005** — Confirmar que `SampleManager` carga la librería completa en `librerias\all_tracks`
- [x] **T006** — Confirmar conexión MCP activa y visible en cliente AI
- [x] **T007** — Resolver permisos NTFS en `ProgramData` para edición directa
- [x] **T008** — Configurar logging a nivel INFO en producción
- [x] **T009** — Integrar estructura de errores: `MCPError`, `ValidationError`, `TimeoutError`
- [x] **T010** — Pipeline end-to-end: generar 1 canción y verificar que carga en Ableton

---

## FASE 1 — Inteligencia de Samples 🔴 PRIORIDAD MÁXIMA

> **Goal**: De 800 samples disponibles, el sistema usa todos inteligentemente, sin repetir, con coherencia tonal.

### 1.A — Fix de repetición (impacto inmediato)

- [ ] **T011** — `server.py → _find_library_file()`: aumentar `limit` de semantic search de `10` a `50`
  - Bug actual: solo se evalúan 10 resultados; si tienen penalización de diversidad, el sistema queda atascado en los mismos archivos.

- [ ] **T012** — `sample_selector.py → select_sample()`: shuffled candidate pool con `session_seed`
  - Antes de scorear, aplicar `random.shuffle()` al pool con seed basado en timestamp de la generación.

- [ ] **T013** — `server.py → _build_audio_fallback_sample_paths()`: bucket sampling por subcarpeta
  - Limitar a máximo 15 archivos por subcarpeta. Garantiza que samples de distintas colecciones entren al pool.

- [ ] **T014** — Verificar y reparar persistencia de `sample_history.json` entre reinicios del servidor
  - Si el archivo no existe al arrancar: inicializar con diccionario vacío (no con None).

- [ ] **T015** — Herramienta MCP `get_sample_coverage_report()`
  - Devolver: % de cobertura por subcarpeta, samples más usados, samples nunca usados.

### 1.B — Análisis espectral en indexado

- [ ] **T016** — `vector_manager.py → _build_index()`: agregar llamada a `AudioAnalyzer.analyze()` para cada sample
  - Extraer y guardar en `.sample_embeddings.json`: `key`, `key_confidence`, `spectral_centroid`, `is_harmonic`.
  - Flag `--skip-audio-analysis` para rebuild rápido en desarrollo.

- [ ] **T017** — `sample_selector.py → _calculate_sample_score()`: agregar factor `brightness_fit` (peso 0.10)
  - `atmos`, `pad`, `drone`: penalizar `spectral_centroid > 8000 Hz`.
  - `bass`, `sub_bass`: penalizar `spectral_centroid > 3000 Hz`.
  - `lead`, `chord`: preferir key dentro de ±1 quinta de la key del proyecto.

- [ ] **T018** — Mejorar el embed de texto en `vector_manager.py` para incluir info espectral
  - Formato: `"kick 808 drums bright=low harmonic=no key=None"`

- [ ] **T019** — Validar que `audio_analyzer.py` con `librosa` detecta key en ≥70% de samples
  - Script de prueba: analizar 50 archivos aleatorios y reportar `key`, `confidence`.

- [ ] **T020** — Agregar campo `is_tonal` al metadata del índice
  - `True` para: chords, pad, lead, bass, pluck, arp, drone.
  - `False` para: kick, snare, hat, crash, fill.

### 1.C — Sistema de fatiga persistente

- [ ] **T021** — Crear `sample_fatigue.json` en `~/.abletonmcp_ai/`
  - Estructura: `{path: {role: {uses: int, last_used: timestamp}}}`
  - Reemplaza gradualmente `_recent_sample_diversity_memory`.

- [ ] **T022** — Factor de fatiga continuo (vs. binario actual)
  - 0 usos: sin penalización → `fatigue_factor = 1.0`
  - 1-3 usos: `fatigue_factor = 0.75`
  - 4-10 usos: `fatigue_factor = 0.50`
  - 10+ usos: `fatigue_factor = 0.20` (casi bloqueado)

- [ ] **T023** — Herramienta MCP `reset_sample_fatigue(role=None)`
  - Sin `role`: resetear toda la fatiga. Con `role`: resetear solo ese rol.

- [ ] **T024** — Herramienta MCP `get_sample_fatigue_report()`
  - Top-10 samples más usados por rol con conteos y timestamps.

---

## FASE 2 — Coherencia Musical & Sistema de Paleta 🔴 PRIORIDAD MÁXIMA

> **Goal**: Cada canción tiene una "identidad sonora" coherente. Drums, bass y music suenan como si vinieran de la misma sesión.

### 2.A — Palette Lock

- [ ] **T025** — Selección de "folder ancla" por bus al inicio de cada generación
  - Elegir aleatoriamente de las carpetas **menos usadas** (via Coverage Wheel).
  - Mapear: `drums_anchor`, `bass_anchor`, `music_anchor` (FX libre).

- [ ] **T026** — `sample_selector.py → _calculate_sample_score()`: agregar factor `palette_bonus`
  - Folder ancla: `score *= 1.4` | Folder compatible: `score *= 1.2` | Diferente: `score *= 0.9`

- [ ] **T027** — Guardar la palette en el manifest de generación
  - Formato: `{"palette": {"drums": "Splice/Techno/Kit_A", "bass": "SM/TechHouse/Bass"}}`

- [ ] **T028** — Herramienta `set_palette_lock(drums, bass, music)` para override manual

### 2.B — Coverage Wheel

- [ ] **T029** — Crear `collection_coverage.json` en `~/.abletonmcp_ai/`
  - Estructura: `{folder_path: {uses: int, last_used: timestamp}}`

- [ ] **T030** — Al terminar cada generación: actualizar Coverage Wheel con carpetas usadas

- [ ] **T031** — Lógica de selección de ancla: weighted random sampling por frescura
  - `freshness = max(0, 10 - uses_last_10_gens)` → elegir ancla con mayor freshness.

- [ ] **T032** — Herramienta MCP `get_coverage_wheel_report()` → heatmap de uso por carpeta

### 2.C — Wild Card Injection

- [ ] **T033** — Seleccionar 2-3 roles "wild card" por generación
  - Para wild cards: solo 2 filtros duros (rol correcto + duración válida), sin penalización.

- [ ] **T034** — `select_sample_wildcard(role, seed)` en `SampleSelector`
  - Log: `"Wild card selected: {path} for role {role}"`

### 2.D — Section Casting

- [ ] **T035** — Definir `ROLE_SECTION_VARIANTS` en `song_generator.py`
  ```python
  ROLE_SECTION_VARIANTS = {
    'top_loop':   {'intro': 'minimal filtered subtle', 'drop': 'full punchy driving', 'break': 'sparse reversed'},
    'atmos':      {'intro': 'atmospheric wide', 'drop': 'driving textured', 'break': 'deep long ambient'},
    'pad':        {'intro': 'soft subtle', 'drop': 'full wide powerful', 'break': 'evolving textured'},
    'vocal_chop': {'intro': 'minimal', 'drop': 'aggressive chopped', 'break': 'reversed distant'},
  }
  ```

- [ ] **T036** — `server.py → _find_library_file()`: pasar `section` como modificador del query
  - `query_modified = f"{base_query} {ROLE_SECTION_VARIANTS[role][section]}"`

- [ ] **T037** — Seleccionar samples distintos por sección para roles con variantes

### 2.E — Fingerprint tonal de la canción

- [ ] **T038** — Al seleccionar el primer sample armónico: extraer fingerprint
  - `fingerprint = {key, spectral_centroid, is_major, brightness_category}` → guardar en contexto de generación.

- [ ] **T039** — Penalización de fingerprint mismatch para samples armónicos subsiguientes
  - Key a más de 2 quintas: `score *= 0.6` | Brightness muy diferente (>3000 Hz): `score *= 0.8`

---

## FASE 3 — Human Feel & Dinámicas 🟠 PRIORIDAD ALTA

> **Goal**: La música respira. Hay tensión-release, fades naturales, groove humano.

- [ ] **T040** — `Remote_Script.py`: agregar comando `write_clip_envelope`
  - Parámetros: `track_index`, `clip_index`, `points: List[(time_beats, value)]`

- [ ] **T041** — Herramienta `apply_clip_fades(track_index, section, fade_in_bars, fade_out_bars)`
  - Intro: fade-in 4-8 bars en kick, bass, top loops.
  - Outro: fade-out simétrico. Break: fade-down al inicio + fade-up antes del drop.

- [ ] **T042** — Herramienta `write_volume_automation(track_index, curve_type, section_map)`
  - Curves: `linear`, `exponential`, `s_curve`, `punch`.
  - Build: curva exponencial 0.5 → 0.85 en bus de music.

- [ ] **T043** — Implementar curvas de volumen por sección en `song_generator.py`
  - Intro: music al 60% → building → 100% en drop. Break: drums 30%, music+atmos 70%.

- [ ] **T044** — Herramienta `inject_dynamic_variation(track_index, role)`
  - Ghost notes MIDI: velocidad 20-40. Downbeats: 90-110. Upbeats: 60-80.
  - Para audio clips: micro-automatizaciones de ±3dB en forma de LFO lento.

- [ ] **T045** — Herramienta `apply_sidechain_pump(intensity, style)`
  - `'subtle'`: pump mínimo solo en drop.
  - `'jackin'`: pump pronunciado cada beat (tech house clásico).
  - `'breathing'`: pump lento cada 2 beats.

- [ ] **T046** — Variación de velocidad MIDI por sección
  - Intro: velocidades −15%. Drop: plenas + ghost notes.

- [ ] **T047** — Herramienta `apply_loop_variation(role, sections_map)`
  - Intro: top loop filtrado/suave. Drop: agresivo/abierto. Break: swing alto.

- [ ] **T048** — Herramienta `inject_pattern_fills(track_index, fill_density, section)`
  - Snare rolls, flams, tom fills, hi-hat busteos.
  - Densidad: `'sparse'` (1 cada 8 bars), `'medium'`, `'heavy'` (cada 2 bars).

- [ ] **T049** — Herramienta `apply_swing_to_clip(track_index, clip_index, swing_percent)`
  - Por sección: intro 8%, drop 14%, break 18%.

- [ ] **T050** — Herramienta paraguas `humanize_set(intensity)` (0.3 / 0.6 / 1.0)

---

## FASE 4 — Soundscape & Tonal 🟠 PRIORIDAD ALTA

> **Goal**: Identidad harmónica y espectral definida. No hay samples que "rompen" el ambiente.

- [ ] **T051** — Análisis masivo de key con Krumhansl-Schmuckler durante el indexado
- [ ] **T052** — `KEY_COMPATIBILITY_MATRIX` con scores 0-1 para cada par de keys
- [ ] **T053** — Integrar `KEY_COMPATIBILITY_MATRIX` en `_calculate_sample_score()` (factor 0.25)
- [ ] **T054** — Detección de `project_key` al iniciar generación (manual o inferida)
- [ ] **T055** — Rechazar samples con `key_compatibility < 0.40` para roles críticos (chords, lead, pad)
- [ ] **T056** — Definir `BRIGHTNESS_RANGES` óptimas por rol (sub_bass, bass, kick, pad, lead, atmos…)
- [ ] **T057** — Factor `spectral_fit` en `_calculate_sample_score()` (peso 0.10)
- [ ] **T058** — Paneo espectral inteligente por sección (dinámico según `AUDIO_LAYER_MIX_PROFILES`)
- [ ] **T059** — Filtros de frecuencia automáticos por sección (high-pass en intro, high-cut en break)
- [ ] **T060** — Brightness embedding de 8 bandas por sample en el índice
- [ ] **T061** — Tags automáticos de color espectral: `dark`, `neutral`, `bright`, `warm`, `harsh`
- [ ] **T062** — Herramienta `analyze_mix_spectrum()` → análisis del master en tiempo real

---

## FASE 5 — Arranjo y Estructura DJ Profesional 🟡 PRIORIDAD P3

> **Goal**: Estructura DJ real: intro largo para mezclar, drops definidos, breaks tensos, outro largo.

- [ ] **T063** — Definir `DJ_ARRANGEMENT_TEMPLATES` por subgénero (tech_house, deep_house, techno_minimal)
  ```python
  'tech_house': {
    'intro':   {'bars': 16, 'elements': ['kick','bass','hat'], 'energy': 0.4},
    'build_1': {'bars': 8,  'elements': ['+perc','+top_loop'], 'energy': 0.6},
    'drop_1':  {'bars': 16, 'elements': ['full'], 'energy': 1.0},
    'break':   {'bars': 8,  'elements': ['-kick','+atmos','filter_bass'], 'energy': 0.5},
    'drop_2':  {'bars': 16, 'elements': ['full','+vocal_peak'], 'energy': 1.0},
    'outro':   {'bars': 16, 'elements': ['-vocal','-music'], 'energy': 0.4},
  }
  ```

- [ ] **T064** — `generate_arrangement(template, length_bars)` → genera toda la sesión en Arrangement view
- [ ] **T065** — Intro DJ-compatible de mínimo 16 bars (solo kick + bass + hat)
- [ ] **T066** — Outro DJ-compatible de mínimo 16 bars (misma lógica inversa)
- [ ] **T067** — Loop markers automáticos en puntos clave (drop marcado como loop 16 bars)
- [ ] **T068** — Variación de pattern de kick por sección (ghost notes en build, reverse en break)
- [ ] **T069** — Hi-hat evolution: de closed a open gradualmente por sección
- [ ] **T070** — Bassline evolution: de root-note en intro a melodic walk en drop_2
- [ ] **T071** — Herramienta `inject_transition_fx(type, position_bar)` (riser / crash / snare_roll)
- [ ] **T072** — Filter sweep automation en transiciones (high-pass sube 8 bars antes del drop)
- [ ] **T073** — Reverb tail automation en breaks (reverb 0% → 40% → 0%)
- [ ] **T074** — Pitch automation: riser en últimos 4 beats del break, snap al drop
- [ ] **T075** — Micro-timing "push" del groove (kick −5ms, bass +8ms) para feel orgánico
- [ ] **T076** — `GROOVE_TEMPLATES` por subgénero: `tech_house_drop`, `tech_house_break`, `deep_house_drop`
- [ ] **T077** — `apply_groove_template(section, template_name)` aplicado automáticamente al arrangement

---

## FASE 6 — Masterización & Lanzamiento 🟡 PRIORIDAD P3

> **Goal**: La canción suena a promo de label internacional, lista para Beatport.

- [ ] **T078** — Validar `ROLE_GAIN_CALIBRATION` prácticamente: kick −8 LUFS, bass −10 LUFS
- [ ] **T079** — Herramienta `calibrate_gain_staging()` → medir LUFS de cada bus y ajustar faders
- [ ] **T080** — Verificar headroom en Master Track (≥ −6 dBFS antes del limitador)
- [ ] **T081** — `BUS DRUMS`: parallel compression calibrada (attack 30ms, release 100ms)
- [ ] **T082** — `BUS BASS`: sub en mono, high-cut automático por encima de 300Hz
- [ ] **T083** — `BUS MUSIC`: glue compressor 2:1 + stereo widener solo en mid-high
- [ ] **T084** — Verificar sends de FX (Space/Echo/Heat/Glue) coherentes con `AUDIO_LAYER_MIX_PROFILES`
- [ ] **T085** — Herramienta `run_mix_quality_check()`: LUFS, peak, RMS, balance L/R, correlation mono
- [ ] **T086** — Flags automáticos de issues críticos (clip, desbalance L/R, kick muy silencioso)
- [ ] **T087** — Herramienta `export_stem_mixdown(stem_config)` → stems 24-bit / 44.1kHz WAV
- [ ] **T088** — Generación automática de metadata Beatport (BPM, key, género desde el manifest)
- [ ] **T089** — A/B testing: generar 3 variantes del mismo drop con diferentes palette locks
- [ ] **T090** — Herramienta `analyze_reference_track(file_path)` → extraer BPM, key, LUFS, spectral balance del track de referencia

---

## FASE 7 — IA Autónoma y Aprendizaje 🔵 FUTURO

> **Goal**: El sistema aprende de las preferencias del usuario y mejora con cada sesión.

- [ ] **T091** — Sistema de rating `rate_generation(session_id, score: 1-5, notes)`
- [ ] **T092** — Feedback loop: samples de sesiones bien puntuadas tienen menor fatiga futura
- [ ] **T093** — Predicción de preferencias de palette por BPM/key (con 20+ generaciones)
- [ ] **T094** — Análisis de tendencias de la librería: identificar carpetas con mala performance histórica
- [ ] **T095** — Modo "Autopilot DJ": 16 tracks concatenados con Palette Lock linked entre sí
- [ ] **T096** — Herramienta `generate_dj_set(duration_hours, style_evolution)` → set de 4 horas completo
- [ ] **T097** — Análisis de referencia de Beatport top-100 Tech House (BPM, keys, spectral profiles)
- [ ] **T098** — Hot zone detection: identificar características comunes de drops con mejor rating
- [ ] **T099** — Medir si el set "mueve" via detección de variación de volumen en Ableton (proxy energía)
- [ ] **T100** — Herramienta `auto_improve_set(feedback_json)` → regenerar secciones con bajo score sin tocar las exitosas

---

## 🛠️ Infraestructura y Soporte

- [ ] **T101** — Tests de regresión para `sample_selector.py` (repetición, palette lock, key match)
- [ ] **T102** — Benchmark de performance del indexado (base: 800 samples < 20 min)
- [ ] **T103** — Hot reload de configuración sin reiniciar el servidor
- [ ] **T104** — `howto.md` actualizado con ejemplos JSON-RPC explícitos por herramienta
- [ ] **T105** — CI automático en Gitea con webhooks + badge de status
- [ ] **T106** — `CHANGELOG.md` con versiones del sistema
- [ ] **T107** — Backup diario de `~/.abletonmcp_ai/` (sample_history, fatigue, coverage)
- [ ] **T108** — Dashboard de métricas: `get_system_metrics()` → generaciones totales, cobertura %, promedio estrellas
- [ ] **T109** — Soporte para Deep House, Minimal Techno, Afro House en `STYLE_CONFIGS`
- [ ] **T110** — Script `import_sample_pack(folder, genre_tag, collection_name)` → indexa + actualiza Coverage Wheel

---

## 📊 Métricas de éxito por Fase

| Fase | KPI | Target |
|------|-----|--------|
| 1 | % samples únicos en 20 generaciones | > 85% |
| 1 | % samples con key detectada | > 60% |
| 2 | Coherencia de palette (% samples del folder ancla) | > 65% |
| 2 | Coverage de librería en 20 generaciones | > 80% carpetas usadas |
| 3 | Diferencia de energía drop vs break | > 6 dB LUFS |
| 4 | Key mismatch rate en samples armónicos | < 10% |
| 5 | Intro/Outro duration DJ-compatible | ≥ 16 bars |
| 6 | LUFS integrado del master | −10 a −8 LUFS |
| 6 | Headroom en master | ≥ 0.3 dBTP |

---

## 🚀 Orden de implementación recomendado

| Sprint | Tareas | Objetivo |
|--------|--------|----------|
| **1** (inmediato) | T011 → T015 | Fix de repetición de samples |
| **2** | T025 → T032 | Palette Lock + Coverage Wheel |
| **3** | T040 → T050 | Human Feel básico |
| **4** | T016 → T020, T051 → T055 | Tonal intelligence |
| **5** | T063 → T072 | Estructura DJ |
| **6** | T078 → T087 | Gain staging + export |

---

*Documento vivo — actualizar con cada sprint completado.*