reaper-control/.sdd/changes/mix-calibration/spec.md

mix-calibration Specification

Purpose

Post-processing calibrator that applies role-aware volume, EQ, stereo width, sends, and mastering chain to a SongDefinition before .rpp generation.

Requirements

Requirement: Calibrator Post-Processing

The system MUST provide a Calibrator.apply(song: SongDefinition) -> SongDefinition method that mutates and returns the song with calibrated mix settings. Calibration MUST run as a distinct step between track construction and RPPBuilder.build().

Scenario: Happy path — full calibration

• GIVEN a complete SongDefinition with 7 tracks (Drumloop, Perc, 808 Bass, Chords, Lead, Clap, Pad) and 2 return tracks
• WHEN Calibrator.apply(song) is called
• THEN song.tracks[].volume matches role-based LUFS targets
• AND each non-return track has a ReaEQ plugin prepended to its plugins list
• AND song.tracks[].pan follows stereo-width rules
• AND song.tracks[].send_level contains calibrated reverb/delay values
• AND song.master_plugins contains Ozone 12 Equalizer, Dynamics, Maximizer

Requirement: Role-Based Volumes

The system SHALL set track volumes from a preset table keyed by track role (name → role mapping). Volumes MUST be in the REAPER-compatible 0.0–1.0 range.

Role	Volume	Target
drumloop	0.85	kick prominence
bass	0.72	sub-presence
chords	0.78	harmonic support
lead	0.78	melody clarity
clap	0.75	transient punch
pad	0.68	ambient depth
perc	0.72	groove feel

Scenario: Unknown track role

• GIVEN a track with name not matching any preset role
• WHEN calibrated
• THEN the track's volume and pan remain unchanged (preserved as-is)

Requirement: HPF/LPF EQ per Role

The system SHALL prepend a ReaEQ PluginDef to each non-return track's plugins list with appropriate HPF or LPF parameters. Bass tracks (808 Bass) SHALL receive LPF. All other tracks SHALL receive HPF.

Scenario: HPF on lead/chords/pad tracks

• GIVEN a track named "Chords", "Lead", "Pad", "Clap", "Perc", or "Drumloop"
• WHEN calibrated
• THEN a ReaEQ plugin is inserted at plugins[0] with param 0=1 (band enabled), 1=1 (HPF type), 2=200.0 (frequency for melodic) or 2=60.0 (drums)

Scenario: LPF on bass track

• GIVEN a track named "808 Bass"
• WHEN calibrated
• THEN a ReaEQ plugin is inserted at plugins[0] with param 0=1, 1=0 (LPF type), 2=300.0 (frequency)

Scenario: Return tracks excluded

• GIVEN tracks named "Reverb" or "Delay"
• WHEN calibrated
• THEN no ReaEQ plugin is added (return tracks are skipped)

Requirement: Stereo Width per Role

The system SHALL set track pan values to role-specific defaults.

Role	Pan	Rationale
drumloop	0.0	mono center
bass	0.0	mono sub
chords	+0.5	wide right
lead	+0.3	right-leaning
clap	-0.15	off-center left
pad	-0.5	wide left
perc	+0.12	slight right

Requirement: Send Calibration

The system SHALL set send_level dict entries for reverb (index=return_track_count) and delay (index=return_track_count+1) on each non-return track.

Role	Reverb	Delay
drumloop	0.10	0.00
bass	0.05	0.02
chords	0.30	0.10
lead	0.25	0.15
clap	0.10	0.00
pad	0.40	0.20
perc	0.10	0.00

Requirement: Master Chain Upgrade

The system SHALL replace master_plugins with ["Ozone_12_Equalizer","Ozone_12_Dynamics","Ozone_12_Maximizer"]. If registry lookup for any Ozone plugin fails, the system MUST fall back to ["Pro-Q_3","Pro-C_2","Pro-L_2"].

Requirement: Calibration Toggle

The system SHALL support a --no-calibrate CLI flag. When passed, Calibrator.apply() MUST NOT be called. When omitted (default), calibration MUST run. SongMeta MAY include an optional calibrate: bool field defaulting to True.

Scenario: --no-calibrate preserves existing behavior

• GIVEN compose.py --no-calibrate -o out.rpp
• WHEN the song is built
• THEN Calibrator.apply() is never invoked
• AND the generated .rpp matches the pre-calibration baseline