Trickplay Thumbnails

Trickplay thumbnails are the seek previews: the small image that appears when you hover over or drag the playback scrubber. They belong to a specific media file, so each version of a title (e.g. different quality encodes) has its own set of sprites.

---

How It Works

1. When a user starts streaming a media file for the first time, Sovereign queues a trickplay generation job for that file. The job holds off until the stream is 90 seconds old (and starts that wait again if a newer stream or a seek begins), so it doesn’t start while a playback is only just getting going.
2. A background worker samples the video every few seconds across its whole duration and packs the frames into JPEG sprite sheets, a grid of thumbnails per sheet.
3. Once the sheets are on disk and the job is marked Ready, the player is given an index that maps each timestamp to a region of the right sheet. That index is built on demand and isn’t written to disk.

sequenceDiagram
  participant P as Client device
  participant S as Sovereign
  participant W as Background worker

  P->>S: Start streaming a file
  S->>W: Queue a preview job
  P->>S: Previews?
  S-->>P: Being prepared
  Note over W: Waits until the stream<br/>is 90 seconds old
  W->>W: Sample the video, pack the sheets
  W-->>S: Ready
  P->>S: Previews?
  S-->>P: An index to the sheets

Sampling seeks to roughly one keyframe per thumbnail instead of decoding the whole file, so a feature is usually done in seconds. How long it takes depends mostly on how quickly your storage answers a seek, more than on the length of the title or the speed of your processor. A library on a slow or busy network mount is where you’ll notice previews taking a while to appear.

---

Storage

Artefact	Location
Sprite sheets	{assets}/trickplay/{shard}/{mediaId}/{mediaFileId}/trickplay-{n}.jpg
Cue index	Built on demand, not stored on disk

All asset directories are sharded by parent media ID to keep the filesystem hierarchy shallow.

A title needs as many sheets as its duration calls for, numbered from zero, and the last one is padded out to a full grid. A very long title that would need more thumbnails than the cap allows gets a wider sampling interval instead, so the whole runtime is still covered.

The thumbnail on a Continue Watching card is cut from these sheets too, at the point where the viewer stopped. Each cut is cached as its own small tile-{n}.jpg beside the sheets, and the nightly cleanup removes any that are more than 30 days old; one that’s asked for again is cut again.

---

Caching

Trickplay is generated once and reused. If the sheets already exist and the status is Ready, there’s nothing more to do. While a job for a file is in flight, Sovereign won’t start a second one for it in the same server session.

Previews only appear once generation has finished. Until then the player’s seek readout says they’re queued or being generated, or that they’re unavailable if generation failed. Because the job waits out the start of playback, a title’s first play usually gains its previews a minute and a half or so in, and a title played a second time has them immediately.

---

Chapters and End Credits

The same pass reads two more things from the file, at no extra cost.

Chapters. When the container declares chapters, which roughly half of a typical film library does, Sovereign records where each one starts and what it’s called. The players mark them on the scrub bar and name the chapter under the seek preview. Nothing is guessed here: a file with no chapters keeps the plain bar.

Where the end credits begin. Sovereign also looks for the start of the end credits, using a chapter named for them where the file has one and the look of the frames where it doesn’t. When it finds them, the next-up panel (the next episode, or for a film what to watch next) appears over the credits while the film is still playing, instead of waiting for the stream to end. When it isn’t confident, it records nothing and the panel appears at the end as before.

Both arrive with the previews, so on a first play they show up partway through rather than at the start. A file whose previews were generated before Sovereign read chapters and credits keeps its existing previews and never gains either. Deleting that file’s trickplay directory makes the next play generate all three again.