reaper-control/.sdd/changes/archive/2026-05-03-generate-song/change/spec.md

Delta: generate-song

ADDED Requirements

Requirement: CLI generates REAPER .rpp from arguments

scripts/generate.py MUST accept --bpm, --key, --output, and --seed arguments. When invoked as python scripts/generate.py --bpm 95 --key Am --output output/song.rpp --seed 42, the script SHALL produce a valid REAPER .rpp file at the specified output path using seed 42 for all random choices.

Scenario: Happy path — produces 52-bar arrangement

• GIVEN no arguments beyond required ones; seed=42 is the default
• WHEN the CLI is invoked with --bpm 95 --key Am --output /tmp/song.rpp --seed 42
• THEN a .rpp file SHALL be written containing 9 tracks (7 normal + 2 return)
• AND the arrangement duration SHALL equal 52 bars at 95 BPM
• AND all 19 plugins (across tracks, returns, master) SHALL be present in the FX chains

Scenario: Default seed produces reproducible output

• GIVEN two invocations with identical arguments (including --seed 42)
• WHEN both are run in the same environment
• THEN the resulting .rpp files SHALL be byte-for-byte identical

Scenario: Invalid BPM raises ValueError

• GIVEN --bpm 0 or --bpm -10
• WHEN the CLI is invoked
• THEN a ValueError SHALL be raised with message matching bpm must be > 0

---

Requirement: validate_rpp_output(rpp_path) -> list[str] checks all structural invariants

The validation function MUST return an empty list for a valid .rpp, and a list of error strings for any violation.

Scenario: Returns empty list for valid output

• GIVEN a .rpp produced by the CLI with all required structure
• WHEN validate_rpp_output(path) is called
• THEN the result SHALL be []

Scenario: Detects wrong track count

• GIVEN a .rpp with fewer than 9 tracks
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "Expected 9 tracks, got N"

Scenario: Detects missing plugin chains

• GIVEN a .rpp where a track is missing its FXCHAIN block
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "Track 'X' missing FXCHAIN"

Scenario: Detects broken audio clip paths

• GIVEN a .rpp containing an audio clip whose SOURCE WAVE path does not exist on disk
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "Audio clip path does not exist: /path/to/file.wav"

Scenario: Detects MIDI clips without notes

• GIVEN a .rpp containing a MIDI clip with zero notes
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "MIDI clip has no notes"

Scenario: Detects incorrect arrangement duration

• GIVEN a .rpp whose final item ends before the expected 52-bar duration at the given BPM
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "Arrangement ends at beat X, expected at least Y"

Scenario: Detects missing send routing

• GIVEN a .rpp where a non-return track has no AUXRECV send to a return track
• WHEN validate_rpp_output(path) is called
• THEN the returned list SHALL include "Track 'X' missing send to return track"

---

Requirement: scripts/generate.py uses REAPER drumloops with fallback

The script SHALL pick drumloop files from the Ableton drumloop directory, cycling through available files per variant, and SHALL fall back gracefully when a file is absent.

Scenario: Picks from seco and filtrado variants

• GIVEN the CLI is run with --seed 42
• WHEN the resulting .rpp is inspected
• THEN audio clips SHALL reference files from the seco and filtrado pools as defined in DRUMLOOP_FILES
• AND the variant per section SHALL follow DRUMLOOP_ASSIGNMENTS

Scenario: Falls back when perc loop file is missing

• GIVEN the file 91bpm bellako percloop.wav does not exist
• WHEN build_perc_track is called for a verse or chorus section
• THEN no Perc clip SHALL be added for that section (skip silently rather than crash)

---

Requirement: Test suite for generate-song

A test file at tests/test_generate_song.py MUST cover the CLI and validation function.

Scenario: CLI end-to-end smoke test

• GIVEN tmp_path fixture
• WHEN python scripts/generate.py --bpm 95 --key Am --output {tmp_path}/song.rpp --seed 42 is executed as a subprocess
• THEN the resulting file SHALL exist and be non-empty

Scenario: Validation passes for valid output

• GIVEN a generated .rpp at a known path
• WHEN validate_rpp_output(path) is called
• THEN it SHALL return []

Scenario: Validation detects track count violation

• GIVEN a .rpp with 5 tracks (not 9)
• WHEN validate_rpp_output(path) is called
• THEN the error list SHALL contain a track-count violation message

Scenario: Reproducibility — same seed gives same output

• GIVEN two temp paths
• WHEN the CLI is run with --seed 42 to both paths
• THEN both output files SHALL have identical content