ableton-mcp-ai/AbletonMCP_AI/PRO_DJ_ROADMAP.md

🎛️ 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 ✅

• T001 — Migrar proyecto a C:\Users\ren\AbletonMCP_AI con junction a ProgramData
• T002 — Crear start_server.bat con PYTHONPATH correcto
• T003 — Sincronizar opencode.json y .opencode.json apuntando a ruta nueva
• T004 — Verificar que server.py arranca sin errores en log
• T005 — Confirmar que SampleManager carga la librería completa en librerias\all_tracks
• T006 — Confirmar conexión MCP activa y visible en cliente AI
• T007 — Resolver permisos NTFS en ProgramData para edición directa
• T008 — Configurar logging a nivel INFO en producción
• T009 — Integrar estructura de errores: MCPError, ValidationError, TimeoutError
• 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

  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)

  '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.