1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# Timeline Editor
Interactive web-based editor for `timeline.seq` files.
## Features
- 📂 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)
## CPU Load Visualization
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
This helps identify performance hotspots in your timeline.
## Usage
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)
## File Format
⚠️ **For complete format specification, see:** `doc/SEQUENCE.md`
The editor parses and generates **Sequence V2 format** `.seq` files:
```
# BPM 120
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
- `-` = Decrement priority (background layers)
**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):**
```
# BPM 120
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 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
```
**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
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
## Technical Notes
- 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)
|
