From 726ae79dd3ba8f368d3a671f371e747c33195edd Mon Sep 17 00:00:00 2001 From: skal 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 --- doc/TRACKER.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) (limited to 'doc') diff --git a/doc/TRACKER.md b/doc/TRACKER.md index cb14755..f3a34a3 100644 --- a/doc/TRACKER.md +++ b/doc/TRACKER.md @@ -40,4 +40,85 @@ This generated code can be mixed with fixed code from the demo codebase itself (explosion predefined at a given time ,etc.) The baking is done at compile time, and the code will go in src/generated/ +## .track File Format + +### Timing System + +**Unit-less Timing Convention:** +- All time values are **unit-less** (not beats or seconds) +- Convention: **1 unit = 4 beats** +- Conversion to seconds: `seconds = units * (4 / BPM) * 60` +- At 120 BPM: 1 unit = 2 seconds + +This makes patterns independent of BPM - changing BPM only affects playback speed, not pattern structure. + +### File Structure + +``` +# Comments start with # + +BPM # Optional, defaults to 120 BPM + +SAMPLE # Define sample (asset or generated note) + +PATTERN LENGTH # Define pattern with unit-less duration + , , , # Pattern events + +SCORE # Score section (pattern triggers) + , +``` + +### Examples + +#### Simple 4-beat pattern (1 unit): +``` +PATTERN kick_snare LENGTH 1.0 + 0.00, ASSET_KICK_1, 1.0, 0.0 # Start of pattern (beat 0) + 0.25, ASSET_SNARE_1, 0.9, 0.0 # 1/4 through (beat 1) + 0.50, ASSET_KICK_1, 1.0, 0.0 # 1/2 through (beat 2) + 0.75, ASSET_SNARE_1, 0.9, 0.0 # 3/4 through (beat 3) +``` + +#### Score triggers: +``` +SCORE + 0.0, kick_snare # Trigger at 0 seconds (120 BPM) + 1.0, kick_snare # Trigger at 2 seconds (1 unit = 2s at 120 BPM) + 2.0, kick_snare # Trigger at 4 seconds +``` + +#### Generated note: +``` +SAMPLE NOTE_C4 # Automatically generates C4 note (261.63 Hz) +PATTERN melody LENGTH 1.0 + 0.00, NOTE_C4, 0.8, 0.0 + 0.25, NOTE_E4, 0.7, 0.0 + 0.50, NOTE_G4, 0.8, 0.0 +``` + +### Conversion Reference + +At 120 BPM (1 unit = 4 beats = 2 seconds): + +| Units | Beats | Seconds | Description | +|-------|-------|---------|-------------| +| 0.00 | 0 | 0.0 | Start | +| 0.25 | 1 | 0.5 | Quarter | +| 0.50 | 2 | 1.0 | Half | +| 0.75 | 3 | 1.5 | Three-quarter | +| 1.00 | 4 | 2.0 | Full pattern | + +### Pattern Length + +- `LENGTH` parameter is optional, defaults to 1.0 +- Can be any value (0.5 for half-length, 2.0 for double-length, etc.) +- Events must be within range `[0.0, LENGTH]` + +Example of half-length pattern: +``` +PATTERN short_fill LENGTH 0.5 # 2 beats = 1 second at 120 BPM + 0.00, ASSET_HIHAT, 0.7, 0.0 + 0.50, ASSET_HIHAT, 0.6, 0.0 # 0.50 * 0.5 = 1 beat into the pattern +``` + -- cgit v1.2.3