From 726ae79dd3ba8f368d3a671f371e747c33195edd Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sat, 7 Feb 2026 19:22:43 +0100
Subject: refactor(audio): Convert tracker to unit-less timing system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Changes tracker timing from beat-based to unit-less system to separate
musical structure from BPM-dependent playback speed.

TIMING CONVENTION:
- 1 unit = 4 beats (by convention)
- Conversion: seconds = units * (4 / BPM) * 60
- At 120 BPM: 1 unit = 2 seconds

BENEFITS:
- Pattern structure independent of BPM
- BPM changes only affect playback speed, not structure
- Easier pattern composition (0.00-1.00 for typical 4-beat pattern)
- Fixes issue where patterns played for 2s instead of expected duration

DATA STRUCTURES (tracker.h):
- TrackerEvent.beat → TrackerEvent.unit_time
- TrackerPattern.num_beats → TrackerPattern.unit_length
- TrackerPatternTrigger.time_sec → TrackerPatternTrigger.unit_time

RUNTIME (tracker.cc):
- Added BEATS_PER_UNIT constant (4.0)
- Convert units to seconds at playback time using BPM
- Pattern remains active for full unit_length duration
- Fixed premature pattern deactivation bug

COMPILER (tracker_compiler.cc):
- Parse LENGTH parameter from PATTERN lines (defaults to 1.0)
- Parse unit_time instead of beat values
- Generate code with unit-less timing

ASSETS:
- test_demo.track: converted to unit-less (8 score triggers)
- music.track: converted to unit-less (all patterns)
- Events: beat/4 conversion (e.g., beat 2.0 → unit 0.50)
- Score: seconds/unit_duration (e.g., 4s → 2.0 units at 120 BPM)

VISUALIZER (track_visualizer/index.html):
- Parse LENGTH parameter and BPM directive
- Convert unit-less time to seconds for rendering
- Update tick positioning to use unit_time
- Display correct pattern durations

DOCUMENTATION (doc/TRACKER.md):
- Added complete .track format specification
- Timing conversion reference table
- Examples with unit-less timing
- Pattern LENGTH parameter documentation

FILES MODIFIED:
- src/audio/tracker.{h,cc} (data structures + runtime conversion)
- tools/tracker_compiler.cc (parser + code generation)
- assets/{test_demo,music}.track (converted to unit-less)
- tools/track_visualizer/index.html (BPM-aware rendering)
- doc/TRACKER.md (format documentation)
- convert_track.py (conversion utility script)

TEST RESULTS:
- test_demo builds and runs correctly
- demo64k builds successfully
- Generated code verified (unit-less values in music_data.cc)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 src/generated/test_demo_music.cc | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

(limited to 'src/generated/test_demo_music.cc')

diff --git a/src/generated/test_demo_music.cc b/src/generated/test_demo_music.cc
index 9e04741..f77984e 100644
--- a/src/generated/test_demo_music.cc
+++ b/src/generated/test_demo_music.cc
@@ -20,36 +20,40 @@ const AssetId g_tracker_sample_assets[] = {
 };
 
 static const TrackerEvent PATTERN_EVENTS_drums_basic[] = {
-    { 0.0f, 0, 1.0f, 0.0f },
-    { 0.0f, 3, 0.5f, 0.0f },
-    { 1.0f, 1, 0.9f, 0.0f },
-    { 2.0f, 0, 1.0f, 0.0f },
-    { 3.0f, 1, 0.9f, 0.0f },
+    { 0.00f, 0, 1.0f, 0.0f },
+    { 0.00f, 3, 0.5f, 0.0f },
+    { 0.25f, 1, 0.9f, 0.0f },
+    { 0.50f, 0, 1.0f, 0.0f },
+    { 0.75f, 1, 0.9f, 0.0f },
 };
 static const TrackerEvent PATTERN_EVENTS_drums_with_crash[] = {
-    { 0.0f, 0, 1.0f, 0.0f },
-    { 0.0f, 2, 0.9f, 0.0f },
-    { 0.0f, 3, 0.5f, 0.0f },
-    { 1.0f, 1, 0.9f, 0.0f },
-    { 2.0f, 0, 1.0f, 0.0f },
-    { 3.0f, 1, 0.9f, 0.0f },
+    { 0.00f, 0, 1.0f, 0.0f },
+    { 0.00f, 2, 0.9f, 0.0f },
+    { 0.00f, 3, 0.5f, 0.0f },
+    { 0.25f, 1, 0.9f, 0.0f },
+    { 0.50f, 0, 1.0f, 0.0f },
+    { 0.75f, 1, 0.9f, 0.0f },
 };
 
 const TrackerPattern g_tracker_patterns[] = {
-    { PATTERN_EVENTS_drums_basic, 5, 4.0f }, // drums_basic
-    { PATTERN_EVENTS_drums_with_crash, 6, 4.0f }, // drums_with_crash
+    { PATTERN_EVENTS_drums_basic, 5, 1.00f }, // drums_basic
+    { PATTERN_EVENTS_drums_with_crash, 6, 1.00f }, // drums_with_crash
 };
 const uint32_t g_tracker_patterns_count = 2;
 
 static const TrackerPatternTrigger SCORE_TRIGGERS[] = {
     { 0.0f, 0 },
-    { 4.0f, 1 },
-    { 8.0f, 0 },
-    { 12.0f, 1 },
+    { 1.0f, 0 },
+    { 2.0f, 1 },
+    { 3.0f, 0 },
+    { 4.0f, 0 },
+    { 5.0f, 0 },
+    { 6.0f, 1 },
+    { 7.0f, 0 },
 };
 
 const TrackerScore g_tracker_score = {
-    SCORE_TRIGGERS, 4, 120.0f
+    SCORE_TRIGGERS, 8, 120.0f
 };
 
 // ============================================================
-- 
cgit v1.2.3