# SPRINT 4 — BLOQUE B: TESTING END-TO-END, INTEGRACIÓN Y WORKFLOW DE PRODUCCIÓN (T051-T100)

> **Fecha**: 2026-04-11
> **Estado Sprint 4-A**: ✅ COMPLETO — Verificación post-ejecución, Browser API, Arrangement, Diagnóstico, Robustez
> **Objetivo Sprint 4-B**: Que TODO funcione end-to-end con Ableton abierto y real
> **Revisión**: Qwen

---

## CONTEXTO

Sprint 4-A agregó verificación, diagnóstico y robustez. Ahora sabemos EXACTAMENTE qué funciona y qué no.
El Bloque B se enfoca en:

1. **Testing real** — ejecutar cada tool con Ableton abierto y verificar que se vea en la UI
2. **Integración completa** — conectar engines del Sprint 3 (song_generator, pattern_library, mixing_engine) con handlers del Sprint 4-A
3. **Workflow de producción** — pipeline completo de una canción de reggaeton profesional

---

## FASE B1: TESTING END-TO-END (T051-T065)

### Objetivo: Cada tool nueva debe probarse con Ableton abierto

**T051** — Test `ping` → Verificar que responde instantáneamente (< 100ms)
**T052** — Test `health_check` → Score debe ser 5/5 con Ableton corriendo
**T053** — Test `get_system_diagnostics` → Debe retornar versión de Live, estado del browser, sesión
**T054** — Test `get_live_version` → Debe retornar "12.x.x"
**T055** — Test `test_browser_connection` → Debe listar secciones disponibles
**T056** — Test `scan_browser_section("instruments", depth=1)` → Debe retornar lista de instruments
**T057** — Test `get_track_details(0)` → Debe retornar snapshot del primer track
**T058** — Test `get_device_parameters(track_index, device_index)` → Debe listar parámetros de un device
**T059** — Test `set_device_parameter()` → Debe cambiar un parámetro y verificar el cambio
**T060** — Test `get_clip_notes()` → Debe leer notas de un clip MIDI existente
**T061** — Test `show_arrangement_view()` → Debe cambiar la vista de Ableton a Arrangement
**T062** — Test `show_session_view()` → Debe cambiar la vista de Ableton a Session
**T063** — Test `set_arrangement_position(bar=0)` → Debe mover el playhead al inicio
**T064** — Test `loop_arrangement_region(0, 8)` → Debe crear un loop de 8 bars
**T065** — Test `test_sample_loading()` con sample real → Debe reportar qué métodos funcionan

---

## FASE B2: INTEGRACIÓN ENGINES → HANDLERS (T066-T080)

### Objetivo: Los engines del Sprint 3 deben usarse en handlers reales

**T066** — `_cmd_generate_full_song()` debe usar `ReggaetonGenerator.generate()`:
- Generar config con `song_generator.py`
- Para cada track en config:
  - Crear track en Ableton
  - Generar notas con `pattern_library.py`
  - Crear clips y escribir notas
  - Verificar con `_verify_clip_has_audio()`

**T067** — `_cmd_generate_dembow_clip()` debe usar `DembowPatterns.get_kick_pattern()`:
- Obtener pattern real de `pattern_library.py`
- Crear clip en Ableton
- Escribir notas del pattern
- Verificar notas escritas

**T068** — `_cmd_generate_bass_clip()` debe usar `BassPatterns.get_bass_line()`:
- Obtener línea de bass de `pattern_library.py`
- Crear clip y escribir notas
- Verificar

**T069** — `_cmd_generate_chords_clip()` debe usar `ChordProgressions`:
- Obtener progresión de acordes
- Generar notas de acordes con voicings
- Escribir en clip
- Verificar

**T070** — `_cmd_generate_melody_clip()` debe usar `MelodyGenerator.generate_melody()`:
- Generar melodía con escala detectada
- Crear clip y escribir notas
- Verificar

**T071** — `_cmd_apply_human_feel()` debe usar `HumanFeel.apply_all_humanization()`:
- Leer notas existentes del clip
- Aplicar micro-timing, velocity variation
- Re-escribir notas
- Verificar cambios

**T072** — `_cmd_add_percussion_fills()` debe usar `PercussionLibrary`:
- Obtener fills de `pattern_library.py`
- Crear clips de fills en posiciones de transición
- Verificar

**T073** — `_cmd_create_bus_track()` debe usar `BusManager` de `mixing_engine.py`:
- Crear bus con configuración profesional
- Verificar que el track existe
- Retornar track_index

**T074** — `_cmd_route_track_to_bus()` debe usar `BusManager.route_track_to_bus()`:
- Routear track al bus correcto
- Verificar routing
- Retornar confirmación

**T075** — `_cmd_configure_eq()` debe usar `EQConfiguration.get_preset()`:
- Insertar EQ Eight si no existe
- Configurar con preset apropiado
- Verificar parámetros

**T076** — `_cmd_configure_compressor()` debe usar `CompressionSettings`:
- Insertar Compressor si no existe
- Configurar con preset
- Verificar

**T077** — `_cmd_setup_sidechain()` debe usar `CompressionSettings` + `BusManager`:
- Insertar Compressor en target
- Configurar sidechain desde kick
- Verificar `sidechain_active`

**T078** — `_cmd_apply_master_chain()` debe usar `MasterChain.apply_master_chain()`:
- Insertar cadena completa: EQ → Comp → Sat → Limiter
- Configurar con preset (club/streaming/radio)
- Verificar cada device

**T079** — `_cmd_auto_gain_staging()` debe usar `GainStaging.auto_gain_staging()`:
- Ajustar volúmenes de todos los tracks
- Verificar headroom
- Retornar niveles aplicados

**T080** — `_cmd_full_quality_check()` debe usar `MixQualityChecker.run_quality_check()`:
- Analizar clipping, phase, frequency balance
- Retornar score y sugerencias

---

## FASE B3: WORKFLOW DE PRODUCCIÓN COMPLETO (T081-T095)

### Objetivo: Un pipeline completo de análisis → generación → mezcla → export

**T081** — `_cmd_analyze_library()`:
- Ejecutar análisis espectral de 511 samples
- Generar `.features_cache.json`
- Retornar estadísticas completas

**T082** — `_cmd_build_embeddings_index()`:
- Crear embeddings de 511 samples
- Guardar `.embeddings_index.json`
- Retornar dimensiones y count

**T083** — `_cmd_get_similar_samples(sample_path, top_n=10)`:
- Buscar samples similares por distancia coseno
- Retornar ranking con similitudes

**T084** — `_cmd_find_samples_like_audio(audio_path, top_n=20)`:
- Analizar archivo de referencia
- Encontrar samples similares en librería
- Retornar matches con scores

**T085** — `_cmd_get_user_sound_profile()`:
- Cargar perfil desde `.user_sound_profile.json`
- Retornar BPM, key, timbre preferidos

**T086** — `_cmd_get_recommended_samples(role, count=5)`:
- Usar perfil del usuario para recomendar
- Retornar samples por rol

**T087** — `_cmd_generate_from_reference(reference_audio_path)`:
- Analizar referencia
- Seleccionar samples similares
- Generar track completo con samples reales
- Configurar buses y mezcla
- Retornar resumen completo

**T088** — `_cmd_produce_reggaeton(bpm, key, style, structure)`:
- Pipeline completo:
  1. Seleccionar samples con `get_recommended_samples()`
  2. Generar config con `ReggaetonGenerator`
  3. Crear tracks en Ableton
  4. Generar clips con patterns reales
  5. Configurar buses y routing
  6. Aplicar mezcla automática
  7. Configurar sidechain
- Retornar resumen completo con verificación

**T089** — `_cmd_produce_arrangement(bpm, key, style, structure)`:
- Como T088 pero en Arrangement View
- Clips posicionados en tiempo
- Automatización incluida

**T090** — `_cmd_complete_production(bpm, key, style, output_dir)`:
- Pipeline T088 + renderizado
- Exportar stems + full mix
- Generar release notes
- Retornar paths de archivos

**T091** — `_cmd_batch_produce(count, style, bpm_range, key_range)`:
- Generar múltiples canciones
- Variación automática
- Cada una única

**T092** — `_cmd_export_stems(output_dir)`:
- Renderizar cada bus como stem
- Drums, Bass, Music, FX stems
- Guardar en directorio

**T093** — `_cmd_render_full_mix(output_path)`:
- Renderizar mezcla completa
- WAV 24-bit/44.1kHz
- Con mastering aplicado

**T094** — `_cmd_render_instrumental(output_path)`:
- Mutear melodías/vocals
- Renderizar solo drums + bass

**T095** — `_cmd_generate_release_notes()`:
- Generar notas de release
- BPM, key, structure
- Samples usados
- Mixing notes
- Loudness stats

---

## FASE B4: DOCUMENTACIÓN Y UX (T096-T100)

**T096** — Crear `docs/GUIA_DE_USO.md`:
- Lista completa de 118+ tools
- Descripción de cada una
- Ejemplos de uso
- Orden recomendado para producción

**T097** — Crear `docs/WORKFLOW_REGGAETON.md`:
- Pipeline paso a paso para producir reggaeton
- Desde análisis de librería hasta export final
- Screenshots descriptivos

**T098** — Crear `docs/TROUBLESHOOTING.md`:
- Problemas comunes y soluciones
- Cómo diagnosticar con `health_check()` y `get_system_diagnostics()`
- Qué hacer si Ableton no responde

**T099** — Tool MCP `help()` → Retorna lista de tools con descripción breve
**T100** — Tool MCP `get_workflow_status()` → Retorna estado actual del proyecto

---

## ARCHIVOS A MODIFICAR

| Archivo | Cambios |
|---------|---------|
| `AbletonMCP_AI/__init__.py` | +30 handlers nuevos (workflow completo) |
| `mcp_server/server.py` | +15 tools MCP nuevas |
| `docs/GUIA_DE_USO.md` | Nuevo - Documentación completa |
| `docs/WORKFLOW_REGGAETON.md` | Nuevo - Pipeline de producción |
| `docs/TROUBLESHOOTING.md` | Nuevo - Diagnóstico |

## RESTRICCIONES

1. **Compilar después de cada archivo**: `python -m py_compile "<path>"`
2. **NO tocar `libreria/`** - solo lectura
3. **Cada handler debe verificar POST-ejecución** (usar patterns del Sprint 4-A)
4. **Mantener compatibilidad** con 118 tools existentes
5. **Paths absolutos de Windows** en todo

---

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