Thumbnails — how generated

Last updated: May 19, 2026

Thumbnails — how generated

Wevion generates thumbnails lazily — first preview request triggers FFmpeg if cache miss. Images: 320 px and 640 px variants. Videos: FFmpeg extracts a frame at t=1s as poster. 3-tier cache: in-memory (hot) → S3 (cold) → FFmpeg generation. First view of a new file may take 5-30 seconds to render the thumbnail; subsequent views are fast.

Who is this for

Anyone noticing slow thumbnail rendering. Also: anyone wondering why thumbnails sometimes look different from the source file (resolution / frame choice).

The 3-tier cache

When the UI requests a thumbnail via GET /api/v1/creative-hub/media/:fileId/thumbnail:

Tier

Latency

What happens

Tier 1 — in-memory

< 10 ms

Server has the thumbnail in process memory (recent / hot) — instant return

Tier 2 — S3 cache

50-200 ms

Thumbnail was generated previously + stored in S3; fetched + returned

Tier 3 — FFmpeg generation

5-30 sec

First request OR S3 cache evicted; FFmpeg generates on-demand, stores to S3, returns

In-memory cache is bounded (LRU-style); S3 is the long-term store; FFmpeg is the fallback.

Image thumbnails

For images (PNG / JPG / WebP / GIF):

  • Source: the original file

  • Variants: 320 px wide (grid view) + 640 px wide (preview modal)

  • Format: JPEG (compressed; smaller download)

  • Aspect ratio preserved

The full-resolution original is fetched separately for the preview modal's "view original" mode.

Video thumbnails (poster frames)

For videos (MP4 / MOV / WebM):

  • FFmpeg extracts a frame at t=1s (avoids black frames at t=0 for many encodings)

  • Resized to 320 / 640 px width

  • Format: JPEG

  • Used as <video> poster attribute (shown before play)

For long videos with a black or empty first second: thumbnail may be unhelpful — consider manually picking a different frame outside Wevion + uploading as a separate image.

Cache lifecycle

Event

Effect

First preview request

Tier 3: FFmpeg generates, stores to Tier 2 (S3)

Subsequent requests

Tier 2 or Tier 1 hit (fast)

In-memory cache eviction

LRU — least recently used dropped first

S3 cache TTL

Long (days / months); periodic cleanup of orphans

File renamed

Thumbnail keyed by file_id, NOT name → cache unaffected

File re-uploaded with new content

Same file_id → cache served stale until invalidated; re-upload regenerates

When thumbnails differ from source

  • Color shift: JPEG compression vs PNG source (acceptable for grid display)

  • Crop: some grid views render square — thumbnail aspect preserved, but UI crops display

  • Video poster doesn't match preview: poster = t=1s frame; preview shows current scrub position

HTTP Range support

For videos, the thumbnail endpoint also serves the video stream when client requests with Range header (browser does this automatically for <video> tags). See ch-107 preview for the streaming + scrub flow.

Failure modes

FFmpeg fails

Causes:

  • Unsupported codec (rare on common formats; common on exotic ones)

  • Corrupted file

  • Out of memory (very large videos, server load)

Result: thumbnail returns 500 or stays "Generating..." in UI. File may still be downloadable; you just won't see a thumbnail.

Fix: re-upload with a supported format (MP4 H.264 most reliable), or convert externally first.

Cache evicted, regeneration slow

If you don't view a thumbnail for months and the S3 cache TTL has passed: next view triggers FFmpeg again (5-30 sec). Subsequent views fast again.

File deleted

Thumbnail endpoint returns 404 for deleted files. UI shows broken thumbnail icon.

Performance tips

Compress videos before upload

Smaller videos = faster FFmpeg generation = faster first preview. Use H.264 MP4 1080p typical.

Avoid uploading 4K videos for grid display

Wevion's thumbnails are 640 px max. 4K source adds upload time + generation time with no quality gain in the grid.

Prefer images for grid-heavy folders

Folders with 100+ items: image thumbnails are nearly instant; video thumbnails benefit from FFmpeg pre-warming as you scroll.

Common issues

  • "Generating thumbnail..." stuck > 30 sec: FFmpeg failure; re-upload or convert format

  • Thumbnail blurry: compression artifact in JPEG; original is fine — only the thumbnail is compressed

  • Black thumbnail for video: t=1s happened to be black; not fixable from UI (no manual frame picker)

  • Outdated thumbnail after re-upload: cache invalidation lag; force-reload page or wait

Related