docs: LLM-ready documentation suite — LLM_CONTEXT.md, module deep-dives, JSON schemas, CLI reference
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).
This commit is contained in:
renato97
86
README.md
86
README.md
@@ -1,27 +1,36 @@
|
||||
# FL Control — Reggaeton Production System
|
||||
# fl_control — REAPER .rpp Reggaetón Generator
|
||||
|
||||
Python system for generating complete reggaeton `.flp` projects for FL Studio from the command line, using intelligent sample selection and algorithmic composition.
|
||||
> **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
|
||||
|
||||
- **Forensic Sample Analyzer** — 4-layer audio analysis (signal, perceptual, musical, timbre) using aubio
|
||||
- **Intelligent Sample Selector** — scores samples by key compatibility (circle of fifths), BPM proximity, and character
|
||||
- **Melodic Generators** — reggaeton-idiomatic patterns: bass tresillo, melodic hooks, chord blocks, sustained pads
|
||||
- **FLP Builder** — assembles valid FL Studio project files from a JSON song definition
|
||||
- **MCP Server** — 28-tool Model Context Protocol server for AI-assisted production
|
||||
- **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
|
||||
|
||||
# Analyze your sample library
|
||||
1_ANALIZAR.bat # or: python src/analyzer/__init__.py
|
||||
# Generate a reggaetón track
|
||||
python scripts/generate.py --bpm 95 --key Am --output output/song.rpp --seed 42
|
||||
|
||||
# Compose a track
|
||||
python scripts/compose_track.py --key Am --bpm 95 --bars 8 --output output/track.flp
|
||||
# or double-click:
|
||||
COMPONER.bat
|
||||
# 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
|
||||
@@ -29,30 +38,49 @@ COMPONER.bat
|
||||
```
|
||||
fl_control/
|
||||
├── src/
|
||||
│ ├── analyzer/ # Forensic audio feature extraction
|
||||
│ ├── composer/ # Pattern generators (rhythm + melodic)
|
||||
│ ├── flp_builder/ # FL Studio .flp binary assembly
|
||||
│ └── selector/ # Intelligent sample scoring & selection
|
||||
├── mcp/ # MCP server (28 tools for AI integration)
|
||||
├── scripts/ # CLI entry points
|
||||
├── knowledge/ # Musical domain knowledge (progressions, templates)
|
||||
├── data/ # Generated indexes (gitignored)
|
||||
├── .sdd/ # Spec-Driven Development artifacts
|
||||
└── COMPONER.bat # Quick-compose launcher
|
||||
│ ├── 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+
|
||||
- FL Studio (for opening generated `.flp` files)
|
||||
- ~4GB disk space for sample library (not included)
|
||||
- REAPER (Windows, v7.x) — for opening generated `.rpp` files and running ReaScripts
|
||||
- Sample library with drumloops and FX samples (not included)
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Drop your sample library into `librerias/`
|
||||
2. Run `1_ANALIZAR.bat` to build the sample index
|
||||
3. Run `COMPONER.bat` to generate a track
|
||||
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 JSON `SongDefinition` as the single source of truth decoupling composition logic from FLP binary rendering. See `.sdd/` for full technical specs and design documents.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user