refactor(audio): Convert tracker to unit-less timing system

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>

1 files changed, 52 insertions, 19 deletions

diff --git a/tools/track_visualizer/index.html b/tools/track_visualizer/index.html
index 70a5fd8..4a613ec 100644
--- a/tools/track_visualizer/index.html
+++ b/tools/track_visualizer/index.html
@@ -161,7 +161,9 @@
       const patterns = {};
       const score = [];
       let currentPattern = null;
+      let currentPatternLength = 1.0; // Default: 1 unit
       let inScore = false;
+      let bpm = 120.0; // Default BPM
 
       for (let line of lines) {
         line = line.trim();
@@ -169,10 +171,28 @@
         // Skip comments and empty lines
         if (line.startsWith('#') || line.length === 0) continue;
 
-        // Pattern definition
+        // BPM directive
+        if (line.startsWith('BPM ')) {
+          bpm = parseFloat(line.substring(4).trim());
+          continue;
+        }
+
+        // Pattern definition with optional LENGTH
         if (line.startsWith('PATTERN ')) {
-          currentPattern = line.substring(8).trim();
-          patterns[currentPattern] = [];
+          const tokens = line.substring(8).trim().split(/\s+/);
+          currentPattern = tokens[0];
+          currentPatternLength = 1.0; // Default
+
+          // Check for LENGTH parameter
+          const lengthIdx = tokens.indexOf('LENGTH');
+          if (lengthIdx !== -1 && lengthIdx + 1 < tokens.length) {
+            currentPatternLength = parseFloat(tokens[lengthIdx + 1]);
+          }
+
+          patterns[currentPattern] = {
+            events: [],
+            unitLength: currentPatternLength
+          };
           inScore = false;
           continue;
         }
@@ -184,12 +204,12 @@
           continue;
         }
 
-        // Pattern events (beat, sample, volume, pan)
+        // Pattern events (unit_time, sample, volume, pan)
         if (currentPattern && !inScore) {
           const parts = line.split(',').map(s => s.trim());
           if (parts.length >= 2) {
-            patterns[currentPattern].push({
-              beat: parseFloat(parts[0]),
+            patterns[currentPattern].events.push({
+              unitTime: parseFloat(parts[0]),
               sample: parts[1],
               volume: parts.length > 2 ? parseFloat(parts[2]) : 1.0,
               pan: parts.length > 3 ? parseFloat(parts[3]) : 0.0
@@ -197,36 +217,44 @@
           }
         }
 
-        // Score entries (time, pattern_name)
+        // Score entries (unit_time, pattern_name)
         if (inScore) {
           const parts = line.split(',').map(s => s.trim());
           if (parts.length >= 2) {
             score.push({
-              time: parseFloat(parts[0]),
+              unitTime: parseFloat(parts[0]),
               pattern: parts[1]
             });
           }
         }
       }
 
-      return { patterns, score };
+      return { patterns, score, bpm };
+    }
+
+    // Convert unit-less time to seconds
+    // 1 unit = 4 beats, at given BPM
+    function unitsToSeconds(units, bpm) {
+      const BEATS_PER_UNIT = 4.0;
+      const unitDurationSec = (BEATS_PER_UNIT / bpm) * 60.0;
+      return units * unitDurationSec;
     }
 
-    // Calculate pattern duration (max beat time)
-    function getPatternDuration(pattern) {
-      if (pattern.length === 0) return 4.0; // Default 4 beats
-      return Math.max(...pattern.map(e => e.beat)) + 1.0;
+    // Get pattern duration in seconds
+    function getPatternDuration(pattern, bpm) {
+      if (!pattern || !pattern.unitLength) return unitsToSeconds(1.0, bpm);
+      return unitsToSeconds(pattern.unitLength, bpm);
     }
 
     // Draw timeline
     function drawTimeline() {
       if (!trackData) return;
 
-      const { patterns, score } = trackData;
+      const { patterns, score, bpm } = trackData;
 
       // Find max time for canvas sizing
       const maxTime = score.length > 0
-        ? Math.max(...score.map(s => s.time + getPatternDuration(patterns[s.pattern] || [])))
+        ? Math.max(...score.map(s => unitsToSeconds(s.unitTime, bpm) + getPatternDuration(patterns[s.pattern], bpm)))
         : 60;
 
       // Update canvas size
@@ -246,8 +274,8 @@
       // Group score entries by time for stacking
       const stackedPatterns = [];
       for (const entry of score) {
-        const startTime = entry.time;
-        const duration = getPatternDuration(patterns[entry.pattern] || []);
+        const startTime = unitsToSeconds(entry.unitTime, bpm);
+        const duration = getPatternDuration(patterns[entry.pattern], bpm);
         const endTime = startTime + duration;
 
         // Find stack level (avoid overlaps)
@@ -261,13 +289,15 @@
           stackLevel++;
         }
 
+        const pattern = patterns[entry.pattern];
         stackedPatterns.push({
           patternName: entry.pattern,
           startTime,
           endTime,
           duration,
           stackLevel,
-          events: patterns[entry.pattern] || []
+          unitLength: pattern ? pattern.unitLength : 1.0,
+          events: pattern ? pattern.events : []
         });
       }
 
@@ -385,7 +415,10 @@
       ctx.strokeStyle = '#ffffff';
       ctx.lineWidth = 2;
       for (const event of item.events) {
-        const tickX = x + event.beat * (PIXELS_PER_SECOND * zoomLevel) / beatsPerSecond;
+        // Convert unit_time to position within pattern
+        // event.unitTime ranges from 0 to item.unitLength
+        // width represents the full pattern duration
+        const tickX = x + (event.unitTime / item.unitLength) * width;
         const tickY = y + height - TICK_HEIGHT * verticalZoom;
 
         // Vertical tick mark