Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs

docs/MELODY_GENERATOR_README.md

@@ -0,0 +1,184 @@
+# Melody Generator README
+
+## Modulo de generacion melodica procedural para reggaeton
+
+**Version:** Sprint Granular v0.1.40  
+**Tareas:** T121-T135  
+**Archivo:** `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/melody_generator.py`
+
+---
+
+## Proposito
+
+El modulo `melody_generator.py` proporciona generacion proceduralde melodias MIDI para tracks armonicos en producciones de reggaeton. Se integra con `reference_listener` para deteccion automatica de tonalidad y genera melodias coherentes con la estructura del track.
+
+---
+
+## Caracteristicas Principales
+
+### T121: Escalas y Tontericas
+
+- Soporte para escalas menores (Am, Bm, Cm, Dm, Em, Fm, Gm, F#m)
+- Mapeo completo de raices MIDI por tonalidad
+- Cuantizacion automatica a escala
+
+### T122-T124: Progresiones de Acordes
+
+```python
+REGGAETON_CHORD_PROGRESSION = ['Am', 'F', 'G', 'Em']
+```
+
+- Progresion clasica reggaeton Am-F-G-Em
+- Soporte para variaciones modales
+- Transiciones suaves entre secciones
+
+### T125-T127: Generacion de Melodias
+
+```python
+@dataclass
+class MidiNote:
+    pitch: int
+    start_beat: float
+    duration_beats: float
+    velocity: int = 80
+```
+
+- Notas MIDI estructuradas
+- Control de duracion y velocidad
+- Cuantizacion a beats
+
+### T128-T130: Contorno Melodico
+
+- Melodias ascendentes para builds
+- Melodias descendentes para drops
+- Contornos por seccion
+
+### T131-T135: Integracion con Arrangement
+
+- Melodias por seccion (intro, build, drop, break)
+- Variaciones A/B para evitar repeticion
+- Sincronizacion con estructura reggaeton 95 BPM
+
+---
+
+## API Principal
+
+### `scale_notes(root_midi: int, octaves: int) -> List[int]`
+
+Genera notas de la escala Am en el rango especificado.
+
+**Args:**
+- `root_midi`: Nota raiz en MIDI (default: A3 = 57)
+- `octaves`: Numero de octavas (default: 2)
+
+**Returns:**
+- Lista de pitches MIDI en la escala
+
+---
+
+### `quantize_to_scale(pitch: int, scale_root: int) -> int`
+
+Cuantiza un pitch MIDI a la nota mas cercana en la escala.
+
+**Args:**
+- `pitch`: pitch MIDI a cuantizar
+- `scale_root`: raiz de la escala
+
+**Returns:**
+- Pitch MIDI cuantizado
+
+---
+
+### `MidiNote`
+
+Dataclass para representar notas MIDI.
+
+```python
+note = MidiNote(
+    pitch=60,
+    start_beat=0.0,
+    duration_beats=0.5,
+    velocity=90
+)
+```
+
+---
+
+## Integracion con MCP
+
+El melody generator se invoca desde `server.py` en la generacion de tracks:
+
+```python
+def generate_melody_for_section(
+    track_index: int,
+    key: str,
+    section: str,
+    bars: int = 4,
+    style: str = "reggaeton"
+) -> List[MidiNote]:
+    ...
+```
+
+---
+
+## Tests
+
+Los tests se encuentran en `tests/test_melody_generator.py`:
+
+```powershell
+python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_melody_generator.py"
+```
+
+---
+
+## Dependencias
+
+- `reference_listener.py` - Deteccion de tonalidad
+- `arrangement_intelligence.py` - Estructura por seccion
+- `song_generator.py` - Orquestacion de generacion
+
+---
+
+## Ejemplo de Uso
+
+```python
+from melody_generator import MidiNote, scale_notes, quantize_to_scale
+
+# Obtener notas de la escala Am
+notes = scale_notes(root_midi=57, octaves=2)
+
+# Cuantizar un pitch fuera de escala
+pitch = 62  # D4 (fuera de Am)
+quantized = quantize_to_scale(pitch, scale_root=57)
+
+# Crear nota MIDI
+note = MidiNote(
+    pitch=quantized,
+    start_beat=0.0,
+    duration_beats=1.0,
+    velocity=80
+)
+```
+
+---
+
+## Notas de Implementacion
+
+1. **Tonalidad**: El modulo detecta automaticamente la tonalidad desde el reference_listener
+2. **Estructura**: Respeta la estructura reggaeton definida en `arrangement_intelligence.py`
+3. **Variacion**: Genera variaciones A/B para evitar repeticion
+4. **Cuantizacion**: Siempre cuantiza a la escala detectada
+
+---
+
+## Roadmap
+
+- [ ] T136: Integracion con chord progression avanzado
+- [ ] T137: Melodias con glide/pitch bend
+- [ ] T138: Melodias con arpregios rapidos
+- [ ] T139: Melodias con call-and-response
+
+---
+
+*Maintained by: AbletonMCP-AI Team*
+*Last updated: 2026-04-05*