Skip to content

Posters and storyboards

A poster is the image shown before a video plays. A storyboard is the strip of thumbnails shown when a viewer hovers or drags the player's seek bar. Both are generated automatically for every video; posters can also be managed by hand.

Auto-generated posters

When a video is processed, one poster is captured, at the middle of its duration. It is chosen as the most representative frame from ~50 candidate frames starting at that point, so fades, scene cuts, and black frames are skipped — a video never ends up fronted by a blank frame. That poster becomes the default (the one the player actually shows).

To use a different frame, capture one from the video yourself on the Video Edit → Posters page, or upload your own image.

Managing posters

On the Video Edit → Posters page you can upload a poster image, capture a poster from the video itself (scrub the preview to the frame you want and press Use current frame), pick the default from the poster gallery, and delete posters.

  • Upload: POST …/video/<video_id>/poster ⧉ — a multipart form with a file field. Any common image format, up to 10 MB; it is stored as an optimized JPEG. The upload does not become the default automatically.
  • Set the default: pass default_poster_id to the edit video endpoint.
  • Delete: DELETE …/poster/<poster_id> ⧉ — the default poster can't be deleted; make another poster the default first.
  • Read: request the video with ?include=posters — each poster carries id, cdn_link (a signed URL, 24-hour expiry), and default.

A video can have at most 20 posters, and posters can't be added to a video whose processing failed (422 video_errored).

Storyboards

Storyboards are generated automatically during encoding: a WebVTT file that maps time ranges to tiles in one or more JPEG sprite sheets. By default one tile is captured every 7 seconds (each tile again picked as the most representative of several candidate frames). Very long videos widen the interval instead of growing without bound — full 7-second granularity is kept up to roughly 3-hour videos.

Storyboards power the player's scrub preview and the audience-retention hover preview in the dashboard. There is nothing to configure and no write API:

  • Read them with ?include=storyboards — each carries id, vtt_link (a signed URL to the .vtt, which references the sprite sheets), and default.
  • The player's scrub preview can be toggled per player with the storyboard control setting.