movie-thumbnail

A React component that renders a strip of seek thumbnails for video players, loading frames from a CDN based on TMDB ID and timestamp.

Installation

npm install movie-thumbnail

Usage

import ThumbnailStrip from 'movie-thumbnail'

function Player() {
  return (
    <ThumbnailStrip
      tmdbId={550}
      time={120}
      round={10}
      duration={7200}
      imageCount={5}
      currentPosition={2}
      imageWidth={160}
      imageHeight={90}
      imageSpacing={8}
      unit="px"
      slide={false}
      slideBuffer={4}
      slideDuration={0.3}
      onSuccess={(tmdbId) => console.log('loaded', tmdbId)}
      onError={(tmdbId) => console.error('error', tmdbId)}
      apiHost="https://api.domain.com"
      apiKey="your_api_key_here"
      className="strip"
      thumbClassName="thumb"
      imgClassName="thumb-img"
      placeholderClassName="thumb-placeholder"
    />
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tmdbId | number | — | TMDB movie ID | | time | number | — | Current playback time in seconds | | round | number | — | Rounding interval for thumbnail timestamps | | duration | number | — | Total video duration in seconds | | imageCount | number | 5 | Number of thumbnails to display | | currentPosition | number | 2 | Index of the "current" thumbnail in the strip | | imageWidth | number | 160 | Width of each thumbnail | | imageHeight | number | 90 | Height of each thumbnail | | imageSpacing | number | 8 | Gap between thumbnails | | unit | string | 'px' | CSS unit for dimensions (px, rem, etc.) | | slide | boolean | false | Enable sliding animation for thumbnail transitions | | slideBuffer | number | 4 | Extra offscreen thumbnails rendered on each side when sliding | | slideDuration | number | 0.3 | Slide transition duration in seconds | | onSuccess | function | — | Callback fired once per tmdbId when the probe image loads | | onError | function | — | Callback fired once per tmdbId when the probe image fails to load | | apiHost | string | — | API host used to sign asset URLs | | apiKey | string | — | API key sent in the X-API-Key request header | | className | string | — | Class for the strip container | | thumbClassName | string | — | Class for each thumbnail wrapper | | imgClassName | string | — | Class for loaded <img> elements | | placeholderClassName | string | — | Class for placeholder elements |

How It Works

The component requests a signed asset URL from {apiHost}/assets/sign?path={tmdbId} with the X-API-Key header. Thumbnails are then fetched from {signedUrl}/{seconds}.jpg where seconds is zero-padded to 5 digits and rounded to the nearest round interval. Signed URLs are cached when possible, the probe image controls onSuccess and onError, images are preloaded via new Image(), and a placeholder is shown until each image loads.

License

MIT