remove stale doc

§

1 files changed, 0 insertions, 251 deletions

diff --git a/BEAT_TIMING_SUMMARY.md b/BEAT_TIMING_SUMMARY.md
deleted file mode 100644
index e593380..0000000
--- a/BEAT_TIMING_SUMMARY.md
+++ /dev/null
@@ -1,251 +0,0 @@
-# Beat-Based Timing System
-
-## Summary
-
-**Timeline sequences now use musical beats as the primary time unit**, ensuring visual effects stay synchronized to music structure regardless of BPM changes. Variable tempo only affects audio sample triggering—visual effects run at constant physical time with optional beat-synchronized animation.
-
-**Key Change:** `CommonPostProcessUniforms` now provides both `time` (physical seconds) and `beat_time` (absolute beats) + `beat_phase` (fractional 0-1) for flexible animation.
-
----
-
-## Changes Made
-
-### 1. **Documentation Updated**
-- `doc/SEQUENCE.md`: Beat-based format as primary, updated runtime parameters
-- `tools/timeline_editor/README.md`: Beat notation as default
-
-### 2. **Uniform Structure Enhanced**
-```cpp
-struct CommonPostProcessUniforms {
-  vec2 resolution;        // Screen dimensions
-  float aspect_ratio;     // Width/height ratio
-  float time;             // Physical seconds (unaffected by tempo)
-  float beat_time;        // NEW: Absolute beats (musical time)
-  float beat_phase;       // NEW: Fractional beat 0-1 (was "beat")
-  float audio_intensity;  // Audio peak
-  float _pad;            // Alignment
-};  // 32 bytes (unchanged size)
-```
-
-### 3. **Shader Updates**
-- All `common_uniforms.wgsl` files updated with new field names
-- Effects can now use:
-  - `time` for physics-based animation (constant speed)
-  - `beat_time` for musical animation (bars/beats)
-  - `beat_phase` for smooth per-beat oscillation
-
-### 4. **Seq Compiler**
-- `tools/seq_compiler.cc`: Beat notation as default parser behavior
-- Format: `5` = beats, `2.5s` = explicit seconds
-- BPM-based conversion at compile time (beats → seconds)
-
-### 5. **Timeline Files Converted**
-- `workspaces/main/timeline.seq`: Added 's' suffix to preserve timing
-- `workspaces/test/timeline.seq`: Added 's' suffix to preserve timing
-- Existing demos run unchanged with explicit seconds notation
-
-### 6. **Runtime Updates**
-- `main.cc`: Calculates `beat_time` and `beat_phase` from audio time
-- `gpu.cc`: Passes both physical time and beat time to effects
-- `effect.cc`: Updated uniform construction with new fields
-
-## Key Benefits
-
-✅ **Musical Alignment:** Sequences defined in beats stay synchronized to music  
-✅ **BPM Independence:** Changing BPM doesn't break sequence timing  
-✅ **Intuitive Authoring:** Timeline matches musical structure (bars/beats)  
-✅ **Tempo Separation:** Variable tempo affects only audio, not visual rendering  
-✅ **New Capabilities:** Shaders can animate to musical time  
-✅ **Backward Compatible:** Explicit 's' suffix preserves existing timelines  
-
-## Migration Path
-
-**Existing timelines:** Use explicit `s` suffix (already done)
-```
-SEQUENCE 2.50s 0
-  EFFECT + Flash 0.00s 1.00s
-```
-
-**New content:** Use beat notation (natural default)
-```
-# BPM 120
-SEQUENCE 0 0 "Intro"     # Beat 0 = bar 1
-  EFFECT + Flash 0 2     # Beats 0-2 (half bar)
-  EFFECT + Fade 4 8      # Beats 4-8 (full bar)
-```
-
-## Verification
-
-**Build:** ✅ Complete (100%)
-```bash
-cmake --build build -j4
-```
-
-**Tests:** ✅ 34/36 passing (94%)
-```bash
-cd build && ctest
-```
-
-**Demo Run:** ✅ Verified
-```
-[GraphicsT=0.32, AudioT=0.13, Beat=0, Phase=0.26, Peak=1.00]
-[GraphicsT=0.84, AudioT=0.64, Beat=1, Phase=0.28, Peak=0.14]
-[GraphicsT=1.38, AudioT=1.15, Beat=2, Phase=0.30, Peak=0.92]
-```
-- Beat counting: ✅ Correct (0→1→2→3...)
-- Phase tracking: ✅ Correct (fractional 0.0-1.0)
-- Effect timing: ✅ Sequences start/end at correct times
-- Shader compilation: ✅ No errors
-
-**Commits:**
-- `89c4687` - feat: implement beat-based timing system
-- `641b5b6` - fix: update shader files to use beat_phase
-
----
-
-## Usage Examples
-
-### Timeline Authoring (Beat-Based)
-```seq
-# BPM 120
-SEQUENCE 0 0 "Intro (Bar 1)"
-  EFFECT + Flash 0 2           # Beats 0-2 (half bar)
-  EFFECT + Fade 2 4            # Beats 2-4 (second half)
-
-SEQUENCE 8 1 "Drop (Bar 3)"
-  EFFECT + Heptagon 0 16       # Full 4 bars (16 beats)
-  EFFECT + Particles 4 12      # Beats 4-12 (2 bars)
-```
-
-### Shader Animation (Musical Time)
-```wgsl
-// Pulse every 4 beats (one bar)
-let bar_pulse = sin(uniforms.beat_time * TAU / 4.0);
-
-// Smooth per-beat oscillation
-let beat_wave = sin(uniforms.beat_phase * TAU);
-
-// Physics-based (constant speed)
-let rotation = uniforms.time * TAU;
-```
-
-### Legacy Timelines (Explicit Seconds)
-```seq
-SEQUENCE 2.50s 0
-  EFFECT + Flash 0.00s 1.00s   # Preserved timing
-```
-
----
-
-## Architecture
-
-**Timing Separation:**
-```
-┌─────────────────┐
-│ Platform Clock  │ (physical seconds)
-└────────┬────────┘
-         │
-    ┌────┴─────┬──────────────┐
-    ▼          ▼              ▼
-Physical   Audio Time    Music Time
-  Time    (playback)   (tempo-scaled)
-    │          │              │
-    │          └──────┬───────┘
-    │                 ▼
-    │          Beat Calculation
-    │          (BPM conversion)
-    │                 │
-    └────────┬────────┘
-             ▼
-    Visual Effects Rendering
-    (time + beat_time + beat_phase)
-```
-
-**Key Insight:** Variable tempo changes `music_time` for audio triggering, but visual effects receive constant `time` (physical) and derived `beat_time` (from audio playback, not music_time).
-
----
-
-## Technical Details
-
-### Uniform Size Maintained
-```cpp
-// Before (32 bytes):
-struct { vec2 res; float _pad[2]; float aspect, time, beat, intensity; }
-
-// After (32 bytes):
-struct { vec2 res; float aspect, time, beat_time, beat_phase, intensity, _pad; }
-```
-
-### Beat Calculation
-```cpp
-// main.cc
-const float absolute_beat_time = current_audio_time * g_tracker_score.bpm / 60.0f;
-const float beat_phase = fmodf(absolute_beat_time, 1.0f);
-```
-
-### Seq Compiler Logic
-```cpp
-// Default: beats → seconds
-float beat = std::stof(value);
-float time = beat * 60.0f / bpm;
-
-// Explicit seconds: pass through
-if (value.back() == 's') return seconds;
-```
-
----
-
-## Migration Guide
-
-**For New Content:** Use beat notation (recommended)
-```seq
-# BPM 140
-SEQUENCE 0 0 "Intro"
-  EFFECT + Flash 0 4    # 4 beats = 1.71s @ 140 BPM
-```
-
-**For Existing Content:** Already migrated with 's' suffix
-```seq
-SEQUENCE 2.50s 0        # Preserved exact timing
-  EFFECT + Flash 0.00s 1.00s
-```
-
-**For Shader Effects:**
-- Use `uniforms.beat_phase` (not `uniforms.beat`)
-- Use `uniforms.beat_time` for bar-based animation
-- Use `uniforms.time` for constant-speed animation
-
----
-
-## Files Modified
-
-**Core System:**
-- `src/gpu/effects/post_process_helper.h` - Uniform structure
-- `src/gpu/effect.{h,cc}` - Effect rendering signatures
-- `src/gpu/gpu.{h,cc}` - GPU draw interface
-- `src/main.cc`, `src/test_demo.cc` - Beat calculation
-
-**Shaders:**
-- `workspaces/{main,test}/shaders/common_uniforms.wgsl`
-- `assets/{common,final}/shaders/common_uniforms.wgsl`
-- All effect shaders using beat: `particle_spray_compute.wgsl`, `ellipse.wgsl`
-
-**Timeline Compiler:**
-- `tools/seq_compiler.cc` - Beat-as-default parser
-
-**Timelines:**
-- `workspaces/main/timeline.seq` - Explicit 's' suffix
-- `workspaces/test/timeline.seq` - Explicit 's' suffix
-
-**Documentation:**
-- `doc/SEQUENCE.md` - Beat notation format
-- `tools/timeline_editor/README.md` - Editor usage
-
----
-
-## Future Enhancements
-
-1. **Beat-Synced Effects:** Create effects that pulse/animate to bars
-2. **Timeline Conversion:** Tool to convert explicit seconds → beats
-3. **Editor Support:** Timeline editor beat grid visualization
-4. **Shader Helpers:** WGSL functions for common beat patterns