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>
---
 convert_track.py | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 convert_track.py

(limited to 'convert_track.py')

diff --git a/convert_track.py b/convert_track.py
new file mode 100644
index 0000000..ec9d62c
--- /dev/null
+++ b/convert_track.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Convert .track files from beat-based to unit-less timing."""
+
+import re
+import sys
+
+def convert_beat_to_unit(beat_str):
+    """Convert beat value to unit-less (beat / 4)."""
+    beat = float(beat_str)
+    unit = beat / 4.0
+    return f"{unit:.2f}"
+
+def process_line(line):
+    """Process a single line, converting beat values."""
+    line = line.rstrip('\n')
+
+    # Skip comments and empty lines
+    if not line.strip() or line.strip().startswith('#'):
+        return line
+
+    # PATTERN line - add LENGTH 1.0
+    if line.strip().startswith('PATTERN '):
+        # Check if LENGTH already exists
+        if ' LENGTH ' in line:
+            return line
+        parts = line.split()
+        if len(parts) >= 2:
+            return f"PATTERN {parts[1]} LENGTH 1.0"
+        return line
+
+    # Event line (starts with a number)
+    match = re.match(r'^(\s*)([0-9.]+),\s*(.+)$', line)
+    if match:
+        indent, beat_str, rest = match.groups()
+        unit_str = convert_beat_to_unit(beat_str)
+        return f"{indent}{unit_str}, {rest}"
+
+    return line
+
+def main():
+    if len(sys.argv) != 3:
+        print(f"Usage: {sys.argv[0]} <input.track> <output.track>")
+        sys.exit(1)
+
+    input_file = sys.argv[1]
+    output_file = sys.argv[2]
+
+    with open(input_file, 'r') as f:
+        lines = f.readlines()
+
+    # Add header comment about timing
+    output_lines = []
+    output_lines.append("# Enhanced Demo Track - Progressive buildup with varied percussion\n")
+    output_lines.append("# Features acceleration/deceleration with diverse samples and melodic progression\n")
+    output_lines.append("#\n")
+    output_lines.append("# TIMING: Unit-less (1 unit = 4 beats at 120 BPM = 2 seconds)\n")
+    output_lines.append("# Pattern events use unit-less time (0.0-1.0 for 4-beat pattern)\n")
+    output_lines.append("# Score triggers use unit-less time\n")
+
+    # Skip old header lines
+    start_idx = 0
+    for i, line in enumerate(lines):
+        if line.strip() and not line.strip().startswith('#'):
+            start_idx = i
+            break
+
+    # Process rest of file
+    for line in lines[start_idx:]:
+        output_lines.append(process_line(line) + '\n')
+
+    with open(output_file, 'w') as f:
+        f.writelines(output_lines)
+
+    print(f"Converted {input_file} -> {output_file}")
+
+if __name__ == '__main__':
+    main()
-- 
cgit v1.2.3