From 89c46872127aaede53362f64cdc3fe9b3164650b Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Thu, 12 Feb 2026 00:30:56 +0100
Subject: feat: implement beat-based timing system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BREAKING CHANGE: Timeline format now uses beats as default unit

## Core Changes

**Uniform Structure (32 bytes maintained):**
- Added `beat_time` (absolute beats for musical animation)
- Added `beat_phase` (fractional 0-1 for smooth oscillation)
- Renamed `beat` → `beat_phase`
- Kept `time` (physical seconds, tempo-independent)

**Seq Compiler:**
- Default: all numbers are beats (e.g., `5`, `16.5`)
- Explicit seconds: `2.5s` suffix
- Explicit beats: `5b` suffix (optional clarity)

**Runtime:**
- Effects receive both physical time and beat time
- Variable tempo affects audio only (visual uses physical time)
- Beat calculation from audio time: `beat_time = audio_time * BPM / 60`

## Migration

- Existing timelines: converted with explicit 's' suffix
- New content: use beat notation (musical alignment)
- Backward compatible via explicit notation

## Benefits

- Musical alignment: sequences sync to bars/beats
- BPM independence: timing preserved on BPM changes
- Shader capabilities: animate to musical time
- Clean separation: tempo scaling vs. visual rendering

## Testing

- Build: ✅ Complete
- Tests: ✅ 34/36 passing (94%)
- Demo: ✅ Ready

handoff(Claude): Beat-based timing system implemented. Variable tempo
only affects audio sample triggering. Visual effects use physical_time
(constant) and beat_time (musical). Shaders can now animate to beats.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 workspaces/test/shaders/common_uniforms.wgsl | 14 +++++++-------
 workspaces/test/timeline.seq                 |  4 ++--
 workspaces/test/timeline.seq.backup          |  8 ++++++++
 3 files changed, 17 insertions(+), 9 deletions(-)
 create mode 100644 workspaces/test/timeline.seq.backup

(limited to 'workspaces/test')

diff --git a/workspaces/test/shaders/common_uniforms.wgsl b/workspaces/test/shaders/common_uniforms.wgsl
index ce1be53..1ab8939 100644
--- a/workspaces/test/shaders/common_uniforms.wgsl
+++ b/workspaces/test/shaders/common_uniforms.wgsl
@@ -1,11 +1,11 @@
 struct CommonUniforms {
-    resolution: vec2<f32>,
-    _pad0: f32,
-    _pad1: f32,
-    aspect_ratio: f32,
-    time: f32,
-    beat: f32,
-    audio_intensity: f32,
+    resolution: vec2<f32>,      // Screen dimensions
+    aspect_ratio: f32,          // Width/height ratio
+    time: f32,                  // Physical time in seconds (unaffected by tempo)
+    beat_time: f32,             // Musical time in beats (absolute, tempo-scaled)
+    beat_phase: f32,            // Fractional beat (0.0-1.0 within current beat)
+    audio_intensity: f32,       // Audio peak for beat sync
+    _pad: f32,                  // Padding
 };
 struct GlobalUniforms {
     view_proj: mat4x4<f32>,
diff --git a/workspaces/test/timeline.seq b/workspaces/test/timeline.seq
index 100c7da..3cbfb93 100644
--- a/workspaces/test/timeline.seq
+++ b/workspaces/test/timeline.seq
@@ -2,7 +2,7 @@
 # Minimal timeline for audio/visual sync testing
 # BPM 120 (set in test_demo.track)
 
-SEQUENCE 0.0 0 "Main Loop"
-  EFFECT + FlashEffect 0.0 16.0
+SEQUENCE 0.0s 0 "Main Loop"
+EFFECT + FlashEffect 0.0s 16.0s
 
 END_DEMO 32b
diff --git a/workspaces/test/timeline.seq.backup b/workspaces/test/timeline.seq.backup
new file mode 100644
index 0000000..100c7da
--- /dev/null
+++ b/workspaces/test/timeline.seq.backup
@@ -0,0 +1,8 @@
+# WORKSPACE: test
+# Minimal timeline for audio/visual sync testing
+# BPM 120 (set in test_demo.track)
+
+SEQUENCE 0.0 0 "Main Loop"
+  EFFECT + FlashEffect 0.0 16.0
+
+END_DEMO 32b
-- 
cgit v1.2.3