Thumbnails

Thumbnail support is implemented as a plugin, meaning it must be installed and enabled separately.

Setup

First, install the @castlabs/react-native-prestoplay-thumbnails package:

npm install @castlabs/react-native-prestoplay-thumbnails

Once the plugin is installed, enable it when initializing the SDK, by passing the ThumbnailPlugin class. For example:

import { Sdk } from "@castlabs/react-native-prestoplay";
import { ThumbnailPlugin } from "@castlabs/react-native-prestoplay-thumbnails";

Sdk.initialize({
  licenseKey: {
    /* Valid license here */
  },
  plugins: [ThumbnailPlugin],
});

Usage

If a thumbnail track is not embedded in a stream, side-loading of a thumbnail track is available. When initializing the player, specify a remote thumbnail track in the player configuration. For example:

<PlayerProvider
  playerConfig={{
    autoPlay: true,
    source: {
      /* ... */
    },
    remoteThumbnailTracks: [
      {
        url: "https://example.com/thumbs/$index$.jpg",
        mimeType: "image/jpeg",
        gridHeight: 1,
        gridWidth: 1,
        intervalMs: 10000,
      },
    ],
  }}
/>

note

On iOS and tvOS, a sideloaded track is not required when the stream itself carries an I-frame only track (an HLS EXT-X-I-FRAME-STREAM-INF rendition): those frames are rendered by the Apple thumbnails engine. When remoteThumbnailTracks is configured, the sideloaded track takes precedence.

With the plugin enabled, use the Thumbnail component to display a single thumbnail at a specific time in the video:

<Thumbnail
  positionMs={/* Time in milliseconds where the thumbnail should appear */}
  style={{ width: 150, height: 100 }} // Adjust the size of the thumbnail
/>

Please note, that it’s important to place the Thumbnail component inside the PlayerProvider to ensure it has access to the player instance.

Error Handling

On Android and Web, the Thumbnails plugin emits ErrorCode.ThumbnailsImageMissing when a thumbnail image cannot be loaded. Subscribe to player errors to handle this case:

import { ErrorCode } from "@castlabs/react-native-prestoplay";

player.onError((error) => {
  if (error.errorCode === ErrorCode.ThumbnailsImageMissing) {
    // Thumbnail image unavailable — hide the thumbnail UI or show a placeholder
  }
});

Note: this error is non-fatal and does not affect playback.

On iOS and tvOS the Apple engine raises the same error when it cannot produce a frame for a requested position — including positions requested before the I-frame track is ready, and every position of a stream that carries no I-frame track at all. Scrubbing such content can therefore raise ThumbnailsImageMissing repeatedly, so treat it as "no thumbnail for now" rather than a fatal condition.