Thumbnails — how generated
Thumbnails: images proxied from Drive thumbnail link (~800px). Videos: FFmpeg frame at t=0.5s scaled to 400px, cached in S3. Endpoint /thumbnail/:fileId. In-memory + S3 cache.
Written By Salvatore Sinigaglia
Last updated About 4 hours ago
Thumbnails: images proxied from Drive thumbnail link (~800px). Videos: FFmpeg frame at t=0.5s scaled to 400px, cached in S3. Endpoint /thumbnail/:fileId. In-memory + S3 cache.
Thumbnails — how generated
Images: served by proxying Google Drive's own thumbnail link (up to ~800px). Videos: FFmpeg extracts a frame at t=0.5s and scales it to 400px wide as the poster, cached in S3. Requests go through an in-memory cache, then (for videos) an S3 cache, then FFmpeg generation on a miss. Endpoint:
GET /api/v1/creative-hub/thumbnail/:fileId. First view of a new video may take a few seconds to render the poster; 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 cache
When the UI requests a thumbnail via GET /api/v1/creative-hub/thumbnail/:fileId:
The in-memory cache is bounded; S3 is the long-term store for video posters; FFmpeg is the fallback for videos.
Image thumbnails
For images (PNG / JPG / WebP / GIF):
- Source: Google Drive's own thumbnail link for the file (Wevion proxies it, requesting a larger size — up to ~800px)
- No FFmpeg step for images
- 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 seeks to t=0.5s and extracts a single frame
- Scaled to 400px wide
- Cached in S3 and used as the
<video>poster (shown before play)
For a video that is black or empty in its first half-second: the poster may be unhelpful — consider picking a different frame outside Wevion + uploading it as a separate image.
Cache lifecycle
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
Video streaming is separate
The thumbnail endpoint returns only a still poster image — it does not stream video or support HTTP Range. Video playback fetches the file bytes from the separate content endpoint (/files/:fileId/content). 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: the t=0.5s frame 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
FAQ
When does Wevion generate a thumbnail?
For images, Wevion proxies Google Drive's own thumbnail link, so there's no lazy FFmpeg step. For videos, the poster is generated lazily — the first request runs FFmpeg on a cache miss (a few seconds), then stores the poster in S3. Requests flow through an in-memory cache (under 10 ms) and, for videos, an S3 cache (50-200 ms). So the first view of a new video can take a few seconds, while subsequent views are fast.
What resolution and frame does Wevion use for thumbnails?
Image thumbnails are proxied from Drive's thumbnail link at a larger size (up to ~800px), with the full-resolution original fetched separately for "view original" mode. For videos, FFmpeg seeks to t=0.5s and extracts a single frame as the poster, scaled to 400px wide, then caches it in S3.
Why is a video's thumbnail black?
The frame at t=0.5s that Wevion extracts happened to be black or empty, which can occur on videos that open on a dark scene. There is no manual frame picker in the UI to fix this. As a workaround, pick a different frame outside Wevion and upload it as a separate image to use as the visual.
Why is my thumbnail still outdated after re-uploading the file?
Video posters are keyed by the file's Drive id, not by name, so a re-upload keeping the same id can serve a stale cached poster until it is invalidated. This is cache invalidation lag — force-reload the page or wait, and the regenerated poster will appear. Renaming a file never affects the cache, since the key is the file id.