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
|
# 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
- 🗑️ Delete sequences/effects
- ▶️ 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)
## 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:**
- 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
|
