reaper-control/.sdd/changes/sidechain/proposal.md

Proposal: 808 Bass Sidechain Ducking

Intent

808 bass and kick drum overlap in low frequencies with zero separation. Professional reggaeton uses sidechain-style ducking — bass dips when kick hits — creating the "pumping" feel and preventing low-frequency mud. Currently build_bass_track() generates static-velocity MIDI notes with no awareness of the drumloop's kick pattern.

Scope

In Scope

• Pre-analyze drumloop WAV files to extract kick transient positions via DrumLoopAnalyzer
• Cache kick beat-positions per drumloop path (same file reused across sections)
• Generate MIDI CC11 (Expression) events on bass clips at kick hit positions
• Duck shape: instantaneous drop to CC11≈50, 80ms release ramp to CC11=127
• ClipDef schema extended with midi_cc: list[CCEvent] field
• RPPBuilder._build_midi_source() emits CC E-lines interleaved with Note events

Out of Scope

• Track-level volume automation envelopes (VOLENV2) — complex binary encoding, deferred
• ReaComp-sidechain routing via ReaScript — Phase 2 enhancement only
• DrumLoopAnalyzer integration at composition time (not pre-cached) — deferred to Phase 2
• Ducking for non-bass tracks (chords, lead, pad)
• User-configurable duck depth/shape — constants only

Capabilities

New Capabilities

• midi-cc-events: MIDI CC event emission in .rpp source — CC11 Expression events interleaved with notes in E-line stream
• kick-detection-cache: DrumLoopAnalyzer tied into composition pipeline; kick positions cached per drumloop WAV path

Modified Capabilities

• bass-generation: build_bass_track() accepts kick position data and generates per-note velocity ducking OR CC11 events synchronized to kick hits
• rpp-clip-encoding: _build_midi_source() emits E B0 0B xx lines alongside Note On/Off

Approach

Principle: MIDI CC11 (Expression) is the simplest .rpp-native sidechain. No REAPER-specific features, no binary envelope encoding, no ReaScript bridge. Pure MIDI standard — works with any synth (Serum 2 confirmed).

Data flow:

Drumloop WAV
  → DrumLoopAnalyzer.analyze() → transient_positions("kick")
  → beat-positions cache (dict[str, list[float]])
  → build_bass_track(sections, offsets, key_root, key_minor, kick_cache={})
  → generates CCEvent objects {controller=11, time, value}
  → ClipDef.midi_cc = [...]
  → RPPBuilder._build_midi_source() emits E-lines

CC11 ducking shape per kick hit (all times in beats relative to clip start):

Offset from kick	CC11 Value	Description
kick_time	50	Instant dip (~-9dB)
kick_time + 0.02	50	Hold through transient
kick_time + 0.18	127	Release complete (80ms ≈ 0.16 beats)

Key decision — MIDI CC11 vs alternatives:

Option	Verdict	Why
A: MIDI CC11 (Expression)	✅ Chosen	.rpp MIDI source format supports E B0 0B xx lines. Serum 2, most synths respond. Trivial builder change.
B: Track volume envelope (VOLENV2)	❌ Rejected	Binary/chunk encoding in .rpp — fragile, hard to debug, no benefit over CC11 for this use case.
C: ReaScript ReaComp sidechain	⏸️ Deferred	Works only in Phase 2 with REAPER running. Use as future enhancement for non-MIDI audio basses.

Affected Areas

Area	Impact	Description
src/core/schema.py	Modified	Add CCEvent dataclass (controller, time, value); add midi_cc: list[CCEvent] to ClipDef
scripts/compose.py	Modified	Add _get_kick_cache(), pass to build_bass_track(), generate CC11 events in bass clips
src/reaper_builder/__init__.py	Modified	_build_midi_source() interleaves CC events into E-line stream
src/composer/drum_analyzer.py	Unchanged	Already exports transient_positions("kick") — zero changes needed
tests/test_compose_integration.py	Modified	Verify CC events present in bass clips, correct CC11 values at kick positions
tests/test_reaper_builder.py	Modified	Verify _build_midi_source() emits B0 0B E-lines

Risks

Risk	Likelihood	Mitigation
Synth doesn't respond to CC11	Low	Serum 2, Omnisphere, Diva all support it. Add _CC11_VOLUME_MIN constant for easy disable (set to 127 = no ducking).
DrumloopAnalyzer misclassifies kick transients	Med	Only use transients with confidence > 0.6; add KICK_CONFIDENCE_THRESHOLD = 0.6 constant.
CC events overlap MIDI notes in E-line stream	Low	Sort all events (notes + CC) by absolute time; REAPER E-lines are monotonic delta-encoded.

Rollback Plan

Delete midi_cc from ClipDef and revert builder to skip CC events. Remove _get_kick_cache() from compose.py. No schema migrations needed — midi_cc defaults to empty list (zero behavioral change). One-commit revert.

Dependencies

• librosa (already a project dependency via drum_analyzer.py)
• DrumLoopAnalyzer (already implemented and tested)
• No new packages, no external APIs.

Success Criteria

• Bass MIDI clips contain CC11 (Expression) E-lines at kick hit positions
• CC11 value drops to ~50 at kick onset, recovers to 127 within 0.18 beats
• DrumLoopAnalyzer correctly identifies kick transients in all 5 drumloop variants
• Kick position cache avoids re-analyzing same WAV across sections
• 110 existing tests pass unchanged
• .rpp output opens in REAPER without errors; bass audibly ducks when kick hits
• validate_rpp_output() reports no regressions