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

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 for the complete system overview, data model reference, and extension guide.