From 89c46872127aaede53362f64cdc3fe9b3164650b Mon Sep 17 00:00:00 2001 From: skal 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 --- tools/timeline_editor/README.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'tools/timeline_editor/README.md') diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md index a76a5ed..4861a88 100644 --- a/tools/timeline_editor/README.md +++ b/tools/timeline_editor/README.md @@ -49,23 +49,25 @@ SEQUENCE ["optional_name"] [optional_end] - `=` = Keep same priority as previous - `-` = Decrement priority (background layers) -**Time Notation:** -- `0b`, `4b`, `64b` = Beats (converted using BPM) -- `0.0`, `2.0`, `32.0` = Seconds -- Integer without 'b': treated as beats -- Decimal point: treated as seconds +**Time Notation (Beat-Based):** +- **Default:** All numbers are beats (e.g., `4`, `16.5` = beats) +- `4b`, `16b` = Explicit beats (optional 'b' suffix for clarity) +- `2.0s`, `8.25s` = Explicit seconds (rare, for physical timing) -Example: +Example (Beat-Based): ``` # BPM 120 -SEQUENCE 0b 0 "Opening Scene" - EFFECT - FlashCubeEffect .2 3 # Background (priority -1) - EFFECT + FlashEffect 0.0 1.0 # Foreground (priority 0) - EFFECT + FadeEffect 0.5 2.0 # Overlay (priority 1) - -SEQUENCE 4b 1 "Beat Drop" - EFFECT + HeptagonEffect 0.0 0.5 # Priority 0 - EFFECT = ParticlesEffect 0.0 2.0 # Priority 0 (same layer) +SEQUENCE 0 0 "Opening Scene" # Start at beat 0 + EFFECT - FlashCubeEffect 0 4 # Beats 0-4 (0-2s @ 120 BPM) + EFFECT + FlashEffect 0 2 # Beats 0-2 (0-1s) + EFFECT + FadeEffect 1 4 # Beats 1-4 (0.5-2s) + +SEQUENCE 8 1 "Beat Drop" # Start at beat 8 (bar 3) + EFFECT + HeptagonEffect 0 1 # First beat of sequence + EFFECT = ParticlesEffect 0 4 # Full bar (4 beats) + +SEQUENCE 2.5s 0 "Explicit seconds" # Rare: start at 2.5 physical seconds + EFFECT + Fade 0 4 # Still uses beats for duration ``` ## Technical Notes -- cgit v1.2.3