# Change Archive: reggaeton-composer

**Archived**: 2026-05-02
**Status**: Completed & Verified

---

## Summary

Implemented a complete sample-driven reggaeton production system that generates valid FL Studio .flp projects from natural language prompts via CLI.

---

## Files Changed

| File | Role |
|------|------|
| `src/selector/__init__.py` | SampleSelector with scoring by key/BPM/character |
| `src/composer/melodic.py` | Melodic generators: bass_tresillo, lead_hook, chords_block, pad_sustain |
| `src/flp_builder/schema.py` | Extended with MelodicNote, MelodicTrack, melodic_tracks in SongDefinition |
| `src/flp_builder/builder.py` | FLPBuilder extended for melodic_tracks + melodic patterns |
| `src/flp_builder/skeleton.py` | Bug fix: CACHED_SAMPLE_EVENTS → STRIP_EVENTS |
| `scripts/compose_track.py` | Main CLI entrypoint |
| `COMPONER.bat` | Windows batch launcher |

---

## Verification Result

✅ 6/6 checks passed

**Command**: `python scripts/compose_track.py --key Am --bpm 95 --bars 8 --output output/reggaeton.flp`
**Output**: Valid .flp file, ~52KB

---

## Key Decisions

1. **Sample-first → pattern-first hybrid**: Rather than generating MIDI from scratch, the system selects compatible samples and wraps them in AUdsty pattern loops before building the FLP, ensuring results sound polished even when no samples match perfectly.

2. **Score-weighted selection**: SampleSelector ranks candidates by weighted multi-factor scoring (key match: 40%, BPM proximity: 30%, character tag alignment: 30%).

3. **Bug fix in skeleton.py**: `CACHED_SAMPLE_EVENTS` was an undefined constant — corrected to `STRIP_EVENTS` which correctly prevents duplicate sample events.

4. **CLI over library**: Exposed as a standalone script (`compose_track.py`) rather than a Python API, making it directly usable from shell/bat files.

---

## Architecture

```
scripts/compose_track.py
  └─ SampleSelector → selects best samples from data/libreria
  └─ MelodicComposer → generates bass/lead/chords/pad patterns
  └─ FLPBuilder → assembles .flp from skeleton + tracks + clips
```

---

## SDD Cycle

- **Proposal**: reggaeton-composer
- **Spec**: reggaeton production system specs
- **Design**: technical design with scoring algorithm, pattern injection, FLP schema
- **Tasks**: 6 implementation tasks
- **Verify**: 6/6 checks passed
- **Archive**: This file
