diff options
Diffstat (limited to 'tools')
| -rw-r--r-- | tools/timeline_editor/README.md | 70 | ||||
| -rw-r--r-- | tools/timeline_editor/ROADMAP.md | 24 |
2 files changed, 75 insertions, 19 deletions
diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md index 4d41cd7..82a743f 100644 --- a/tools/timeline_editor/README.md +++ b/tools/timeline_editor/README.md @@ -4,7 +4,7 @@ Interactive web-based editor for `timeline.seq` files. ## Features -- 📂 Load/save `timeline.seq` files +- 📂 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 @@ -22,9 +22,12 @@ Interactive web-based editor for `timeline.seq` files. - 📊 **CPU load visualization** (color-coded effect density) - ▶️ Audio playback with auto-expand/collapse - 🎚️ Sticky audio track and timeline ticks -- 🔴 **Playback indicator on waveform** (NEW) -- 🎯 **Double-click seek during playback** (NEW) -- 📍 **Click waveform to seek** (NEW) +- 🔴 **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) ## CPU Load Visualization @@ -56,6 +59,8 @@ This helps identify performance hotspots in your timeline. - 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 @@ -63,21 +68,32 @@ This helps identify performance hotspots in your timeline. - 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" +7. **Save:** Click "💾 Save timeline.seq" (validates node references before saving) ## File Format ⚠️ **For complete format specification, see:** `doc/SEQUENCE.md` -The editor parses and generates `.seq` files with this format: +The editor parses and generates **Sequence V2 format** `.seq` files: ``` # BPM 120 -SEQUENCE <start_time> <priority> ["optional_name"] [optional_end] - EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...] - EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...] +SEQUENCE <start_time> <priority> ["optional_name"] + NODE <name> <type> # Optional explicit node declarations + EFFECT <+|=|-> <ClassName> <inputs...> -> <outputs...> <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 @@ -88,21 +104,35 @@ SEQUENCE <start_time> <priority> ["optional_name"] [optional_end] - `4b`, `16b` = Explicit beats (optional 'b' suffix for clarity) - `2.0s`, `8.25s` = Explicit seconds (rare, for physical timing) -Example (Beat-Based): +**Example (V2 Format with NODE declarations):** ``` # BPM 120 -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 0.0 0 "Opening Scene" + NODE temp1 u8x4_norm # Declare intermediate buffer + NODE depth depth24 # Declare depth buffer + EFFECT + Hybrid3D source depth -> temp1 0.0 4.0 + EFFECT + GaussianBlur temp1 -> sink 0.0 4.0 -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 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 +``` -SEQUENCE 2.5s 0 "Explicit seconds" # Rare: start at 2.5 physical seconds - EFFECT + Fade 0 4 # Still uses beats for duration +**Example (V2 Format with auto-inferred nodes):** ``` +# BPM 120 +SEQUENCE 0.0 0 "Simple Chain" + # No NODE declarations - temp1 is auto-inferred + EFFECT + Blur source -> temp1 0.0 4.0 + 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 @@ -132,6 +162,7 @@ open "tools/timeline_editor/index.html?seq=../../workspaces/main/timeline.seq" - 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 @@ -149,3 +180,4 @@ open "tools/timeline_editor/index.html?seq=../../workspaces/main/timeline.seq" - **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) diff --git a/tools/timeline_editor/ROADMAP.md b/tools/timeline_editor/ROADMAP.md index b14a73b..836c6f6 100644 --- a/tools/timeline_editor/ROADMAP.md +++ b/tools/timeline_editor/ROADMAP.md @@ -29,6 +29,30 @@ This document outlines planned enhancements for the interactive timeline editor. ## Phase 1: Core Editing Features (High Priority) +### 1.0 Sequence V2 Format Support ✅ COMPLETED +**Goal:** Support explicit node routing and DAG-based effect composition. + +**Features:** +- ✅ Parse NODE declarations with typed buffers (u8x4_norm, f32x4, f16x8, depth24, compute_f32) +- ✅ Parse arrow syntax: `EFFECT + ClassName input1 input2 -> output1 output2 start end` +- ✅ Serialize v2 format with NODE declarations +- ✅ Validate node references (only when explicit NODEs declared) +- ✅ Buffer chain visualization in properties panel and tooltips +- ✅ Node editor modal for adding/deleting node declarations +- ✅ Backward compatible with auto-inferred nodes (no NODE declarations) + +**Implementation:** +- New module: `timeline-format.js` (parse, serialize, validate, render) +- Updated data model: effects have `inputs[]` and `outputs[]` arrays +- Property panel: separate fields for inputs/outputs, buffer chain display +- Validation: blocks save if undeclared nodes referenced (when NODEs explicit) + +**Status:** ✅ COMPLETED (2026-02-17) +**Effort:** ~12 hours actual +**Impact:** Essential for v2 DAG architecture support + +--- + ### 1.1 Snap-to-Beat ⭐ Priority: HIGH **Goal:** Enable precise musical timing by snapping items to beat boundaries. |