ableton-mcp-ai/docs/sprint_2_100_tareas_calidad_profesional.md

# MEGA SPRINT 2 - Producción Profesional de Reggaeton

> **Date**: 2026-04-11
> **Assigned**: Kimi K2
> **Reviewed by**: Qwen
> **Sprint 1 Status**: ✅ COMPLETO - 511 samples indexados, 8 nuevas MCP tools integradas
> **Dependencies instaladas**: numpy, librosa, scipy, scikit-learn, soundfile

---

## QUÉ YA FUNCIONA (NO TOCAR)

- ✅ MCP server con 30+ herramientas
- ✅ Remote script en Ableton (puerto 9877)
- ✅ Library analysis (511 samples indexados)
- ✅ `analyze_library`, `get_library_stats`, `browse_library`
- ✅ `get_similar_samples`, `find_samples_like_audio`
- ✅ `get_user_sound_profile`, `get_recommended_samples`, `compare_two_samples`
- ✅ `select_samples_for_genre`
- ✅ OpenCode configurado
- ✅ libreria/reggaeton/ con 511 samples

---

## FASE 1: SONG GENERATOR PROFESIONAL (CRÍTICO)

El song_generator.py actual es un stub de ~120 líneas. Necesita ser reescrito completamente
para generar reggaeton profesional.

### T001-T010: Motor de generación musical

**T001** - Reescribir `engines/song_generator.py` completo (~2000+ líneas)

**T002** - Clase `ReggaetonGenerator` con estos métodos:
```python
class ReggaetonGenerator:
    def generate(self, bpm=95, key="Am", style="dembow", structure="standard") -> SongConfig
    def _generate_dembow_pattern(self, bars=16) -> List[Note]
    def _generate_bass_pattern(self, bars=16, root_notes=None) -> List[Note]
    def _generate_chord_progression(self, bars=16, progression=None) -> List[Note]
    def _generate_melody(self, bars=16, scale=None) -> List[Note]
    def _generate_hi_hat_pattern(self, bars=16, style="8th") -> List[Note]
    def _generate_percussion(self, bars=16) -> List[Note]
    def _generate_fx_fills(self, bars=16) -> List[Note]
```

**T003** - Soporte de estructuras configurables:
- `minimal`: intro(8) → groove(16) → break(8) → outro(8) = 40 bars
- `standard`: intro(8) → build(8) → drop(16) → break(8) → drop2(16) → outro(8) = 64 bars
- `extended`: intro(16) → build(8) → drop(16) → break(8) → build2(8) → drop2(16) → peak(8) → outro(16) = 96 bars

**T004** - Patrones de dembow REALISTAS:
```
Kick:  | X . . X . . X . | X . . X . . X . |  (1, 1.5, 2, 3, 4)
Snare: | . . . . X . . . | . . . . X . . . |  (en 3)
```

**T005** - Patrones de hi-hat con swing:
- 8th notes con shuffle 55-65%
- 16th notes con variación de velocity
- Open hat en off-beats

**T006** - Patrones de bass:
- Sub bass en root notes de la progresión
- Slides entre notas
- Variación rítmica por sección

**T007** - Progresiones de acordes reggaeton:
- vi-IV-I-V (Am-F-C-G)
- i-VI-VII (Am-F-G)
- i-iv-VII-VI (Am-Dm-G-F)
- Soporte para 7ths, sus chords

**T008** - Melodías generadas con escala detectada:
- Usar la key del proyecto
- Patrones pentatonic/blues para reggaeton
- Variación por sección

**T009** - Human feel:
- Micro-timing variation: ±15ms por nota
- Velocity variation: ±10 por nota
- Note length variation: ±5%

**T010** - Integrar con sample library:
- Usar `get_recommended_samples()` para seleccionar samples reales
- Seleccionar kick, snare, hat, bass por rol
- Variar samples entre secciones (no repetir el mismo)

---

## FASE 2: AUDIO CLIPS REALES (CRÍTICO)

Sin audio clips reales no hay sonido. Esta fase es P0.

### T011-T020: Runtime para audio

**T011** - En `AbletonMCP_AI/__init__.py`, agregar handler `_cmd_load_sample_to_clip`:
- Recibe `track_index`, `clip_index`, `sample_path`
- Carga el sample .wav en el clip de Session View
- Warpea al BPM del proyecto automáticamente

**T012** - Agregar handler `_cmd_load_sample_to_drum_rack_pad`:
- Recibe `track_index`, `pad_note`, `sample_path`
- Carga sample en el pad específico del Drum Rack
- Ajusta start/end points si es necesario

**T013** - Agregar handler `_cmd_create_arrangement_audio_clip`:
- Recibe `track_index`, `sample_path`, `start_time`, `length`
- Crea clip de audio en Arrangement View
- Warp al BPM del proyecto

**T014** - Agregar handler `_cmd_duplicate_session_to_arrangement`:
- Graba clips de Session View a Arrangement View
- Configura loop recording

**T015** - Agregar handler `_cmd_set_warp_markers`:
- Configura warp markers para samples
- Soporte para warp modes: beats, texture, tone, complex

**T016** - Agregar handler `_cmd_reverse_clip`:
- Revierte un clip de audio

**T017** - Agregar handler `_cmd_pitch_shift_clip`:
- Cambia pitch de un clip sin cambiar tempo

**T018** - Agregar handler `_cmd_time_stretch_clip`:
- Cambia tempo de un clip sin cambiar pitch

**T019** - Agregar handler `_cmd_slice_clip`:
- Detecta transients y crea slices del loop
- Asigna slices a Drum Rack pads

**T020** - Test: cargar sample real de libreria → debe sonar en Ableton

---

## FASE 3: MEZCLA Y ROUTING

### T021-T035: Sistema de mezcla

**T021** - En runtime, agregar handler `_cmd_create_bus_track`:
- Crea track de grupo (DRUMS, BASS, MUSIC, FX, VOCALS)
- Configura output routing

**T022** - Agregar handler `_cmd_route_track_to_bus`:
- Routea track individual a bus
- Configura sends a returns

**T023** - Agregar handler `_cmd_create_return_track`:
- Crea return track con efecto específico
- Soporte para: Reverb, Delay, Chorus, Phaser

**T024** - Agregar handler `_cmd_set_track_send`:
- Configura send de track a return
- Set amount (0.0-1.0)

**T025** - Agregar handler `_cmd_insert_device`:
- Inserta device en cadena de track
- Soporte para: EQ Eight, Compressor, Saturator, Utility, Glue Compressor

**T026** - Agregar handler `_cmd_configure_eq`:
- Configura EQ Eight en track
- High-pass, low-shelf, peaking, notch

**T027** - Agregar handler `_cmd_configure_compressor`:
- Configura Compressor en track
- Threshold, ratio, attack, release, makeup gain

**T028** - Agregar handler `_cmd_setup_sidechain`:
- Configura sidechain compression
- Bass sidechaineado al kick
- Synths sidechained al kick

**T029** - Agregar handler `_cmd_auto_gain_staging`:
- Ajusta volumen de todos los tracks para headroom -6dB
- Kick como referencia (0dB)
- Bass -1dB, synths -4dB, FX -8dB

**T030** - Agregar handler `_cmd_apply_master_chain`:
- Configura cadena de mastering en master track:
  EQ → Glue Compressor → Saturator → Limiter
- Presets: "reggaeton club", "reggaeton streaming", "reggaeton radio"

**T031** - Agregar handler `_cmd_set_device_parameter`:
- Set ANY device parameter by name
- track_index, device_name, param_name, value

**T032** - Agregar handler `_cmd_get_device_parameters`:
- Get all parameters of a device

**T033** - Presets de mezcla por género:
- Reggaeton clásico: kick loud, bass prominent, synths mid
- Perreo: kick + bass dominate, minimal synths
- Romántico: balanced, vocal forward, reverb heavy

**T034** - `run_mix_quality_check()`:
- Analiza todos los tracks
- Reporta: clipping, phase issues, frequency masking, stereo imbalance
- Sugiere correcciones

**T035** - `calibrate_for_streaming()`:
- Ajusta mezcla para -14 LUFS (Spotify)
- True peak < -1dB
- Dynamic range appropriado

---

## FASE 4: WORKFLOW COMPLETO

### T036-T050: Un comando para generar todo

**T036** - MCP tool `generate_complete_reggaeton(bpm, key, style, structure, use_samples=True)`:
1. Analiza librería (si no está cacheada)
2. Selecciona samples por similitud al estilo
3. Crea tracks: Kick, Snare, HiHats, Bass, Chords, Melody, FX
4. Carga samples reales en cada track
5. Configura routing de buses
6. Aplica mezcla automática
7. Configura sidechain
8. Retorna resumen completo

**T037** - `generate_from_reference(reference_audio_path)`:
1. Analiza el audio de referencia
2. Encuentra samples similares en la librería
3. Genera track con samples más parecidos
4. Replica estructura energética de la referencia

**T038** - `export_project(path, format="als")` - Guarda proyecto
**T039** - `load_project(path)` - Carga proyecto existente
**T040** - `get_project_summary()` - Resumen completo
**T041** - `suggest_improvements()` - Analiza y sugiere
**T042** - `compare_to_reference(reference)` - Compara canción vs referencia
**T043** - `undo_last_action()` - Deshacer
**T044** - `clear_project()` - Limpia todo para empezar de nuevo
**T045** - `validate_project()` - Verifica coherencia completa
**T046** - `add_variation_to_section(section_index)` - Variación en sección
**T047** - `create_transition(from_section, to_section, type)` - Transición
**T048** - `humanize_track(track_index, intensity)` - Human feel
**T049** - `apply_groove(track_index, groove_template)` - Groove
**T050** - `create_fx_automation(track_index, fx_type, section)` - FX auto

---

## PRIORIDAD DE EJECUCIÓN

### Bloque 1 (CRÍTICO - sin esto no hay canción):
T001-T010: Song generator profesional
T011-T020: Audio clips reales

### Bloque 2 (Alta - sin esto no suena profesional):
T021-T035: Mezcla y routing

### Bloque 3 (Media - workflow):
T036-T050: Un comando para todo

---

## 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** con `{"status": "success", "result": ...}` o `{"status": "error", "message": ...}`
4. **Mantener compatibilidad** con tools existentes del Sprint 1
5. **Usar engines del Sprint 1** para selección de samples
6. **Paths absolutos de Windows** en todo

---

## ARCHIVOS A MODIFICAR/CREAR

### Modificar:
- `mcp_server/engines/song_generator.py` → Reescribir completo
- `AbletonMCP_AI/__init__.py` → Agregar 20+ handlers nuevos
- `mcp_server/server.py` → Agregar 15+ nuevas tools MCP

### Crear:
- `mcp_server/engines/mixing_engine.py` → T021-T035 (lógica de mezcla)
- `mcp_server/engines/workflow_engine.py` → T036-T050 (workflow completo)

---

**Cuando termines, avisale a Qwen.**
Él va a: compilar, probar, arreglar bugs, y verificar que funcione end-to-end.