reaper-control/.sdd/changes/smart-chords/design.md

Design: Smart Chord Engine

Technical Approach

New ChordEngine class in src/composer/chords.py. Pure Python, seed-based random.Random, using existing CHORD_TYPES and NOTE_NAMES from composer/__init__.py. Voice leading: greedy scoring of candidate voicings. build_chords_track() imports and delegates.

Architecture Decisions

Decision	Choice	Rejected	Rationale
RNG strategy	random.Random(seed) instance	Global random.seed()	Isolates ChordEngine from other modules; no side effects
Voice scoring	Greedy min-semi distance per chord	Global optimization (DP)	Simple, fast, produces musical results for ≤12 chords; DP overkill
Inversion encoding	dict[str, int] → {"root":0, "first":1, "second":2}	Enum class	Follows existing dict-based config pattern (CHORD_TYPES)
Emotion mapping	Hardcoded dict[str, list[int]] degree offsets	Data file	4 modes, 7 entries each — file indirection adds complexity for no benefit
Chord output format	list[list[int]] (list of MIDI note lists)	Dict with metadata	Directly feedable to existing MidiNote factory; no schema change

Data Flow

User: --emotion dark --seed 42
         │
         ▼
build_chords_track() → ChordEngine("Am", seed=42)
         │
         ├── progression(8, emotion="dark", bpc=4, inversion="root")
         │      │
         │      ├── EMOTION_PROGRESSIONS["dark"] → [0, 5, 10, 7]
         │      ├── get_chord_degrees(root, scale, degrees) → [chords]
         │      ├── voice_leading(chords, "root") → [voicings]
         │      └── apply_inversion(voicings, "root") → list[list[int]]
         │
         ▼
   MidiNote list → ClipDef → TrackDef

File Changes

File	Action	Description
src/composer/chords.py	Create	ChordEngine class + EMOTION_PROGRESSIONS
scripts/compose.py	Modify	build_chords_track() imports + delegates to ChordEngine
tests/test_chords.py	Create	Unit tests for R1-R4, integration for R7

Interfaces

# src/composer/chords.py
class ChordEngine:
    def __init__(self, key: str, seed: int = 42): ...
    def progression(
        self, bars: int, emotion: str = "classic",
        beats_per_chord: int = 4, inversion: str = "root"
    ) -> list[list[int]]: ...

    # Internal
    def _get_degrees(self, emotion: str) -> list[int]: ...
    def _voice_leading(self, chords: list[list[int]], inversion: str) -> list[list[int]]: ...
    def _score_voicing(self, prev: list[int], cand: list[int]) -> int: ...
    def _apply_inversion(self, voicing: list[int], inversion: str) -> list[int]: ...

# EMOTION_PROGRESSIONS — degree offsets (semitone from root) per emotion
# Pattern: [(degree, quality), ...]
EMOTION_PROGRESSIONS = {
    "romantic": [(0, "min"), (8, "maj"), (4, "maj"), (10, "maj")],  # i-VI-III-VII
    "dark":     [(0, "min"), (5, "min"), (10, "maj"), (7, "min")],  # i-iv-V-v
    "club":     [(0, "min"), (10, "maj"), (8, "maj"), (4, "maj")],  # i-VII-VI-III
    "classic":  [(0, "min"), (8, "maj"), (4, "maj"), (10, "maj")],  # i-VI-III-VII
}

Voice Leading Algorithm

For position i (0..n-1):
  1. Build all voicings of chord[i] (root + inversions → candidate lists)
  2. If i > 0: for each candidate, score = sum(abs(c[j] - prev[j])) across voices
  3. Filter candidates where score ≤ 4 per voice
  4. Select lowest-total-score candidate (greedy)
  5. If no candidate passes filter: keep raw chord (no voicing penalty)

Returns minimum-movement path through chord sequence.

Testing Strategy

Layer	What	Approach
Unit	Determinism (R1)	ChordEngine(seed=42).progression(8) × 3 calls — assert equality
Unit	Voice leading ≤4 (R2)	Run progression, verify all adjacent pairs
Unit	Inversions (R3)	Assert bass note = target (root/3rd/5th)
Unit	Emotion divergence (R4)	4 emotions → assert 4 distinct outputs
Integration	CLI --emotion flag (R7)	compose.py --emotion dark → verify ChordEngine called

Open Questions

• Should --emotion be a CLI flag or auto-detected from section type? Per proposal, explicit flag.