Skip to navigation

Add seek preview thumbnails

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.
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:

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:

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