From 493bb2125d1f51c0d56b0f87638a3ec23b8afd3d Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Fri, 13 Feb 2026 13:46:24 +0100
Subject: Doc: Add tracker humanization and sample offset features

Specifies sample offset (shift trigger left) and humanization (per-note timing/volume variation) for realistic playback.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 TODO.md        | 19 ++++++++++++++++++-
 doc/TRACKER.md | 28 ++++++++++++++++++++++++----
 2 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/TODO.md b/TODO.md
index 3734ec6..072efe2 100644
--- a/TODO.md
+++ b/TODO.md
@@ -46,7 +46,24 @@ Enhanced CNN post-processing with multi-dimensional feature inputs.
 
 ---
 
-## Priority 3: 3D System Enhancements (Task #18)
+## Priority 3: Tracker Humanization & Sample Offset
+
+Enhance tracker with sample offset and humanization for realistic playback.
+
+**Features:**
+1. **Sample Offset:** Intrinsic offset value per sample (shifts trigger left, preserves beat sync)
+   - Add `offset_sec` to `NoteParams` (gen.h) and `Sample` struct
+   - Extend `.track` SAMPLE syntax: `SAMPLE <name> [OFFSET <sec>] [VOL <vol>]`
+   - Apply negative `start_offset_samples` in `trigger_note_event()`
+
+2. **Humanization:** Per-note random timing/volume variation (baked into WAV export)
+   - Add to `TrackerScore`: `humanize_seed`, `timing_variation_pct`, `volume_variation_pct`
+   - `.track` syntax: `HUMANIZE SEED <int> TIMING <pct> VOLUME <pct>`
+   - Apply per-event RNG modulation in `tracker_update()`
+
+---
+
+## Priority 4: 3D System Enhancements (Task #18)
 
 Pipeline for importing complex 3D scenes to replace hardcoded geometry.
 
diff --git a/doc/TRACKER.md b/doc/TRACKER.md
index 48829c0..5cb59de 100644
--- a/doc/TRACKER.md
+++ b/doc/TRACKER.md
@@ -20,11 +20,13 @@ Patterns are BPM-independent. Changing BPM only affects playback speed.
 
 BPM <tempo>              # Optional, defaults to 120 BPM
 
-SAMPLE <name>            # Define sample (asset or generated note)
+SAMPLE <name> [OFFSET <sec>] [VOL <volume>]  # Define sample with optional offset/volume
 
 PATTERN <name> LENGTH <duration>   # Define pattern with unit-less duration
   <unit_time>, <sample>, <volume>, <pan>   # Pattern events
 
+HUMANIZE SEED <int> TIMING <pct> VOLUME <pct>  # Optional humanization params
+
 SCORE                    # Score section (pattern triggers)
   <unit_time>, <pattern_name>
 ```
@@ -70,10 +72,28 @@ PATTERN short_fill LENGTH 0.5   # 2 beats = 1 second at 120 BPM
   0.50, ASSET_HIHAT, 0.6, 0.0   # 0.50 * 0.5 = 1 beat into the pattern
 ```
 
-### Future: Modifiers
+### Sample Offset
+
+Samples can specify an intrinsic offset (time-shift left):
+```
+SAMPLE ASSET_KICK_1 OFFSET 0.05 VOL 1.2
+```
+
+- **OFFSET**: Seconds to shift trigger earlier (preserves beat sync)
+- **VOL**: Default volume multiplier for this sample
+
+### Humanization
+
+Add per-note timing/volume variation for realistic playback:
+```
+HUMANIZE SEED 42 TIMING 2.0 VOLUME 5.0
+```
+
+- **SEED**: Random seed for reproducibility
+- **TIMING**: Timing variation (% of beat duration)
+- **VOLUME**: Volume variation (% of event volume)
 
-Potential runtime modifiers (not yet implemented):
-- Randomization, accents, volume modulation, distortion, noise, effects
+Applied per-note, baked into WAV export.
 
 ---
 
-- 
cgit v1.2.3