Video Timeline Slider - Technical Documentation

🎯 Overview

The slider represents an entire timelapse sequence as one continuous timeline. Each video is approximately 4 seconds representing 1 hour of real time, compressed from thousands of source frames.

Try it live: 🚀 Launch Timelapse Player

⚡ Real-Time Scrubbing

User Experience

Drag the slider → Video seeks immediately to that position
Frame-accurate seeking → 30fps precision targeting
Smooth performance → No lag or stuttering during rapid movements
Predictable behavior → Always lands where you point

Play/Pause Behavior

During drag: Video pauses automatically to prevent playback advancing beyond thumb position

On release: Resumes playing from new position if it was playing before drag started

Manual control: Play/pause button works independently of scrubbing

🔧 Technical Implementation

Latest-Only Event Queue

The core innovation is using an event-driven approach rather than time-based throttling or debouncing:

// Latest-only seek queue - process only the most recent request
let pendingSeek = null;
let seekScheduled = false;

function scheduleSeek(targetVideoIndex, targetTimeInVideo) {
  // Overwrite any previous pending seek (latest wins)
  pendingSeek = { targetVideoIndex, targetTimeInVideo };
  
  if (!seekScheduled) {
    seekScheduled = true;
    setTimeout(() => {
      if (pendingSeek) {
        executeSeek(pendingSeek);
        pendingSeek = null;
      }
      seekScheduled = false;
    }, 0); // Next event loop tick
  }
}

How It Works

Rapid events → User drags slider, generating many input events
Latest wins → Each event overwrites the previous pending seek
Event loop batching → setTimeout(0) defers to next tick
Single execution → Only the final position gets processed

Why This Approach

Event-driven: Works with browser's natural timing instead of arbitrary delays

Efficient: No wasted seeks to intermediate positions during rapid movement

Responsive: Immediate visual feedback with optimal backend processing

Adaptive: Automatically scales to system performance without tuning

📊 Timeline Mapping

Duration Analysis

Queries actual video durations → No assumptions about 4-second length
Builds total timeline → Sum of all video durations in sequence
Maps slider position → 0-100% represents entire accumulated duration

Frame-Level Precision

// Calculate target frame within video
const targetFrame = Math.floor(timeWithinVideo * TIMELAPSE_FPS);
const targetTimeInVideo = targetFrame / TIMELAPSE_FPS;

// Seek to exact frame position
mainVideo.currentTime = targetTimeInVideo;

🎬 Event Flow

Key Video Events

input: Triggers seek during drag

seeking: Video starts seeking to new position

seeked: Seek complete, can resume playback

mouseup: Restores original play state

State Management

Scrubbing state → Tracks when user is actively dragging
Play state memory → Remembers if video was playing before scrub
Seeking state → Prevents timeline updates during async seeks

🏆 Result

Smooth, responsive scrubbing that feels like professional video editing software. The latest-only event queue provides the perfect balance of responsiveness and efficiency, automatically adapting to system performance without requiring manual tuning.

      Performance characteristics: Works equally well on fast desktops with local files and slower systems with remote video streams.
    

🔗 Try It Yourself

Experience the smooth scrubbing behavior in action:

🎥 Open Timelapse Player

Load a playlist and try dragging the timeline slider to see the real-time seeking in action.