# 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*