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 --- tools/track_visualizer/index.html | 71 ++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 19 deletions(-) (limited to 'tools/track_visualizer/index.html') 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 -- cgit v1.2.3