diff options
Diffstat (limited to 'tools/timeline_editor/README.md')
| -rw-r--r-- | tools/timeline_editor/README.md | 63 |
1 files changed, 53 insertions, 10 deletions
diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md index 6e368cf..72b5ae0 100644 --- a/tools/timeline_editor/README.md +++ b/tools/timeline_editor/README.md @@ -14,28 +14,49 @@ Interactive web-based editor for `timeline.seq` files. - ⚙️ Stack-order based priority system - 🔍 Zoom (10%-200%) with mouse wheel + Ctrl/Cmd - 🎵 Audio waveform visualization (aligned to beats) -- 🎼 Snap-to-beat mode (enabled by default) +- 🎼 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** (NEW) -- 🎚️ **Sticky audio track and timeline ticks** (NEW) +- ✨ 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 + - Click waveform to seek to position + - **Double-click timeline** to seek during playback (continues playing) - Watch sequences auto-expand/collapse during playback - - Red playback indicator shows current position + - Red playback indicators on both timeline and waveform show current position 5. **Edit:** - - Drag sequences/effects to reposition - - Double-click sequence header to collapse/expand + - **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" @@ -78,9 +99,28 @@ 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 @@ -91,9 +131,12 @@ SEQUENCE 2.5s 0 "Explicit seconds" # Rare: start at 2.5 physical seconds - 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) +- **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 -- Snap-to-beat enabled by default for musical 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 |