# Timeline Editor

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

## Features

✅ **Implemented:**
- 📂 Load/save `demo.seq` files
- 📊 Visual Gantt-style timeline
- 🎯 Drag & drop sequences along timeline
- 🎯 Drag & drop effects along timeline
- 🎯 Resize effects with left/right handles
- ⏱️ Edit timing (start/end times)
- ⚙️ Stack-order based priority system
- ⚙️ Edit effect class names and constructor arguments
- 🔍 Zoom in/out (10% - 200%)
- 🎵 Audio waveform visualization (WAV files)
- 📋 Real-time statistics
- 🗑️ Delete sequences/effects
- ➕ Add new sequences
- 🎼 Snap-to-beat mode with beat markers

## Usage

1. **Open the editor:**
   ```bash
   open tools/timeline_editor/index.html
   ```
   Or double-click `index.html` in Finder.

2. **Load a timeline:**
   - Click "📂 Load demo.seq"
   - Select your `assets/demo.seq` file

3. **Edit the timeline:**
   - **Drag sequences/effects** to move them along the timeline
   - **Click an item** to select it and view properties
   - **Edit properties** in the panel below
   - **Click "Apply"** to save property changes

4. **Save your changes:**
   - Click "💾 Save demo.seq"
   - Choose where to save the modified file

5. **Load audio waveform (optional):**
   - Click "🎵 Load Audio (WAV)" to visualize your music track
   - The waveform appears above the timeline for visual reference
   - Use it to align sequences with beats, drops, and musical phrases
   - Click "✖ Clear Audio" to remove the waveform

   **Tip:** Generate a WAV file from your demo using:
   ```bash
   ./build/demo64k --dump_wav output.wav
   ```
   Then load `output.wav` in the timeline editor to align sequences with the actual audio output.

6. **Zoom controls:**
   - Use the zoom slider to adjust timeline scale
   - Higher zoom = more pixels per second
   - Waveform scales automatically with zoom

7. **Snap-to-beat mode:**
   - Enable "Show Beats" checkbox to display beat markers
   - Sequences and effects snap to beat boundaries when dragged
   - Helps maintain musical timing

## Keyboard Shortcuts

- **Delete key**: Delete selected item (when implemented)
- **Escape**: Deselect current item

## 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:**
- `0b`, `4b`, `64b` = Beats (converted using BPM)
- `0.0`, `2.0`, `32.0` = Seconds
- Integer without 'b': treated as beats
- Decimal point: treated as seconds

Example:
```
# BPM 120
SEQUENCE 0b 0 "Opening Scene"
  EFFECT - FlashCubeEffect .2 3      # Background (priority -1)
  EFFECT + FlashEffect 0.0 1.0       # Foreground (priority 0)
  EFFECT + FadeEffect 0.5 2.0        # Overlay (priority 1)

SEQUENCE 4b 1 "Beat Drop"
  EFFECT + HeptagonEffect 0.0 0.5    # Priority 0
  EFFECT = ParticlesEffect 0.0 2.0   # Priority 0 (same layer)
```

## Color Coding

- **Blue boxes**: Sequences (container for effects)
- **Gray boxes**: Effects (visual elements)
- **Green highlight**: Selected sequence
- **Orange highlight**: Selected effect

## Tips

- **Sequences** have absolute start times
- **Effects** have start/end times **relative to their sequence**
- Priority determines rendering order (higher = rendered later = on top)
- Effect constructor arguments are passed as-is to the C++ code

## Limitations

- No preview rendering (this is intentional - it's just a timeline editor)
- No automatic overlap detection yet
- No undo/redo (coming soon)
- Cannot add effects to sequences (manually edit properties for now)

## Future Enhancements

- [ ] Undo/redo functionality
- [ ] Add effect button (create new effects within sequences)
- [ ] Overlap detection warnings
- [ ] Timeline playback indicator
- [ ] Multiple file comparison
- [ ] Export to different formats
- [ ] **Music.track visualization**: Parse `music.track` file and overlay tracker patterns/samples on timeline for alignment assistance

## Technical Details

- Pure HTML/CSS/JavaScript (no dependencies)
- No backend required
- Works offline
- All processing happens in the browser
- Files are saved via browser download API

## Integration

After editing in the timeline editor:

1. Save the modified `demo.seq`
2. Copy it to `assets/demo.seq`
3. Rebuild the project: `cmake --build build`
4. The new timeline will be compiled into the demo

No code changes needed - the `seq_compiler` automatically processes the updated file.