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>
---
 doc/TRACKER.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

(limited to 'doc')

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