@hurraey/video-thumbnail

Goal

Generate a poster, exact visible thumbnails, and coarse background thumbnails without depending on React, Zustand, or editor-specific project state.

Prerequisites

• Node.js 22 or later and pnpm 10 or later for package development
• A browser environment with HTMLVideoElement and createImageBitmap
• Web Worker, WebCodecs VideoDecoder, and an MP4-compatible source for coarse background decoding
• A bundler that supports module workers created through new URL(..., import.meta.url)

Step-by-Step Guide

Install the package

Install a locally packed release:

pnpm add ./hurraey-video-thumbnail-0.1.0.tgz

After a registry release is available, install it by package name:

pnpm add @hurraey/video-thumbnail

Import the public API

Application code should import from the library entry point instead of an internal browser adapter.

import {
    abortViewportThumbnails,
    disposePoster,
    ensurePoster,
    registerIdleBackfill,
    scheduleViewportThumbnails,
    thumbnailCache,
    unregisterIdleBackfill,
} from '@hurraey/video-thumbnail';

Generate the poster and register background work

const sourceId = URL.createObjectURL(videoFile);

await ensurePoster(sourceId);
registerIdleBackfill(sourceId, videoDurationSec);

The poster uses an isolated HTMLVideoElement and seeks to 0.1 seconds. Idle backfill uses the Worker path and stores frames with coarse quality.

Request exact visible frames

scheduleViewportThumbnails({
    sourceId,
    objectUrl: sourceId,
    timestamps: [0.8, 2.4, 4],
    requestKey: 'viewport-42',
});

Use a new requestKey when the viewport, zoom level, tile geometry, or visible source times change. A completed frame is committed only when it still belongs to the current request.

Read the best available frame

const frame = thumbnailCache.getBestNear({
    sourceId,
    timeSec: 2.4,
    toleranceSec: 0.15,
});

Here, exact means that the browser completed an HTMLVideoElement.currentTime seek for the requested timestamp. It does not mean byte-identical decoding across browsers. coarse means that the Worker decoded the nearest sync sample (keyframe).

The cache prefers an exact frame over a coarse frame within the requested tolerance. A later exact frame replaces a coarse frame stored at the same quantized timestamp.

Release runtime resources

abortViewportThumbnails(sourceId);
unregisterIdleBackfill(sourceId);
disposePoster(sourceId);
thumbnailCache.remove(sourceId);
URL.revokeObjectURL(sourceId);

Call the cleanup functions when a source is removed, replaced, or no longer reachable.

Verify Final Result

Install dependencies, verify the library, and create an installable tarball.

pnpm install
pnpm verify
pnpm pack

The Core directory contains deterministic policies and calculations. The Browser directory contains resource-owning adapters for HTML video seeking, Worker decoding, ImageBitmap, and IndexedDB.