# fl_control — REAPER .rpp Reggaetón Generator

> **About the name**: Despite the directory name `fl_control`, this system generates **REAPER `.rpp` project files**. The name is retained for backward compatibility with repository URLs and CI/CD pipelines. This tool targets REAPER exclusively.

Python system for generating complete reggaetón `.rpp` projects for REAPER from the command line, using algorithmic composition, deterministic melody engines, and calibrated mixing.

## Features

- **Chord Engine** — Emotion-aware progressions with voice leading (romantic, dark, club, classic)
- **Melody Engine** — Hook-based call-and-response motifs (hook, stabs, smooth styles)
- **808 Bass** — Proven reggaetón harmonic pattern with CC11 sidechain ducking from drum analysis
- **RPP Builder** — Generates valid REAPER `.rpp` files from a `SongDefinition` dataclass
- **ReaScript Generator** — Self-contained Python scripts for REAPER post-processing (plugin loading, mix calibration, rendering, LUFS measurement)
- **Calibrator** — Role-based volume, pan, EQ, and send presets plus master chain configuration
- **Sample Selector** — Scores samples by key compatibility (circle of fifths), BPM proximity, and character
- **Plugin Registry** — ~97 VST2/VST3 plugins with verified GUIDs and preset data

## Quick Start

```bash
pip install -r requirements.txt

# Generate a reggaetón track
python scripts/generate.py --bpm 95 --key Am --output output/song.rpp --seed 42

# Or use the full pipeline directly
python scripts/compose.py --bpm 99 --key Am --emotion romantic --output output/song.rpp

# Validate output
python scripts/generate.py --bpm 95 --key Dm --seed 123 --validate

# Open the result in REAPER
start output/song.rpp
```

## Project Structure

```
fl_control/
├── src/
│   ├── core/               # Data model (SongDefinition, TrackDef, ClipDef, etc.)
│   ├── composer/            # Chord engine, melody engine, rhythm patterns
│   ├── reaper_builder/      # RPPBuilder, PLUGIN_REGISTRY (~97 plugins), render
│   ├── reaper_scripting/    # ReaScript generator, command/result protocol
│   ├── calibrator/          # Mix calibration presets (volume, pan, sends, EQ)
│   ├── selector/            # Intelligent sample scoring & selection
│   └── validator/           # .rpp output validation
├── scripts/                 # CLI entry points
│   ├── compose.py           # Full composition pipeline
│   ├── generate.py          # Thin wrapper around compose
│   └── run_in_reaper.py     # ReaScript generation & execution
├── knowledge/               # Musical domain knowledge (progressions, templates)
├── data/                    # Generated indexes (gitignored)
├── .sdd/                    # Spec-Driven Development artifacts
└── docs/                    # LLM-ready documentation
    ├── LLM_CONTEXT.md       # Complete system overview for LLMs
    ├── CLI.md               # Full CLI reference
    ├── modules/             # Module deep-dives
    └── schemas/             # JSON Schemas (draft-07)
```

## System Requirements

- Python 3.10+
- REAPER (Windows, v7.x) — for opening generated `.rpp` files and running ReaScripts
- Sample library with drumloops and FX samples (not included)

## Workflow

1. Ensure sample files exist at configured paths (see `scripts/compose.py` for drumloop paths)
2. Run `scripts/generate.py --bpm 95 --key Am --output output/song.rpp`
3. Open `output/song.rpp` in REAPER
4. (Optional) Run ReaScript post-processing: `python scripts/run_in_reaper.py output/song.rpp --action "add_plugins calibrate render"`

## Architecture

The system uses a `SongDefinition` dataclass as the single source of truth, decoupling composition logic from `.rpp` rendering. The pipeline is:

```
CLI → compose SongDefinition → Calibrator.apply() → RPPBuilder.write() → .rpp file
                                                              │
                                                              ▼
                                              ReaScriptGenerator.generate() → ReaScript → REAPER
```

See [docs/LLM_CONTEXT.md](docs/LLM_CONTEXT.md) for the complete system overview, data model reference, and extension guide.