Animated thumbnails

Animated thumbnails return a short looping preview of a video instead of a single still frame. The rendering path exists in the codebase and runs on the test host, but it is gated off in production behind a flag and an allowed-hosts list.

Behavior

When enabled, a thumbnail request can be served as a short animated image rendered by a dedicated renderer Worker (a WASM-based animation pipeline) instead of a static JPEG. The thumbnail Worker calls the renderer over a service binding, caches the result in R2 like any other variant, and returns it.

Today:

• In production, ANIMATED_THUMBNAIL_ENABLED = 0, so requests always get the static JPEG.
• On the watermark-test.vumbnail.com host the feature is enabled for testing, with debug headers on.

Inputs & outputs

Inputs: a thumbnail request whose host is on the animated allowed-hosts list, with the feature flag enabled; the renderer service binding.

Outputs: an animated image variant stored in R2 (under a configurable namespace) and returned with the normal caching behavior; renderer error detail is exposed only to allow-listed hosts.

Controlling env vars (thumbnail Worker):

• ANIMATED_THUMBNAIL_ENABLED — 0 (off) in production.
• ANIMATED_THUMBNAIL_ALLOWED_HOSTS — comma-separated hostnames permitted to request animated output.
• ANIMATED_THUMBNAIL_ERROR_DETAIL_HOSTS — hosts allowed to see renderer error detail.
• ANIMATED_THUMBNAIL_R2_NAMESPACE — R2 path override for animated outputs.

States & edge cases

• Flag off (production default) — the animated path is never taken; static JPEG is served.
• Host not allow-listed — even with the flag on, a non-listed host gets the static image.
• Renderer failure — fails open to the static thumbnail; error detail is suppressed except for the error-detail hosts.
• Cost gating — turning this on broadly is a Cloudflare-spend change and therefore requires a written cost estimate first (see Design principles); container/WASM size has been a focus of research to keep it affordable.

Data shape

type AnimatedThumbnailConfig = {
  enabled: boolean              // ANIMATED_THUMBNAIL_ENABLED
  allowedHosts: string[]        // ANIMATED_THUMBNAIL_ALLOWED_HOSTS
  errorDetailHosts: string[]    // ANIMATED_THUMBNAIL_ERROR_DETAIL_HOSTS
  r2Namespace: string           // ANIMATED_THUMBNAIL_R2_NAMESPACE
}

// Rendered output is cached in R2 alongside clean/wm variants,
// under the configured animated namespace.

Open questions

• Productization. Whether animated previews become a paid add-on, which path shape exposes them (.gif/.webp vs. a query flag), and what the per-render cost ceiling is — all undecided.
• Demand gate. Broad rollout is blocked on demonstrated demand and a cost estimate. See the global Open questions.