# SPRINT 3 - SISTEMA DE PRODUCCIÓN MUSICAL COMPLETO

> **Date**: 2026-04-11
> **Assigned**: Kimi K2
> **Reviewed by**: Qwen
> **Sprint 1 Status**: ✅ COMPLETO - 511 samples indexados, 8 tools de análisis
> **Sprint 2 Status**: ✅ COMPLETO - 62 MCP tools, song generator, mixing, workflow

---

## ESTADO ACTUAL DEL SISTEMA

**Lo que YA funciona:**
- ✅ 62 herramientas MCP (info, transporte, tracks, clips, samples, análisis, mezcla, workflow)
- ✅ 511 samples indexados con BPM, Key, MFCCs, embeddings
- ✅ Song generator: genera configs de 64-96 bars con dembow, bass, chords, melody
- ✅ Pattern library: dembow, bass, chords, melody, percussion, human feel
- ✅ Mixing engine: buses, EQ, compressor, sidechain, master chain
- ✅ Workflow engine: generación completa, referencias, validación, export
- ✅ numpy + librosa + scipy + scikit-learn instalados

**Lo que FALTA para producir reggaeton profesional real:**
- ❌ Los samples NO se cargan realmente en Ableton (solo se genera config)
- ❌ Las notas MIDI NO se escriben en clips reales
- ❌ Los devices NO se insertan realmente en tracks
- ❌ La mezcla NO se aplica realmente en Ableton
- ❌ No hay automatización real en Arrangement View
- ❌ No hay resampleo ni renderizado
- ❌ No hay integración completa entre engines → Ableton runtime

---

## FASE 1: PUENTE ENGINES → ABLETON (T001-T020) - CRÍTICA

El problema principal: los engines generan configs pero NADA se materializa en Ableton.

### T001-T005: Runtime - Crear clips MIDI reales

**T001** - En `AbletonMCP_AI/__init__.py`, agregar handler `_cmd_generate_midi_clip`:
- Recibe track_index, clip_index, notes (lista de dicts con pitch, start_time, duration, velocity)
- Crea clip MIDI en Session View
- Escribe las notas con `clip.set_notes()`
- Retorna: `{created: true, note_count: N}`

**T002** - Agregar handler `_cmd_generate_dembow_clip`:
- Usa `pattern_library.DembowPatterns` para generar notas de dembow
- Crea clip MIDI con kick, snare, hihat patterns
- Parámetros: track_index, clip_index, bars, variation, swing

**T003** - Agregar handler `_cmd_generate_bass_clip`:
- Usa `pattern_library.BassPatterns`
- Crea clip MIDI con línea de bass
- Parámetros: track_index, clip_index, bars, root_notes, style

**T004** - Agregar handler `_cmd_generate_chords_clip`:
- Usa `pattern_library.ChordProgressions`
- Crea clip MIDI con acordes
- Parámetros: track_index, clip_index, bars, progression, voicing

**T005** - Agregar handler `_cmd_generate_melody_clip`:
- Usa `pattern_library.MelodyGenerator`
- Crea clip MIDI con melodía
- Parámetros: track_index, clip_index, bars, scale, density

### T006-T010: Runtime - Cargar samples reales

**T006** - Fix `_cmd_load_sample_to_clip` - actualmente stub, debe:
- Abrir browser de Ableton
- Navegar a sample_path
- Cargar sample en clip de Session View
- Warpear al BPM del proyecto

**T007** - Fix `_cmd_load_sample_to_drum_rack_pad` - actualmente stub, debe:
- Acceder al Drum Rack en el track
- Cargar sample en el pad correcto (por note number)
- Ajustar envelope si es necesario

**T008** - Agregar handler `_cmd_load_samples_for_genre`:
- Usa `sample_selector.select_for_genre()` para obtener samples
- Crea tracks: Kick, Snare, HiHats, Bass, Synths
- Carga cada sample en su track correspondiente
- Configura nombres y colores

**T009** - Agregar handler `_cmd_create_drum_kit`:
- Crea Drum Rack en track
- Carga kick, snare, clap, hats en pads
- Retorna mapeo MIDI completo

**T010** - Agregar handler `_cmd_build_track_from_samples`:
- Recibe track_type (kick, snare, bass, etc.)
- Busca sample recomendado con `get_recommended_samples()`
- Crea track y carga sample
- Configura volumen y paneo

### T011-T015: Runtime - Generación completa

**T011** - Agregar handler `_cmd_generate_full_song`:
- Usa `workflow_engine.ProductionWorkflow` para generar config
- Para cada track en config:
  - Crea track en Ableton
  - Genera notas MIDI (dembow, bass, chords, melody)
  - Crea clips y escribe notas
  - Carga samples si aplica
- Configura routing de buses
- Aplica mezcla
- Retorna resumen completo

**T012** - Agregar handler `_cmd_generate_track_from_config`:
- Recibe TrackConfig JSON
- Crea track con nombre y tipo correcto
- Genera clips con notas
- Carga devices si hay device_chain

**T013** - Agregar handler `_cmd_generate_section`:
- Recibe Section config
- Genera clips para cada track en esa sección
- Aplica variación según energy_level

**T014** - Agregar handler `_cmd_apply_human_feel_to_track`:
- Usa `pattern_library.HumanFeel`
- Modifica notas existentes en clips del track
- Aplica micro-timing, velocity variation
- Parámetros: track_index, intensity

**T015** - Agregar handler `_cmd_add_percussion_fills`:
- Usa `pattern_library.PercussionLibrary`
- Añade fills en puntos de transición
- Snare rolls, tom fills, FX hits

### T016-T020: Runtime - Mezcla real

**T016** - Fix `_cmd_create_bus_track` - actualmente stub, debe:
- Crear track de grupo
- Configurar output routing correctamente
- Retornar track_index del bus

**T017** - Fix `_cmd_route_track_to_bus` - actualmente stub, debe:
- Cambiar output de track a bus
- Configurar sends si aplica

**T018** - Fix `_cmd_insert_device` - actualmente stub, debe:
- Usar browser API para encontrar device
- Cargar device en cadena del track
- Configurar parámetros iniciales

**T019** - Fix `_cmd_configure_eq` - actualmente stub, debe:
- Insertar EQ Eight si no existe
- Configurar bandas según preset
- Aplicar gains, freqs, Qs

**T020** - Fix `_cmd_setup_sidechain` - actualmente stub, debe:
- Insertar Compressor en target
- Configurar sidechain input desde source
- Ajustar threshold, ratio, attack, release

---

## FASE 2: AUTOMATIZACIÓN Y ARRANGEMENT (T021-T040)

### T021-T025: Crear estructura de canción en Arrangement

**T021** - Agregar handler `_cmd_build_arrangement_structure`:
- Crea secciones en Arrangement View
- Intro → Build → Drop → Break → Drop2 → Outro
- Configura loop markers

**T022** - Agregar handler `_cmd_duplicate_clips_to_arrangement`:
- Copia clips de Session View a Arrangement View
- Posiciona cada clip en su sección
- Configura loops

**T023** - Agregar handler `_cmd_create_arrangement_midi_clip`:
- Crea clip MIDI directamente en Arrangement
- Escribe notas
- Configura loop

**T024** - Agregar handler `_cmd_create_arrangement_audio_clip`:
- Crea clip de audio directamente en Arrangement
- Carga sample
- Configura warp markers

**T025** - Agregar handler `_cmd_fill_arrangement_with_song`:
- Pipeline completo:
  1. Genera config con song_generator
  2. Crea tracks
  3. Genera clips MIDI
  4. Posiciona en Arrangement por secciones
  5. Aplica human feel
  6. Configura buses

### T026-T030: Automatización real

**T026** - Agregar handler `_cmd_automate_filter`:
- Inserta AutoFilter en track
- Crea automatización de cutoff
- Filter sweep de intro a drop

**T027** - Agregar handler `_cmd_automate_reverb`:
- Inserta Hybrid Reverb en track
- Crea automatización de Dry/Wet
- Más reverb en break, menos en drop

**T028** - Agregar handler `_cmd_automate_volume`:
- Crea automatización de volumen
- Fade in/out por sección
- Builds progresivos

**T029** - Agregar handler `_cmd_automate_delay`:
- Inserta Delay en track
- Crea automatización de feedback
- Delay throws en transiciones

**T030** - Agregar handler `_cmd_automate_send`:
- Automatiza send amount a return track
- Más send en break, menos en drop

### T031-T035: Transiciones y FX

**T031** - Agregar handler `_cmd_create_riser`:
- Crea clip de riser en Arrangement
- Automatiza pitch + volume + filter
- Pre-drop tension builder

**T032** - Agregar handler `_cmd_create_downlifter`:
- Crea clip de downlifter
- Automatiza pitch down + reverb
- Post-drop release

**T033** - Agregar handler `_cmd_create_impact`:
- Crea clip de impacto en transición
- Sample de impact FX
- Configura volume envelope

**T034** - Agregar handler `_cmd_create_silence`:
- Crea barra de silencio pre-drop
- Mute momentáneo
- Automatiza unmute en drop

**T035** - Agregar handler `_cmd_create_fx_automation_section`:
- Crea sección completa de FX
- Risers, impacts, silences, sweeps
- Posiciona en Arrangement

### T036-T040: Resampleo y processing

**T036** - Agregar handler `_cmd_resample_track`:
- Graba track a nuevo clip de audio
- Configura record routing
- Retorna nuevo clip path

**T037** - Agregar handler `_cmd_reverse_sample`:
- Carga sample, lo revierte
- Guarda como nuevo archivo
- Crea clip con sample revertido

**T038** - Agregar handler `_cmd_slice_and_rearrange`:
- Detecta transients en loop
- Crea slices
- Rearranja slices en nuevo pattern

**T039** - Agregar handler `_cmd_apply_granular_effect`:
- Aplica efecto granular a clip
- Parameters: grain size, density, spread
- Crea texturas atmosféricas

**T040** - Agregar handler `_cmd_create_ambient_layer`:
- Crea track de ambient/pad
- Genera notas largas con chords
- Aplica reverb heavy + delay

---

## FASE 3: INTELIGENCIA MUSICAL AVANZADA (T041-T060)

### T041-T045: Análisis y adaptación

**T041** - Agregar handler `_cmd_analyze_project_key`:
- Analiza todas las notas MIDI del proyecto
- Detecta key predominante
- Sugiere correcciones si hay conflicto

**T042** - Agregar handler `_cmd_harmonize_track`:
- Analiza progresión de acordes
- Genera notas armonizadas para track
- 3rds, 5ths, 7ths sobre progresión

**T043** - Agregar handler `_cmd_generate_counter_melody`:
- Usa `MelodyGenerator.generate_counter_melody()`
- Crea track de contra-melodía
- Complementa melodía principal

**T044** - Agregar handler `_cmd_detect_energy_curve`:
- Analiza energía por sección
- Grafica: intro→build→drop→break
- Sugiere ajustes si no hay contraste

**T045** - Agregar handler `_cmd_balance_sections`:
- Ajusta energía de secciones para mejor flujo
- Intro: 30%, Build: 60%, Drop: 100%, Break: 40%
- Modifica velocity, density, instrumentation

### T046-T050: Variación inteligente

**T046** - Agregar handler `_cmd_variate_loop`:
- Toma loop existente
- Genera variación (no idéntico)
- Mantiene groove pero cambia notas

**T047** - Agregar handler `_cmd_add_call_and_response`:
- Analiza frase existente
- Genera respuesta complementaria
- Call: 2 bars, Response: 2 bars

**T048** - Agregar handler `_cmd_generate_breakdown`:
- Crea sección de breakdown
- Strip down a elementos mínimos
- Build up progresivo

**T049** - Agregar handler `_cmd_generate_drop_variation`:
- Crea variación de drop
- Mismo groove, diferente instrumentation
- Drop A vs Drop B

**T050** - Agregar handler `_cmd_create_outro`:
- Genera outro basado en intro
- Fade out progresivo
- Elimina elementos gradualmente

### T051-T055: Samples inteligentes

**T051** - Agregar handler `_cmd_find_and_replace_sample`:
- Analiza sample actual en track
- Busca alternativa similar en librería
- Reemplaza manteniendo groove

**T052** - Agregar handler `_cmd_layer_samples`:
- Carga 2+ samples en mismo track
- Layer kick + sub, snare + clap
- Configura volumes y EQ para cada capa

**T053** - Agregar handler `_cmd_create_sample_chain`:
- Encadena samples secuencialmente
- Sample 1 → Sample 2 → Sample 3
- Crea evolución sonora

**T054** - Agregar handler `_cmd_generate_from_sample`:
- Analiza sample (BPM, key, timbre)
- Genera canción completa basada en ese sample
- Todo coherente con el sample

**T055** - Agregar handler `_cmd_create_vocal_chops`:
- Carga sample vocal
- Detecta syllables/transients
- Crea slices mapeadas a Drum Rack
- Genera pattern con chops

### T056-T060: Referencia y comparación

**T056** - Agregar handler `_cmd_match_reference_energy`:
- Analiza energía de referencia
- Ajusta mezcla para match
- EQ, compression, limiting

**T057** - Agregar handler `_cmd_match_reference_spectrum`:
- Analiza espectro de referencia
- Ajusta EQ para match tonal
- Balance frequency similar

**T058** - Agregar handler `_cmd_match_reference_width`:
- Analiza stereo width de referencia
- Ajusta imágenes stereo
- Width por frecuencia

**T059** - Agregar handler `_cmd_generate_similarity_report`:
- Compara proyecto vs referencia
- Score por dimensión: BPM, key, energy, spectrum, width
- Sugiere cambios

**T060** - Agregar handler `_cmd_adapt_to_reference_style`:
- Analiza estilo de referencia
- Adapta song structure
- Ajusta instrumentation

---

## FASE 4: WORKFLOW Y PRODUCCIÓN (T061-T080)

### T061-T065: Presets y templates

**T061** - Crear sistema de presets de canción:
- "reggaeton_classic_95bpm"
- "perreo_intenso_100bpm"
- "reggaeton_romantico_90bpm"
- "moombahton_108bpm"
- Cada preset: BPM, key, structure, samples, mixing

**T062** - Agregar handler `_cmd_load_preset`:
- Carga preset completo
- Crea tracks, samples, mixing
- Ready para personalizar

**T063** - Agregar handler `_cmd_save_as_preset`:
- Guarda configuración actual como preset
- Incluye samples, mixing, structure
- Reutilizable

**T064** - Agregar handler `_cmd_list_presets`:
- Lista presets disponibles
- Muestra detalles de cada uno

**T065** - Agregar handler `_cmd_create_custom_preset`:
- Crea preset desde configuración actual
- Nombre personalizado
- Guarda en directorio de presets

### T066-T070: Export y delivery

**T066** - Agregar handler `_cmd_render_stems`:
- Renderiza cada bus como stem separado
- Drums stem, Bass stem, Music stem, FX stem
- Guarda en directorio

**T067** - Agregar handler `_cmd_render_full_mix`:
- Renderiza mezcla completa
- WAV 24-bit/44.1kHz
- Con mastering aplicado

**T068** - Agregar handler `_cmd_render_instrumental`:
- Mutea elementos vocales/melodía
- Renderiza instrumental
- Para DJs o remixes

**T069** - Agregar handler `_cmd_render_acapella`:
- Mutea drums/bass
- Renderiza solo elementos melódicos
- Para mashups

**T070** - Agregar handler `_cmd_export_stems_and_mix`:
- Pipeline completo:
  1. Renderiza stems
  2. Renderiza full mix
  3. Renderiza instrumental
  4. Genera reporte de loudness
  5. Guarda todo en carpeta

### T071-T075: Calidad y validación

**T071** - Agregar handler `_cmd_full_quality_check`:
- Analiza todo el proyecto
- Clipping, phase, frequency balance
- Coherencia armónica
- Energía por sección
- Repetición excesiva
- Retorna score 0-100

**T072** - Agregar handler `_cmd_fix_quality_issues`:
- Toma reporte de quality check
- Aplica correcciones automáticamente
- EQ, compression, stereo, levels

**T073** - Agregar handler `_cmd_check_arrangement_coherence`:
- Verifica que arreglo tenga sentido
- Intro→Build→Drop→Break→Outro
- Transiciones suaves
- Energía apropiada

**T074** - Agregar handler `_cmd_check_sample_compatibility`:
- Verifica que todos los samples existen
- Samples en key correcta
- BPM compatible
- Sin conflicts de fase

**T075** - Agregar handler `_cmd_generate_release_notes`:
- Genera notas de release
- BPM, key, structure
- Samples usados
- Mixing notes
- Loudness stats

### T076-T080: Productividad

**T076** - Agregar handler `_cmd_duplicate_project`:
- Duplica proyecto actual
- Renombra tracks
- Ready para variación

**T077** - Agregar handler `_cmd_create_remix_version`:
- Toma proyecto existente
- Cambia estilo/structure
- Mantiene elementos core
- Nueva versión

**T078** - Agregar handler `_cmd_create_radio_edit`:
- Versión acortada (3:00)
- Intro más corta
- Outro fade
- Optimizada para radio

**T079** - Agregar handler `_cmd_create_dj_edit`:
- Versión extendida para DJs
- Intro con drums solo (16 bars)
- Outro con drums solo (16 bars)
- Clean transitions

**T080** - Agregar handler `_cmd_create_instrumental_version`:
- Mutea melodías/vocals
- Mantiene drums + bass
- Versión instrumental completa

---

## FASE 5: INTEGRACIÓN FINAL (T081-T100)

### T081-T085: Pipeline completo de un comando

**T081** - Agregar MCP tool `produce_reggaeton(bpm, key, style)`:
- UN comando que hace TODO:
  1. Analiza librería (si no cacheada)
  2. Genera config con song_generator
  3. Crea tracks en Ableton
  4. Carga samples reales
  5. Genera notas MIDI
  6. Crea clips en Session View
  7. Configura buses y routing
  8. Aplica mezcla
  9. Configura sidechain
  10. Retorna resumen completo

**T082** - Agregar MCP tool `produce_from_reference(audio_path)`:
- Analiza referencia
- Genera canción similar
- Pipeline completo como T081

**T083** - Agregar MCP tool `produce_arrangement(bpm, key, style)`:
- Como T081 pero en Arrangement View
- Clips posicionados en tiempo
- Automatización incluida

**T084** - Agregar MCP tool `complete_production(bpm, key, style, output_dir)`:
- Pipeline T081 + renderizado
- Exporta stems + full mix
- Genera release notes
- Retorna paths de archivos

**T085** - Agregar MCP tool `batch_produce(count, style, bpm_range, key_range)`:
- Genera múltiples canciones
- Variación automática
- Cada una única
- Para álbumes o EPs

### T086-T090: Features avanzadas

**T086** - Soporte para múltiples progresiones armónicas en una canción
**T087** - Modulación de key entre secciones
**T088** - Polyrhythms y tiempo compuesto
**T089** - Generación de lyrics/vocal melodies (estructura, no audio)
**T090** - Integración con hardware (MIDI controllers, APC40)

### T091-T095: Optimización y performance

**T091** - Caché inteligente: solo re-analiza samples nuevos
**T092** - Procesamiento paralelo para análisis de librería
**T093** - Lazy loading de engines (solo cuando se necesitan)
**T094** - Optimización de memoria (511 samples con embeddings = ~500MB)
**T095** - Progress reporting detallado para operaciones largas

### T096-T100: Documentación y UX

**T096** - Agregar `help()` tool - retorna lista de todas las tools con descripción
**T097** - Agregar `get_workflow_status()` - retorna estado actual del proyecto
**T098** - Agregar `undo()` / `redo()` - sistema de undo/redo
**T099** - Agregar `save_checkpoint()` - guarda estado para recovery
**T100** - Agregar `get_production_report()` - reporte completo de producción

---

## PRIORIDAD DE EJECUCIÓN

### Bloque 1 (CRÍTICO - sin esto no hay producción real):
**T001-T020**: Puente Engines → Ableton
Esto es LO MÁS IMPORTANTE. Sin esto, todo lo demás es teórico.

### Bloque 2 (Alta - sin esto no hay canción completa):
**T021-T040**: Arrangement y automatización

### Bloque 3 (Media - calidad profesional):
**T041-T060**: Inteligencia musical avanzada

### Bloque 4 (Media - workflow):
**T061-T080**: Presets, export, validación

### Bloque 5 (Baja - integración final):
**T081-T100**: Pipeline de un comando, features avanzadas

---

## RESTRICCIONES

1. **NO tocar `libreria/`** - solo lectura
2. **Compilar después de cada archivo**: `python -m py_compile "<path>"`
3. **Cada MCP tool retorna JSON válido** con status + result/error
4. **Mantener compatibilidad** con 62 tools existentes
5. **Usar engines del Sprint 1 y 2** - no reimplementar
6. **Paths absolutos de Windows** en todo

---

## ARCHIVOS A MODIFICAR/CREAR

### Modificar:
- `AbletonMCP_AI/__init__.py` - Agregar 60+ handlers nuevos
- `mcp_server/server.py` - Agregar 40+ nuevas tools MCP
- `mcp_server/engines/__init__.py` - Agregar exports nuevos

### Crear:
- `mcp_server/engines/harmony_engine.py` - T041-T050 (inteligencia armónica)
- `mcp_server/engines/arrangement_engine.py` - T021-T040 (arrangement y automation)
- `mcp_server/engines/preset_system.py` - T061-T065 (presets y templates)

---

**Cuando termines, avisale a Qwen.**
Él va a: compilar, probar, arreglar bugs, verificar end-to-end, y crear el Sprint 4.

**Este sprint transforma el sistema de "genera configs" a "produce canciones reales en Ableton".**