reaper-control/docs/CLI.md

CLI Reference

Parent doc: LLM_CONTEXT.md

Overview

Three CLI entry points, all in scripts/:

Script	Role	Default output
compose.py	Full composition pipeline	.rpp file
generate.py	Thin wrapper around compose	.rpp file + optional validation
run_in_reaper.py	ReaScript generation & execution	ReaScript .py, result JSON, LUFS JSON

compose.py

Full pipeline: builds all tracks, applies calibration, generates .rpp.

Usage

python scripts/compose.py [--bpm BPM] [--key KEY] [--output PATH] [--seed SEED]
                          [--emotion EMOTION] [--inversion INVERSION]
                          [--no-calibrate]

Flags

Flag	Type	Default	Description
--bpm	float	99	Tempo. Must be > 0.
--key	str	"Am"	Musical key. Format: [A-G][b#]?m? (e.g. "Am", "Dm", "G", "F#m")
--output	str	"output/song.rpp"	Output .rpp file path. Parent directory created if missing.
--seed	int	None	Random seed. None = non-deterministic (system time).
--emotion	str	"romantic"	Chord emotion: romantic, dark, club, classic
--inversion	str	"root"	Preferred chord inversion: root, first, second
--no-calibrate	flag	False	Skip post-processing mix calibration

Examples

# Default reggaetón at 99 BPM in Am
python scripts/compose.py

# Specific BPM and key
python scripts/compose.py --bpm 95 --key Dm

# Deterministic output with seed
python scripts/compose.py --bpm 95 --key Am --seed 42

# Dark emotion with first inversion chords
python scripts/compose.py --emotion dark --inversion first

# Skip calibration (raw volumes from VOLUME_LEVELS in compose.py)
python scripts/compose.py --no-calibrate

# Custom output path
python scripts/compose.py --output my_project/song_v2.rpp

Output Structure

output/song.rpp          # REAPER project file

Console output includes:

• BPM and key confirmation
• Section count and total duration (bars + beats)
• Kick detection cache summary (per drumloop file)
• Final output path

generate.py

Thin wrapper around compose.py. Delegates by setting sys.argv and calling compose.main().

Usage

python scripts/generate.py [--bpm BPM] [--key KEY] [--output PATH] [--seed SEED]
                           [--emotion EMOTION] [--inversion INVERSION]
                           [--validate]

Flags

Flag	Type	Default	Description
--bpm	float	95	Tempo. Must be > 0.
--key	str	"Am"	Musical key
--output	str	"output/song.rpp"	Output .rpp path
--seed	int	42	Random seed
--emotion	str	"romantic"	Chord emotion
--inversion	str	"root"	Chord inversion
--validate	flag	False	Run validator after generation

Differences from compose.py

• Default BPM is 95 (vs 99 in compose.py)
• Default seed is 42 (vs None in compose.py)
• Has --validate flag (runs validate_rpp_output() after generation)
• No --no-calibrate flag (calibration always applied)

Examples

# Generate with default settings
python scripts/generate.py

# Generate with validation
python scripts/generate.py --bpm 95 --key Dm --seed 123 --validate

# Full custom generation
python scripts/generate.py --bpm 100 --key Fm --output output/custom.rpp --seed 7 --emotion club

Validation Errors

When --validate is set, errors are printed to stderr:

Validation errors:
  - Expected 416 beats, found 400 beats
  - Missing drumloop in section: chorus

Exit code 1 on validation failure.

run_in_reaper.py

Generates a ReaScript for post-processing and polls for results.

Usage

python scripts/run_in_reaper.py <rpp_path> [--output WAV_PATH] [--timeout SECONDS]
                                 [--plugins-config JSON_PATH] [--action ACTIONS]

Arguments and Flags

Arg/Flag	Type	Default	Description
rpp_path	positional	(required)	Path to .rpp file
--output, -o	str	<rpp_stem>_rendered.wav	Rendered WAV output path
--timeout	int	120	Seconds to poll for result JSON
--plugins-config	str	None	Path to JSON-serialized SongDefinition (for deriving plugins_to_add)
--action	str	"calibrate"	Space-separated action pipeline

Actions

Space-separated list of up to 5 actions, executed in order:

add_plugins configure_fx_params verify_fx calibrate render

Each action name maps to a function in the generated ReaScript. Unknown action names are ignored.

Examples

# Basic calibration on an existing .rpp
python scripts/run_in_reaper.py output/song.rpp

# Full pipeline: load plugins, calibrate, render
python scripts/run_in_reaper.py output/song.rpp --action "add_plugins calibrate render"

# With plugin config from JSON SongDefinition
python scripts/run_in_reaper.py output/song.rpp --plugins-config output/song.json --action "add_plugins configure_fx_params"

# Custom render output and extended timeout
python scripts/run_in_reaper.py output/song.rpp -o output/final_mix.wav --timeout 300 --action "calibrate render"

Output Files

scripts/fl_control_phase2.py           # Generated ReaScript
scripts/fl_control_command.json        # Command JSON for ReaScript
scripts/fl_control_result.json         # Result JSON from ReaScript (polled)
output/<song>_lufs.json               # LUFS metrics
output/<song>_fx_errors.json          # FX errors (if any)

Exit Codes

Code	Meaning
0	Success
1	Error: .rpp not found, plugin config not found, result read error, or REAPER error
2	Timeout: result JSON not found within timeout

Key Validation

All scripts validate the key format: ^[A-G][b#]?m?$

Valid examples: "Am", "C", "D#m", "Gb", "F#".

Invalid: "A minor", "c" (lowercase), "H", "Am7".

BPM Validation

BPM must be > 0. Min/max enforced by SongDefinition.validate(): 20–999.

Determinism

• When --seed is provided, all random operations use random.Random(seed) for reproducible output.
• Same (--bpm, --key, --seed, --emotion, --inversion) produces identical .rpp files.
• ReaScript seed is derived from the CLI seed. Same command → same script.