diff options
Diffstat (limited to 'tools/timeline_editor/README.md')
| -rw-r--r-- | tools/timeline_editor/README.md | 208 |
1 files changed, 53 insertions, 155 deletions
diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md index 82a743f..1f1539d 100644 --- a/tools/timeline_editor/README.md +++ b/tools/timeline_editor/README.md @@ -1,183 +1,81 @@ # Timeline Editor -Interactive web-based editor for `timeline.seq` files. +Interactive web-based editor for `timeline.seq` files with Sequence V2 format support. -## Features +## Quick Start -- 📂 Load/save `timeline.seq` files (Sequence V2 format) -- 📊 Visual timeline with sticky time markers (beat-based) -- 🎯 Drag & drop sequences and effects -- 🎯 Resize effects with handles -- 📦 Collapsible sequences (double-click to collapse) -- 📏 Vertical grid lines synchronized with time ticks -- ⏱️ Edit timing and properties (in beats) -- ⚙️ Stack-order based priority system -- 🔍 Zoom (10%-200%) with mouse wheel + Ctrl/Cmd -- 🎵 Audio waveform visualization (aligned to beats) -- 🎼 Quantize grid (Off, 1/32, 1/16, 1/8, 1/4, 1/2, 1 beat) -- 🎛️ BPM slider (60-200 BPM) -- 🔄 Re-order sequences by time -- ✨ Add effects to sequences -- 🗑️ Delete sequences/effects (toolbar + properties panel) -- 📊 **CPU load visualization** (color-coded effect density) -- ▶️ Audio playback with auto-expand/collapse -- 🎚️ Sticky audio track and timeline ticks -- 🔴 **Playback indicator on waveform** -- 🎯 **Double-click seek during playback** -- 📍 **Click waveform to seek** -- 🔗 **NODE declarations with typed buffers** (NEW) -- 🔀 **Buffer chain visualization** (NEW) -- ✅ **Validation for undeclared nodes** (NEW) +```bash +cd tools/timeline_editor +python3 -m http.server 8080 +# Open http://localhost:8080 +``` -## CPU Load Visualization +Or with auto-load: `index.html?seq=../../workspaces/main/timeline.seq&wav=audio.wav` -The editor displays a **CPU load bar** at the top (underneath audio waveform if loaded): -- **Full-height bars** (80px) show effect density at each time point -- **Color-coded:** Green (low) → Yellow (medium) → Red (high load) -- **Load calculation:** Sum of all active effects across all sequences (1.0 per effect) -- **Updates automatically** when effects/sequences are moved -- **Collapsed sequences count** toward load +## Features -This helps identify performance hotspots in your timeline. +**Editing:** +- Drag/drop sequences and effects, resize with handles +- Add/delete sequences and effects +- Edit NODE declarations (typed buffers: u8x4_norm, f32x4, f16x8, depth24, compute_f32) +- Edit effect routing: inputs/outputs with buffer chain visualization +- Properties panel with validation for undeclared nodes +- Collapsible sequences (double-click), re-order by time -## Usage +**Timeline:** +- Beat-based timing with BPM slider (60-200) +- Quantize grid (Off, 1/32-1 beat), snap-to-grid with hotkeys 0-6 +- Zoom 10%-200% (Ctrl/Cmd + wheel) +- CPU load visualization (effect density) +- Show beats/seconds toggle -1. **Open:** Requires HTTP server (ES6 modules): - ```bash - cd tools/timeline_editor - python3 -m http.server 8080 - ``` - Then open: `http://localhost:8080` -2. **Load timeline:** Click "📂 Load timeline.seq" → select `workspaces/main/timeline.seq` -3. **Load audio:** Click "🎵 Load Audio (WAV)" → select audio file -4. **Auto-load via URL:** `index.html?seq=timeline.seq&wav=audio.wav` -4. **Playback:** - - Click "▶ Play" or press **Spacebar** to play/pause - - Click waveform to seek to position - - **Double-click timeline** to seek during playback (continues playing) - - Watch sequences auto-expand/collapse during playback - - Red playback indicators on both timeline and waveform show current position -5. **Edit:** - - **Add Effect:** Select sequence, click "✨ Add Effect" button - - **Add Node:** Select sequence, properties panel → "Nodes" section → "+ Add Node" - - **Edit Effect Routing:** Select effect → edit "Inputs" and "Outputs" fields (space-separated) - - **Delete:** Click item, use "🗑️ Delete Selected" or delete button in properties panel - - Drag sequences/effects to reposition (works when collapsed or expanded) - - Double-click anywhere on sequence to collapse/expand - - Click item to edit properties in side panel - - Drag effect handles to resize - - **Quantize:** Use dropdown or hotkeys (0-6) to snap to grid -6. **Zoom:** Ctrl/Cmd + mouse wheel (zooms at cursor position) -7. **Save:** Click "💾 Save timeline.seq" (validates node references before saving) +**Audio:** +- WAV playback with waveform visualization +- Seek by clicking waveform or double-clicking timeline +- Auto-expand/collapse sequences during playback +- Dual playback indicators (timeline + waveform) -## File Format +**Shortcuts:** +- **Spacebar**: Play/pause +- **0-6**: Quantize (0=Off, 1=1beat, etc.) +- **Ctrl/Cmd + Wheel**: Zoom -⚠️ **For complete format specification, see:** `doc/SEQUENCE.md` +## File Format (V2) -The editor parses and generates **Sequence V2 format** `.seq` files: +⚠️ **Complete spec:** `doc/SEQUENCE.md` ``` # BPM 120 -SEQUENCE <start_time> <priority> ["optional_name"] - NODE <name> <type> # Optional explicit node declarations - EFFECT <+|=|-> <ClassName> <inputs...> -> <outputs...> <start> <end> [params...] +SEQUENCE <start_time> <priority> ["name"] + NODE <name> <type> # Optional: u8x4_norm|f32x4|f16x8|depth24|compute_f32 + EFFECT <+|=|-> <Class> <in...> -> <out...> <start> <end> [params] ``` -**Node Types:** -- `u8x4_norm` - RGBA8 standard texture (default framebuffer format) -- `f32x4` - RGBA float32 texture (HDR rendering) -- `f16x8` - 8-channel float16 (G-buffer for hybrid 3D) -- `depth24` - Depth buffer (3D rendering) -- `compute_f32` - Storage buffer (compute shaders) - -**Reserved Nodes:** -- `source` - Input framebuffer (implicit, always available) -- `sink` - Output framebuffer (implicit, always available) - -**Priority Modifiers:** -- `+` = Increment priority (normal effects) -- `=` = Keep same priority as previous -- `-` = Decrement priority (background layers) +**Reserved nodes:** `source` (input), `sink` (output) +**Priority:** `+` increment, `=` same, `-` decrement +**Time:** Beats by default, `4b` explicit beats, `2.0s` 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 (V2 Format with NODE declarations):** +**Example:** ``` -# BPM 120 -SEQUENCE 0.0 0 "Opening Scene" - NODE temp1 u8x4_norm # Declare intermediate buffer - NODE depth depth24 # Declare depth buffer +SEQUENCE 0.0 0 "Scene" + NODE temp1 u8x4_norm + NODE depth depth24 EFFECT + Hybrid3D source depth -> temp1 0.0 4.0 - EFFECT + GaussianBlur temp1 -> sink 0.0 4.0 - -SEQUENCE 4.0 0 "Beat Drop" - NODE glow f32x4 # HDR buffer for glow - EFFECT + Heptagon source -> glow 0.0 4.0 - EFFECT + Bloom glow -> sink 0.0 4.0 + EFFECT + Blur temp1 -> sink 0.0 4.0 ``` -**Example (V2 Format with auto-inferred nodes):** +**Auto-inferred nodes** (no NODE declarations needed): ``` -# BPM 120 -SEQUENCE 0.0 0 "Simple Chain" - # No NODE declarations - temp1 is auto-inferred - EFFECT + Blur source -> temp1 0.0 4.0 +SEQUENCE 0.0 0 + EFFECT + Blur source -> temp1 0.0 4.0 # temp1 auto-inferred EFFECT + Flash temp1 -> sink 0.0 4.0 ``` -**Buffer Chain Visualization:** - -The editor displays buffer routing for each effect: -- Property panel: `source, depth → [Hybrid3D] → temp1` -- Effect tooltip: Shows full buffer chain on hover - -## URL Parameters - -Auto-load files on page load: -``` -index.html?seq=../../workspaces/main/timeline.seq&wav=../../audio/track.wav -``` - -**Parameters:** -- `seq` - Path to `.seq` file (relative or absolute URL) -- `wav` - Path to `.wav` audio file (relative or absolute URL) - -**Example:** -```bash -open "tools/timeline_editor/index.html?seq=../../workspaces/main/timeline.seq" -``` - -## Keyboard Shortcuts - -- **Spacebar**: Play/pause audio playback -- **0-6**: Quantize grid (0=Off, 1=1beat, 2=1/2, 3=1/4, 4=1/8, 5=1/16, 6=1/32) -- **Double-click timeline**: Seek to position (continues playing if active) -- **Double-click sequence**: Collapse/expand -- **Ctrl/Cmd + Wheel**: Zoom in/out at cursor position +## Architecture -## Technical Notes +- `index.html` - Main editor (1200+ lines) +- `timeline-format.js` - V2 parser/serializer/validator +- `timeline-viewport.js` - Zoom/scroll control +- `timeline-playback.js` - Audio playback -- Modular ES6 structure (requires HTTP server, not file://) - - `index.html` - Main editor and rendering - - `timeline-format.js` - V2 format parsing/serialization/validation - - `timeline-viewport.js` - Zoom/scroll/indicator control - - `timeline-playback.js` - Audio playback and waveform -- No external dependencies -- **Internal representation uses beats** (not seconds) -- Sequences have absolute times (beats), effects are relative to parent sequence -- BPM used for seconds conversion (tooltips, audio waveform alignment) -- Priority determines render order (higher = on top) -- Collapsed sequences show 35px title bar, expanded show full effect stack -- **Show Beats** toggle: Switch time markers between beats and seconds -- Time markers show 4-beat/bar increments (beats) or 1s increments (seconds) -- **Waveform and time markers are sticky** at top during scroll/zoom -- Vertical grid lines aid alignment -- **Quantize grid**: Independent snap control (works in both beat and second display modes) -- **Auto-expand/collapse**: Active sequence expands during playback, previous collapses -- **Auto-scroll**: Timeline follows playback indicator (keeps it in middle third of viewport) -- **Dual playback indicators**: Red bars on both timeline and waveform (synchronized) -- **Seamless seek**: Double-click or waveform click seeks without stopping playback -- **Node validation**: Only runs when explicit NODE declarations exist (auto-inferred nodes bypass validation) +Pure ES6 modules, no dependencies, requires HTTP server (not file://). |