Overview
When a video is uploaded, Zipline extracts a frame from the video and saves it as a thumbnail image. This allows users to see a preview of the video content in galleries and file listings.Configuration
Enable video thumbnails in your database configuration:- featuresThumbnailsEnabled: Enable/disable thumbnail generation
- featuresThumbnailsNumberThreads: Number of worker threads for processing
- featuresThumbnailsFormat: Output format (jpg, png, webp)
- tasksThumbnailsInterval: How often to check for videos needing thumbnails
- tasksCleanThumbnailsInterval: How often to clean up orphaned thumbnails
How It Works
Thumbnail Generation Process
Background Processing
A background task runs every 30 minutes (configurable) to find videos without thumbnails.
Implementation Reference
The thumbnail task scheduler is insrc/lib/tasks/run/thumbnails.ts:3:
Database Schema
Thumbnails are stored in theThumbnail model:
Worker Threads
Zipline uses worker threads to process thumbnails in parallel:Supported Video Formats
Thumbnails can be generated from any video format with MIME type starting withvideo/:
- MP4 (video/mp4)
- WebM (video/webm)
- AVI (video/x-msvideo)
- MOV (video/quicktime)
- MKV (video/x-matroska)
- FLV (video/x-flv)
- And more…
Thumbnail Formats
Thumbnails can be saved in multiple formats:JPEG
Default format, best compatibility and small file size
PNG
Lossless format, larger file size
WebP
Modern format with good compression
File Naming
Thumbnail files are stored with a prefix:- Original video:
abc123.mp4 - Thumbnail:
.thumbnail.clx1234567890.jpg
Thumbnail Cleanup
The cleanup task runs daily to remove orphaned thumbnails:API Access
Thumbnails are automatically included in file responses:Regenerating Thumbnails
To regenerate all thumbnails (e.g., after changing format or quality):Performance Considerations
Processing Time
Thumbnail generation time depends on:- Video length: Longer videos may take more time
- Video resolution: Higher resolution requires more processing
- Video codec: Some codecs are faster to decode
- Server CPU: More cores allow more parallel processing
- Short video (under 1 min, 720p): 1-3 seconds
- Medium video (5 min, 1080p): 3-5 seconds
- Long video (30 min, 4K): 5-10 seconds
Resource Usage
Worker threads consume:- CPU: Each worker uses 1 CPU core
- Memory: ~100-300MB per worker
- Disk I/O: Reading video files and writing thumbnails
Recommended thread count:
- 2-4 cores: 2 threads
- 4-8 cores: 4 threads
- 8+ cores: 6-8 threads
Storage Impact
Thumbnails add minimal storage overhead:- JPEG thumbnail (1920x1080): ~100-300KB
- PNG thumbnail (1920x1080): ~500KB-1MB
- WebP thumbnail (1920x1080): ~50-200KB
Troubleshooting
Thumbnails Not Generating
- Check that
featuresThumbnailsEnabledistrue - Verify worker threads are starting (check logs)
- Ensure ffmpeg is installed on the server
- Check file permissions on video files
- Look for errors in server logs
Poor Quality Thumbnails
- Increase thumbnail resolution settings
- Change format from JPG to PNG
- Extract a frame from later in the video
- Verify the source video quality is good
High CPU Usage
- Reduce
featuresThumbnailsNumberThreads - Increase
tasksThumbnailsIntervalto process less frequently - Limit maximum video file size
- Consider processing during off-peak hours
Orphaned Thumbnails
- Run the cleanup task manually
- Reduce
tasksCleanThumbnailsIntervalto clean more often - Check for errors in the cleanup task logs
- Verify database and filesystem are in sync