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,
      },
    ],
  }}
/>

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.