diff options
Diffstat (limited to 'tools/timeline_editor/README.md')
| -rw-r--r-- | tools/timeline_editor/README.md | 180 |
1 files changed, 61 insertions, 119 deletions
diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md index adf9d4e..6e368cf 100644 --- a/tools/timeline_editor/README.md +++ b/tools/timeline_editor/README.md @@ -1,73 +1,43 @@ # Timeline Editor -Interactive web-based editor for `demo.seq` timeline files. +Interactive web-based editor for `timeline.seq` 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) +- 📂 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 -- ⚙️ Edit effect class names and constructor arguments -- 🔍 Zoom in/out (10% - 200%) -- 🎵 Audio waveform visualization (WAV files) -- 📋 Real-time statistics +- 🔍 Zoom (10%-200%) with mouse wheel + Ctrl/Cmd +- 🎵 Audio waveform visualization (aligned to beats) +- 🎼 Snap-to-beat mode (enabled by default) +- 🎛️ BPM slider (60-200 BPM) +- 🔄 Re-order sequences by time - 🗑️ Delete sequences/effects -- ➕ Add new sequences -- 🎼 Snap-to-beat mode with beat markers +- ▶️ **Audio playback with auto-expand/collapse** (NEW) +- 🎚️ **Sticky audio track and timeline ticks** (NEW) ## 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 +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. **Playback:** + - Click "▶ Play" or press **Spacebar** to play/pause + - Click waveform to seek + - Watch sequences auto-expand/collapse during playback + - Red playback indicator shows current position +5. **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 +6. **Zoom:** Ctrl/Cmd + mouse wheel (zooms at cursor position) +7. **Save:** Click "💾 Save timeline.seq" ## File Format @@ -87,71 +57,43 @@ SEQUENCE <start_time> <priority> ["optional_name"] [optional_end] - `=` = 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 +**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: +Example (Beat-Based): ``` # 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 +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) -- 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) +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) -## 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 +SEQUENCE 2.5s 0 "Explicit seconds" # Rare: start at 2.5 physical seconds + EFFECT + Fade 0 4 # Still uses beats for duration +``` -## Integration +## Keyboard Shortcuts -After editing in the timeline editor: +- **Spacebar**: Play/pause audio playback +- **Ctrl/Cmd + Wheel**: Zoom in/out at cursor position -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 +## Technical Notes -No code changes needed - the `seq_compiler` automatically processes the updated file. +- 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 +- Time markers show beats by default (4-beat/bar increments) +- **Waveform and time markers are sticky** at top during scroll/zoom +- Vertical grid lines aid alignment +- Snap-to-beat enabled by default for musical alignment +- **Auto-expand/collapse**: Active sequence expands during playback, previous collapses +- **Auto-scroll**: Timeline follows playback indicator (keeps it in middle third of viewport) |