Skip to content

What is a thumbnail source?

IThumbnailSource is the contract for supplying hover thumbnail frames to a progress bar. VttSpriteThumbnailSource is a ready-made implementation of it, exported for consumers building a custom progress bar; it fetches a WebVTT sprite manifest and parses the sprite coordinates from each cue. It is not wired into the player by default: the built-in DesktopUiPlugin reads previewSpriteUrl through its own internal sprite loader. A custom implementation could use a different manifest format or a server-side lookup.

IThumbnailSource interface

TypeScript
import type { IThumbnailSource } from '@nomercy-entertainment/nomercy-video-player';
MethodSignatureDescription
load(item)(item: BasePlaylistItem) => Promise<boolean>Fetch and cache thumbnails for the item. Returns true when thumbnails are available, false otherwise
lookup(timeSeconds)(timeSeconds: number) => ThumbnailFrame | nullReturn the frame covering timeSeconds. Must be synchronous, called on every scrub event
unload()() => voidRelease cached data. Called on unload and dispose

ThumbnailFrame

TypeScript
import type { ThumbnailFrame } from '@nomercy-entertainment/nomercy-video-player';

interface ThumbnailFrame {
  spriteUrl: string; // URL of the sprite image
  x: number; // Left offset within the sprite, in pixels
  y: number; // Top offset within the sprite, in pixels
  w: number; // Width of the sub-region, in pixels
  h: number; // Height of the sub-region, in pixels
  start: number; // Cue start time in seconds
  end: number; // Cue end time in seconds
}

Ready-made implementation: VttSpriteThumbnailSource

VttSpriteThumbnailSource is not wired in automatically; construct it yourself when building a custom progress bar. It reads the previewSpriteUrl field on VideoPlaylistItem:

TypeScript
import type { VideoPlaylistItem } from '@nomercy-entertainment/nomercy-video-player';

// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'
const item: VideoPlaylistItem = {
  url: '/Tears.of.Steel.(2012)/Tears.of.Steel.(2012).NoMercy.m3u8',
  previewSpriteUrl: '/Tears.of.Steel.(2012)/previews.vtt',
};

The VTT manifest references sprite images using fragment identifiers (#xywh=):

Code
WEBVTT

00:00:00.000 --> 00:00:10.000
/cosmos/sprites/000.jpg#xywh=0,0,160,90

00:00:10.000 --> 00:00:20.000
/cosmos/sprites/000.jpg#xywh=160,0,160,90

VttSpriteThumbnailSource parses these coordinates and exposes them via lookup(timeSeconds).

Using thumbnails in a custom UI

TypeScript
player.on('time', () => {
  // Called during scrub, lookup is synchronous
  const frame = thumbnailSource.lookup(hoverTime);
  if (!frame) return;

  img.src = frame.spriteUrl;
  img.style.objectPosition = `-${frame.x}px -${frame.y}px`;
  img.style.width = `${frame.w}px`;
  img.style.height = `${frame.h}px`;
});

The DesktopUiPlugin does not use this adapter. It reads previewSpriteUrl through its own internal sprite loader to show hover thumbnails above the progress-bar scrubber. VttSpriteThumbnailSource is exported for consumers who build a custom progress bar and want a ready-made sprite resolver.

See also