> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Add seek preview thumbnails

> Show a thumbnail for any position as the viewer scrubs, using FastPix spritesheets in the FastPix Flutter Player. On by default, with an advanced high-density option.

FastPix generates spritesheets, grids of thumbnails, for every on-demand video. The player loads the active source's spritesheet in the background and gives a custom seek bar a thumbnail for any position.

* **Normal spritesheet:** on by default, with nothing to configure. FastPix picks 50 or 100 tiles and their spacing from the video's length.
* **Advanced spritesheet:** opt in for a thumbnail every 1 to 10 seconds. When it is on, only the advanced spritesheet is loaded, and the normal one is not used first or as a fallback. An interval outside 1 to 10 uses 10.

```dart
final configuration = FastPixPlayerConfiguration(
  'your-workspace-id',
  'your-viewer-id',
  'your-beacon-url',
  spritesheetConfiguration: const FastPixPlayerSpritesheetConfiguration(
    enableAdvancedSpritesheet: true,
    advancedSpritesheetInterval: 2,
  ),
);
```

\


## Show the preview

Show the preview above your seek bar's thumb while the viewer drags, passing the scrub position:

```dart
if (controller.isScrubbing)
  FastPixSeekPreview(
    controller: controller,
    position: state.position, // from playbackStateStream while scrubbing
    width: 160,
  ),
```

`FastPixSeekPreview` draws the tile for the position. While no image is available, such as spritesheets disabled, a live source, still loading or generating, or a failure, it shows only the time. It never shows a spinner or an error.

To draw thumbnails yourself, `controller.spritesheetTileAt(position)` returns the tile covering a position, with its `start`, `end`, and `region` in the spritesheet image. `controller.spritesheet`, `spritesheetStream`, and `spritesheetStatus` (`idle`, `loading`, `ready`, `failed`) follow the active source.

\


## Image hosts

The images host is derived from the source's `customDomain`, by replacing `stream` with `images` in the first label. There is nothing to configure, and a playlist that mixes environments works per item:

```dart
FastPixPlayerDataSource.hls(
  playbackId: 'staging-playback-id',
  customDomain: 'stream.fastpix.co', // spritesheets: images.fastpix.co
);
```

A source with no `customDomain` uses `images.fastpix.com`. A `customDomain` that is not a `stream.*` host has no images host to derive, so that source shows a time-only preview rather than having a host guessed for it. Read the resolved origin from `FastPixPlayerDataSource.imagesHost`, which is `null` in that case.

For private and DRM media, the source's playback `token` is sent with the spritesheet requests. Without one they fail with `unauthorized`.

\


## Things to know

* Spritesheets load after the source is ready and never delay or affect playback. Turn them off with `enableSpritesheet: false`.
* Each source costs a metadata request (5 to 85 KB) and an image: about 0.3 MB for a normal spritesheet, up to about 19 MB for an advanced one at interval 2 on a long video.
* The first request for a new advanced interval makes FastPix generate it. That took about two minutes for an 80-minute video, while the player retries for about 30 seconds (after 1, 2, 4, 8, and 15 seconds), so the first viewer of a new interval usually sees only the time, and later viewers see thumbnails.
* Images too large to decode at full size on a phone are decoded at a reduced size. Tiles look softer but stay correct.
* Failures arrive as `FastPixSpritesheetFailedEvent`, never on the playback error channel, with a `FastPixSpritesheetErrorCode`: `unauthorized`, `mediaNotFound`, `intervalExceedsDurationCap`, `generationTimedOut`, `invalidResponse`, `metadataImageMismatch`, `decodeFailed`, or `networkError`. The other spritesheet events are `spritesheetLoadStarted`, `spritesheetLoaded`, and `spritesheetImageReady`.

\


## What's next

* [Build a custom UI](/docs/flutter-player/build-a-custom-ui) to wire the preview into your own seek bar.