ableton-mcp-ai/docs/sprint_3_produccion_completa.md

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