# Timeline Editor

Interactive web-based editor for `timeline.seq` files.

## Features

- 📂 Load/save `timeline.seq` files
- 📊 Visual Gantt-style timeline with sticky time markers
- 🎯 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
- ⚙️ Stack-order based priority system
- 🔍 Zoom (10%-500%) with mouse wheel + Ctrl/Cmd
- 🎵 Audio waveform visualization
- 🎼 Snap-to-beat mode
- 🔄 Re-order sequences by time
- 🗑️ Delete sequences/effects

## 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. **Edit:**
   - Drag sequences/effects to reposition
   - Double-click sequence header to collapse/expand
   - Click item to edit properties in side panel
   - Drag effect handles to resize
4. **Zoom:** Ctrl/Cmd + mouse wheel (zooms at cursor position)
5. **Audio:** Load WAV file for waveform visualization
6. **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
```

## Technical Notes

- Pure HTML/CSS/JavaScript (no dependencies, works offline)
- Sequences have absolute times, effects are relative to parent sequence
- Priority determines render order (higher = on top)
- Collapsed sequences show 35px title bar, expanded show full effect stack
- Time markers sticky at top when scrolling
- Vertical grid lines aid alignment