# Tasks: `reggaeton-professional-mix`

## type: architecture
## status: draft

---

## Phase 1 — Note Validity (Foundation)

### 1.1 Clamp pitch in `encode_notes_block()`
**File**: `src/flp_builder/events.py`
**Location**: `encode_notes_block()`, lines 201–223
**Change**: Replace `key=key & 0x7F` with explicit `max(0, min(127, key))`.
**Why**: `key & 0x7F` silently wraps values ≥128 rather than clamping, causing the FL Studio "invalid notes" warning.
**Validation**: Verify notes with key=128 produce no warning; key=0 and key=127 work.

### 1.2 Clamp velocity in `encode_notes_block()`
**File**: `src/flp_builder/events.py`
**Location**: `encode_notes_block()`, line 219 — `velocity=velocity & 0x7F`
**Change**: Replace with `max(1, min(127, velocity))`.
**Why**: Velocity 0 is invalid in MIDI; `& 0x7F` allows 0 from input.
**Validation**: velocity=0 → clamped to 1; velocity=127 stays 127; velocity=200 → clamped to 127.

### 1.3 Clamp duration ≥ 1 in `encode_notes_block()`
**File**: `src/flp_builder/events.py`
**Location**: `encode_notes_block()`, line 212 — `length=max(length, 1)`
**Change**: Already present. Confirm `max(length, 1)` is retained (was added in prior fix).
**Why**: Duration of 0 would produce 0-byte notes, which FL Studio rejects.
**Validation**: length=0 → stays 1 after max(); length=1 → stays 1.

---

## Phase 2 — Mix Settings

### 2.1 Add mix fields to `PatternDef`
**File**: `src/flp_builder/schema.py`
**Location**: `PatternDef` dataclass, lines 72–87
**Change**: Add four fields to `PatternDef`:
```python
volume: float = 0.85        # 0.0–1.0, default -1.5 dB
pan: float = 0.0            # -1.0 to 1.0, center
reverb_send: float = 0.2    # 0.0–1.0
delay_send: float = 0.1      # 0.0–1.0
```
Add `volume`, `pan`, `reverb_send`, `delay_send` to `_PATTERN_KEYS` frozenset for validation.
**Why**: Needed so the composer can specify per-pattern mix settings; previously all channels used defaults.
**Validation**: JSON round-trip: `PatternDef(..., volume=0.8, pan=-0.3, reverb_send=0.4, delay_send=0.2)` survives `to_json()` → `from_json()`.

### 2.2 Patch mix events in `ChannelSkeletonLoader`
**File**: `src/flp_builder/skeleton.py`
**Location**: `ChannelSkeletonLoader.load()` — after sample patching, before assembly
**Change**: Accept `mix_map: dict[int, dict]` parameter (channel_index → {volume, pan, reverb_send, delay_send}). After patching samples, append/replace word events:
- `ChVolWord` (72): volume as 0–255 word (`int(vol * 200)`, 200 = 0 dB)
- `ChPanWord` (73): pan as signed 0–255 (`int((pan + 1.0) * 127.5)`)
- `ChReverb` (139): reverb_send as 0–255 (`int(send * 255)`)
- `ChStereoDelay` (85): delay_send as 0–255 (`int(send * 255)`)
**Why**: FL Studio stores these as word events on the channel; skeleton loader must inject them.
**Validation**: Load skeleton with mix_map, verify output bytes contain the four event IDs with expected values.

### 2.3 Pass mix_map from `FLPBuilder` to skeleton loader
**File**: `src/flp_builder/builder.py` (assumed existing — if not found, locate)
**Location**: `FLPBuilder.build()` call to `ChannelSkeletonLoader.load()`
**Change**: Build mix_map from `PatternDef` fields and pass to loader.
**Why**: Bridges schema (PatternDef) to FLP rendering (skeleton).
**Note**: If builder.py does not yet accept/forward mix_map, add it.

---

## Phase 3 — Groove

### 3.1 Add `groove_strength` to rhythm generators
**File**: `src/composer/rhythm.py`
**Location**: All generator functions + `get_notes()` dispatcher
**Change**: Add `groove_strength: float = 0.0` parameter (0.0 = no groove, 1.0 = max groove) to all generators:
- `kick_main_notes`, `kick_sparse_notes`, `kick_outro_notes`
- `snare_verse_notes`, `snare_fill_notes`, `snare_outro_notes`
- `hihat_16th_notes`, `hihat_8th_notes`
- `clap_24_notes`, `perc_combo_notes`, `rim_build_notes`

Apply groove via `_apply_groove(note_dict, groove_strength)` helper:
- Velocity jitter: `vel ±= random.randint(0, int(5 + groove_strength * 10))`
- Positional nudge: `pos += random.uniform(-groove_strength * 0.02, groove_strength * 0.02)`
- Swing (every other 16th): shift even-index 16ths forward by `swing_amount = groove_strength * 0.1`

**Why**: Groove makes drum patterns feel human and avoids mechanical timing.
**Validation**: `get_notes("kick_main_notes", bars=1, groove_strength=0.5)` returns notes with positional variation vs. `groove_strength=0.0`.

### 3.2 Update `get_notes()` dispatcher signature
**File**: `src/composer/rhythm.py`
**Location**: `get_notes()`, lines 303–311
**Change**: Add `groove_strength: float = 0.0` to dispatcher and pass to generator.
**Why**: All generators now accept groove_strength; dispatcher must forward it.

---

## Phase 4 — Melodic Humanization

### 4.1 Add `humanize` to melodic generators
**File**: `src/composer/melodic.py`
**Location**: `bass_tresillo()`, `lead_hook()`, `chords_block()`, `pad_sustain()`
**Change**: Add `humanize: float = 0.0` parameter (0.0 = no humanization, 1.0 = max humanization).

Apply humanization via `_apply_humanize(note_dict, humanize)` helper:
- Velocity jitter: `vel ±= random.randint(0, int(humanize * 5))` — gentler than drums
- Micro-timing: `pos += random.uniform(-humanize * 0.03, humanize * 0.03)` — tighter than drums

**Why**: Melodic instruments (bass, lead, pad) need subtler humanization than drums to avoid sounding out of tune.
**Validation**: `bass_tresillo(key="Am", bars=1, humanize=0.5)` vs. `humanize=0.0` shows velocity/position variance.

### 4.2 Add humanization to melodic dispatcher (if exists)
**File**: `src/composer/melodic.py`
**Location**: Any `get_melodic_notes()` dispatcher function
**Change**: Forward `humanize` parameter to all generators.
**Why**: Single entry point for melodic generation.

---

## Phase 5 — Transitions

### 5.1 Create FX channel (ch21) with riser sample
**File**: `scripts/compose_full_track.py`
**Location**: After melodic track setup, before `SongDefinition`
**Change**: Add FX channel (channel_index=21) with role `"fx"` and riser sample from `SampleSelector`. Use `rim_build_notes` pattern at channel 21 for riser fills. Place riser clips before chorus sections at bars 19 and 43 (1-bar riser items).
**Why**: Transitions between verse→chorus need riser FX to build energy.
**Note**: Verify ch21 is available (not used by drums/melodic); if conflicts, use next available.

### 5.2 Add rim_build pre-chorus fills
**File**: `scripts/compose_full_track.py`
**Location**: Arrangement items for bars 18–19 (pre-chorus 1) and 42–43 (pre-chorus 2)
**Change**: Insert 2-bar rim_build pattern before each chorus:
- Pattern id 9: `rim_build_notes` at channel 13
- Place at bars 18–19 for chorus 1 (bars 20–31)
- Place at bars 42–43 for chorus 2 (bars 44–55)
**Why**: Rim roll builds tension going into the chorus ("rim_build" generator is designed for this).

### 5.3 Place riser FX before choruses
**File**: `scripts/compose_full_track.py`
**Location**: Arrangement items, pre-chorus sections
**Change**: Add 1-bar riser clip at bars 19 and 43 (before chorus 1 and 2). Riser should be on a dedicated FX track (arrangement track 7).
**Why**: Riser sample creates sonic "lift" into the chorus section.

---

## Phase 6 — Compose Script Update

### 6.1 Add reggaeton-standard mix values to PatternDefs
**File**: `scripts/compose_full_track.py`
**Location**: `patterns` list, lines 128–137
**Change**: Set explicit mix values per pattern:
- `kick_main`: volume=0.88, pan=0.0, reverb_send=0.1, delay_send=0.0
- `kick_sparse`: volume=0.82, pan=0.0, reverb_send=0.1, delay_send=0.0
- `snare_main`: volume=0.80, pan=0.05, reverb_send=0.35, delay_send=0.15
- `hihat_main`: volume=0.65, pan=0.0, reverb_send=0.25, delay_send=0.0
- `clap_main`: volume=0.82, pan=0.0, reverb_send=0.45, delay_send=0.1
- `perc_main`: volume=0.72, pan=-0.15, reverb_send=0.3, delay_send=0.1
- `perc2_main`: volume=0.72, pan=0.15, reverb_send=0.3, delay_send=0.1

**Why**: These values are the reggaeton-standard mix targets documented in the design.

### 6.2 Enable `groove_strength` on drum patterns
**File**: `scripts/compose_full_track.py`
**Location**: `patterns` list — update call sites that generate drum notes
**Change**: Pass `groove_strength=0.3` to drum rhythm generators in compose script.
**Why**: Drums benefit from subtle groove humanization to avoid mechanical feel.
**Note**: This requires `get_notes()` to accept `groove_strength` (Phase 3 must be complete first).

### 6.3 Enable `humanize` on melodic tracks
**File**: `scripts/compose_full_track.py`
**Location**: `section_notes()` calls for bass, lead, pad, pluck
**Change**: Pass `humanize=0.2` to melodic generators.
**Why**: Melodic humanization makes bass/lead/pad feel organic and less quantized.

### 6.4 Add transition sections to arrangement
**File**: `scripts/compose_full_track.py`
**Location**: `items` list — insert pre-chorus transition blocks
**Change**: Insert pre-chorus sections at bars 18–19 and 42–43:
- Rim_build pattern at channel 13 (bars 18–19 and 42–43)
- Riser FX at channel 21 (bars 19 and 43, 1 bar each)
**Why**: Proper transitions create professional song flow rather than abrupt section changes.

---

## Dependencies

- Phase 2 depends on Phase 1 (schema fields needed before builder integration)
- Phase 3 can run in parallel with Phase 4 (separate modules)
- Phase 5 depends on Phase 2 (mix infrastructure for FX sends)
- Phase 6 depends on Phases 2, 3, 4, 5 (all capabilities wired up)

## Files Modified (summary)

| File | Phases |
|------|--------|
| `src/flp_builder/events.py` | 1 |
| `src/flp_builder/schema.py` | 2 |
| `src/flp_builder/skeleton.py` | 2 |
| `src/flp_builder/builder.py` | 2 |
| `src/composer/rhythm.py` | 3 |
| `src/composer/melodic.py` | 4 |
| `scripts/compose_full_track.py` | 5, 6 |