ef-thumbnail-strip

Visual thumbnail strip showing preview frames from video or timegroup elements. Automatically generates and displays thumbnails at regular intervals along the timeline.

Basic Usage

Thumbnail strip for a video element.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="thumb-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 h-[48px] bg-gray-900 rounded-lg overflow-auto">
  <ef-thumbnail-strip target="thumb-demo" thumbnail-height="48"></ef-thumbnail-strip>
</div>
<div class="mt-2 flex gap-2">
  <ef-controls target="thumb-demo">
    <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
  </ef-controls>
</div>

Adjustable Thumbnail Size

Control thumbnail height while maintaining aspect ratio.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="size-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 space-y-2">
  <div class="text-white text-sm">24px height:</div>
  <div class="h-[24px] bg-gray-900 rounded-lg overflow-auto">
    <ef-thumbnail-strip target="size-demo" thumbnail-height="24"></ef-thumbnail-strip>
  </div>
  <div class="text-white text-sm mt-4">48px height:</div>
  <div class="h-[48px] bg-gray-900 rounded-lg overflow-auto">
    <ef-thumbnail-strip target="size-demo" thumbnail-height="48"></ef-thumbnail-strip>
  </div>
</div>

Thumbnail Spacing

Control spacing between thumbnails.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="spacing-demo">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 space-y-2">
  <div class="text-white text-sm">Dense spacing (24px):</div>
  <div class="h-[48px] bg-gray-900 rounded-lg overflow-auto">
    <ef-thumbnail-strip
      target="spacing-demo"
      thumbnail-height="48"
      thumbnail-spacing-px="24"
    ></ef-thumbnail-strip>
  </div>
  <div class="text-white text-sm mt-4">Wide spacing (96px):</div>
  <div class="h-[48px] bg-gray-900 rounded-lg overflow-auto">
    <ef-thumbnail-strip
      target="spacing-demo"
      thumbnail-height="48"
      thumbnail-spacing-px="96"
    ></ef-thumbnail-strip>
  </div>
</div>

Timeline Integration

Thumbnails automatically integrate with timeline zoom and scroll.

<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="timeline-thumbs">
  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
</ef-timegroup>
<div class="mt-4 h-[350px] bg-gray-900 rounded-lg overflow-hidden">
  <ef-timeline target="timeline-thumbs"></ef-timeline>
</div>
<div class="mt-2 text-white text-sm">
  Thumbnails automatically appear in video tracks. Zoom in to see more detail.
</div>

Timegroup Thumbnails

Generate thumbnails from entire compositions, not just video.

<ef-timegroup mode="sequence" class="w-[720px] h-[480px] bg-black" id="comp-thumbs">
  <ef-timegroup class="flex items-center justify-center">
    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="0s" sourceout="2s" class="absolute inset-0 size-full object-contain"></ef-video>
    <h1 class="text-white text-6xl font-bold bg-blue-600 p-6 rounded relative">One</h1>
  </ef-timegroup>
  <ef-timegroup class="flex items-center justify-center">
    <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="5s" sourceout="7s" class="absolute inset-0 size-full object-contain"></ef-video>
    <h1 class="text-white text-6xl font-bold bg-purple-600 p-6 rounded relative">Two</h1>
  </ef-timegroup>
</ef-timegroup>
<div class="mt-4 h-[60px] bg-gray-900 rounded-lg overflow-auto">
  <ef-thumbnail-strip target="comp-thumbs" thumbnail-height="60"></ef-thumbnail-strip>
</div>

Custom Zoom

Control thumbnail density:

For standalone use, provide explicit pixels-per-ms attribute.

Intrinsic Duration

By default, thumbnails show the trimmed region of video:

• trimstart="2s" means thumbnails start at 2 seconds into source
• Duration matches effective video duration

Set use-intrinsic-duration to show entire source file regardless of trim.

Features

Lazy loading — Only generates thumbnails for visible region as you scroll.

Viewport virtualization — Efficiently handles timelines of any length.

Smart caching — Caches generated thumbnails and reuses them when possible.

Adaptive spacing — Maintains consistent visual spacing at all zoom levels.

Frame-accurate — Aligns thumbnails to frame boundaries for precision.

Video support — Extracts thumbnails directly from video files.

Timegroup support — Renders composition snapshots with all layers.

Automatic aspect ratio — Thumbnails match target element dimensions.

Target Types

Video elements (ef-video):

• Extracts frames directly from video file
• Fast batch extraction
• Respects video trim settings

Root timegroups (top-level ef-timegroup):

• Renders entire composition to thumbnails
• Includes all layers (video, text, images)
• Lower resolution rendering for performance

How It Works

The thumbnail strip uses different strategies based on target type:

For videos:

1. Uses ThumbnailExtractor for batch frame extraction
2. Decodes video to access raw frames
3. Caches extracted frames for reuse
4. Supports source time translation for trimmed videos

For timegroups:

1. Creates off-screen render clone of composition
2. Seeks to each timestamp and captures canvas
3. Generates at low resolution (0.25x scale) for performance
4. Reuses clone for subsequent thumbnail batches

Thumbnail Positioning

Thumbnails use a stable grid system:

• Grid is anchored in timeline space (not viewport space)
• Scrolls naturally with timeline content
• On zoom, grid snaps to keep thumbnails near viewport edges
• Prevents visual slipping during zoom operations

Spacing between thumbnails is consistent at all zoom levels, but more thumbnails become visible as you zoom in.

Performance Optimization

Batch extraction — Videos extract multiple frames in one pass.

Viewport culling — Only renders thumbnails in visible area plus buffer.

Canvas pooling — Reuses canvas elements across renders.

Abort on scroll — Cancels in-flight captures when viewport changes.

Nearest neighbor — Shows nearby cached thumbnails while loading exact frame.

Trimmed Videos

By default, thumbnails show the trimmed region of video:

• trimstart="2s" means thumbnails start at 2 seconds into source
• Duration matches effective video duration

Set use-intrinsic-duration to show entire source file regardless of trim.

Timeline Context

When used inside a timeline, the strip automatically:

• Reads zoom level from timeline context
• Synchronizes with timeline scroll position
• Updates viewport window as timeline scrolls
• Respects timeline state without explicit binding

For standalone use, provide explicit pixels-per-ms attribute.

CSS Custom Properties

Customize appearance:

ef-thumbnail-strip {
  --ef-thumbnail-gap: 2px;
  --ef-color-bg-inset: rgba(100, 100, 100, 0.3);
  --ef-color-border-subtle: rgba(150, 150, 150, 0.5);
  --ef-color-error: #ef4444;
}

Error States

The component shows error messages for:

• No target specified
• Target element not found
• Invalid target type (must be video or root timegroup)

Example error: "Invalid target: 'ef-text' must be ef-video or root ef-timegroup"

Usage in Timeline

Thumbnails are automatically rendered in video and timegroup tracks when inside ef-timeline. The timeline manages thumbnail strip lifecycle and positioning.

For custom track implementations, use ef-thumbnail-strip directly and manage zoom/scroll context.