7bcd8052a9
Complete documentation system for LLM consumption: primary LLM_CONTEXT.md (27KB system overview), 4 module deep-dives (composer, reaper-builder, reaper-scripting, calibrator), 2 JSON Schema draft-07 contracts, CLI reference, and README correction (FL Studio -> REAPER identity).
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# 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.
|