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
|
# Timeline Editor
Interactive web-based editor for `timeline.seq` files.
## Features
- 📂 Load/save `timeline.seq` files
- 📊 Visual Gantt-style 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** (NEW)
- 🎯 **Double-click seek during playback** (NEW)
- 📍 **Click waveform to seek** (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:** `open tools/timeline_editor/index.html` or double-click in browser
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
- **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"
## File Format
⚠️ **For complete format specification, see:** `doc/SEQUENCE.md`
The editor parses and generates `.seq` files with this format:
```
# BPM 120
SEQUENCE <start_time> <priority> ["optional_name"] [optional_end]
EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...]
EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...]
```
**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 (Beat-Based):
```
# 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 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
```
## 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
- Pure HTML/CSS/JavaScript (no dependencies, works offline)
- **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
|
