Trickplay

Trickplay generates thumbnail sprite sheets that appear when you hover over or scrub the seek bar, giving you a visual preview of each position in the video.

How it works

The server generates a single JPEG sprite sheet containing thumbnails at regular intervals:

Setting	Value
Interval	Every 10 seconds
Thumbnail size	640 x 360 pixels
Grid layout	5 columns
Max rows	20 (up to 100 thumbnails per sprite)

For a 2-hour movie, this produces approximately 720 thumbnails arranged in a grid on a single JPEG image. The player maps your seek position to the correct tile on the sprite.

Generation

Trickplay sprites are generated on demand — the first time you seek through a video, the server creates the sprite sheet and caches it. Subsequent requests serve the cached version instantly.

Cache location

Sprites are stored in DUBBY_TRICKPLAY_CACHE_DIR (defaults to DUBBY_DATA_DIR/trickplay):

<trickplay-dir>/
├── movie/
│   └── <movieId>/
│       └── sprite_640x360.jpg
└── episode/
    └── <episodeId>/
        └── sprite_640x360.jpg

Once generated, sprites are served with a 1-year cache header (Cache-Control: public, max-age=31536000, immutable).

Concurrent requests

If multiple users seek through the same video simultaneously while the sprite is being generated, only one FFmpeg process runs. Additional requests wait for the first generation to complete.

Regenerating sprites

Admins can force-regenerate a sprite if the cached version is corrupted or if the source file has changed:

curl -X POST http://localhost:3000/api/trickplay/movie/{mediaId}/regenerate \
  -H "Authorization: Bearer $TOKEN"

Storage

Each sprite sheet is typically 2-10 MB depending on the video duration. For a library of 500 movies, expect roughly 1-5 GB of trickplay data.

Limitations

• Trickplay is unavailable while a file is actively being transcoded (returns 503 to avoid disk I/O contention)
• Very long media (e.g., 10+ hour recordings) may take a minute to generate the first sprite