feat: reggaeton production system with intelligent sample selection and FLP generation

README.md

@@ -0,0 +1,58 @@
+# FL Control — Reggaeton Production System
+
+Python system for generating complete reggaeton `.flp` projects for FL Studio from the command line, using intelligent sample selection and algorithmic composition.
+
+## 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
+
+## Quick Start
+
+```bash
+pip install -r requirements.txt
+
+# Analyze your sample library
+1_ANALIZAR.bat          # or: python src/analyzer/__init__.py
+
+# Compose a track
+python scripts/compose_track.py --key Am --bpm 95 --bars 8 --output output/track.flp
+# or double-click:
+COMPONER.bat
+```
+
+## Project Structure
+
+```
+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
+```
+
+## System Requirements
+
+- Python 3.10+
+- FL Studio (for opening generated `.flp` files)
+- ~4GB disk space for sample library (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
+
+## 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.