# Proposal: Automated Mix Calibration

## Intent

All track volumes, pans, and sends are hardcoded constants. No frequency balancing. Master chain uses Pro-Q_3/Pro-C_2/Pro-L_2 with DEFAULT presets. Result: flat, amateur sound with bass-drum masking and no stereo width.

Add a post-processing calibrator that sets role-based LUFS volumes, HPF/LPF EQ, stereo panning, calibrated sends, and a proper mastering chain.

## Scope

### In Scope
- `src/calibrator/` module — calibrates a `SongDefinition` with role-aware mix settings
- LUFS-targeted volumes per role (kick -8 → drumloop 0.85, bass -10 → 0.72, lead -12 → 0.78, etc.)
- HPF/LPF via ReaEQ plugins prepended to each track (HPF on non-bass, LPF on bass)
- Stereo width management: bass/kick mono, lead wide (±0.3), chords wider (±0.5), clap off-center
- Calibrated send levels: lead 25% verb / 15% delay, chords 30% / 10%, pad 40% / 20%, drums 10% / 0%
- Master chain swap: Pro-Q_3 → Ozone 12 Equalizer, Pro-C_2 → Ozone 12 Dynamics, Pro-L_2 → Ozone 12 Maximizer
- `--no-calibrate` flag on compose.py to skip calibration

### Out of Scope
- True LUFS measurement (requires REAPER rendering — Phase 2 via ReaScript)
- ReaEQ parameter automation (parametric curves, dynamic EQ)
- Reference-track matching
- Multi-genre calibration profiles (reggaeton only for now)

## Capabilities

### New Capabilities
- `mix-calibration`: Role-based volume/pan/send/EQ calibration applied as post-processing step on `SongDefinition`

### Modified Capabilities
<!-- None — existing compose pipeline is unchanged; calibration is additive -->

None

## Approach

**Separate calibrator module** (`src/calibrator/`), NOT inline in compose.py. Rationale:
- compose.py is 612 lines — adding 200+ calibration lines would bloat it
- Calibration is a separate concern (mixing vs. composition)
- Independently testable, skippable via `--no-calibrate`
- Follows existing module pattern (selector/, builder/, validator/)

**Data flow**: `compose.main()` → `SongDefinition` → `Calibrator.apply(song)` → calibrated `SongDefinition` → `RPPBuilder.build()`

**HPF/LPF strategy**: Add ReaEQ plugin to each track's plugin list. Extend `_build_plugin()` to serialize `PluginDef.params` into VST parameter slots (currently ignored). ReaEQ uses 19 fixed param slots; we populate band 0 (type=1 HPF or type=0 LPF) with frequency values.

**Master chain**: Replace `master_plugins=["Pro-Q_3","Pro-C_2","Pro-L_2"]` with `["Ozone_12_Equalizer","Ozone_12_Dynamics","Ozone_12_Maximizer"]` using default presets already in registry.

## Affected Areas

| Area | Impact | Description |
|------|--------|-------------|
| `src/calibrator/__init__.py` | New | `Calibrator` class with `apply(song)` method |
| `src/calibrator/presets.py` | New | Calibration presets (LUFS targets, HPF/LPF freqs, pans, sends) |
| `src/reaper_builder/__init__.py` | Modified | `_build_plugin()` — serialize `PluginDef.params` to VST slots |
| `scripts/compose.py` | Modified | Import Calibrator, call after track build, add `--no-calibrate` flag |
| `tests/test_calibrator.py` | New | Unit tests for calibrator output |
| `src/core/schema.py` | Modified | Add `calibrate: bool` flag to `SongMeta` (optional) |

## Risks

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| ReaEQ param serialization breaks existing .rpp | Low | Feature-gated: only when `PluginDef.params` is non-empty; zero backcompat impact |
| Ozone 12 plugins missing on some machines | Med | Fallback to Pro-Q_3/Pro-C_2/Pro-L_2 if Ozone registry lookup fails |
| Too-aggressive HPF cuts thin out full sections | Low | Conservative cutoffs: HPF 60Hz for drums, 200Hz for lead/chords; tunable via presets |

## Rollback Plan

1. Revert compose.py: remove `--no-calibrate` flag, remove calibrator import
2. Revert builder: remove params serialization in `_build_plugin()`
3. Delete `src/calibrator/`
4. Restore original `VOLUME_LEVELS`, `SEND_LEVELS`, `MASTER_VOLUME`, `master_plugins` constants

## Dependencies

- `PLUGIN_REGISTRY` entries for `ReaEQ`, `Ozone_12_Equalizer`, `Ozone_12_Dynamics`, `Ozone_12_Maximizer` (all exist)
- No new Python dependencies required

## Success Criteria

- [ ] `Calibrator.apply(song)` returns a `SongDefinition` with volume/pan/send values matching role-based presets
- [ ] Each non-return track has at least one ReaEQ plugin with HPF or LPF params set
- [ ] `--no-calibrate` flag preserves existing behavior (no calibration applied)
- [ ] Generated .rpp with calibration produces audibly cleaner mix (verified by ear)
- [ ] All 110 existing tests still pass (calibration is additive, not breaking)