Replace standard browser-based thumbnails with high-performance, server-side generated previews. Supports modern image formats (WebP) and live video frames.
This plugin solves the "loading lag" caused by generating thumbnails in the browser, especially for video files.
- ⚡ Zero-Lag Frontend: Generates static images on the server. Your browser downloads tiny WebP images instead of decoding massive video files.
- 🎥 Video Frame Extraction: Uses FFmpeg to extract a representative frame from valid video files (seeking past the intro black screen).
- 🖼️ Smart Resizing: Uses Sharp to create high-quality, aspect-ratio-preserved thumbnails that fit perfectly within your grid.
- 🕸️ WebP Format: Serves next-gen WebP images for ~30% smaller file sizes compared to JPEGs, saving bandwidth.
- 🔒 Concurrency Control: Built-in Task Queue limits the number of parallel FFmpeg processes to prevent server CPU overload (Configurable).
- 💾 File-Based Caching: Persists generated thumbnails to
~/.hfs/plugins/better-thumbnails/storage, keeping the main database clean and improving load speeds. - 🛠️ Extended Support: Native frame extraction for
mp4,mkv,avi,mov,wmv,flv,webm,ts, andm4v.
- Go to your HFS Admin Panel.
- Navigate to Plugins -> Search online.
- Search for
better-thumbnails. - Click Install.
- Download the
distfolder from this repository. - Place it inside your HFS
pluginsdirectory - Rename
distfolder tobetter-thumbnails - Restart HFS or reload plugins.
Get the most out of the plugin in 30 seconds:
- Install FFmpeg: Ensure FFmpeg is installed on your system.
- Link Path: In Admin Panel > Plugins > better-thumbnails, set the FFmpeg Executable Path to the location of your
ffmpeg.exe(e.g.C:\ffmpeg\bin\ffmpeg.exe). - Optimize Performance: If you have a powerful server, increase Max Concurrent Generations to
8for faster bulk generation. On weaker VPS/Pi, keep it at2-4.
Settings are organized in Admin Panel > Plugins > better-thumbnails.
| Setting | Description | Default |
|---|---|---|
| Pixels | Max dimension (width/height) of the generated image. Images are resized to fit relative to this box. | 256 |
| Quality | WebP Compression Quality (1-100). Lower values reduce file size but may artifact. | 60 |
| Setting | Description | Default |
|---|---|---|
| Max Concurrent Generations | Limit parallel FFmpeg/Sharp processes. Prevents CPU spikes during folder scans. | 4 |
| FFmpeg Executable Path | Required. Absolute path to ffmpeg binary. |
Empty |
| Log Generation | Print console messages for every generated thumbnail. Useful for debugging. | Off |
| Error/Event | Description | Solution(s) |
|---|---|---|
| Thumbnails not showing | General failure to load image. | 1. Check FFmpeg Path. 2. Clear browser cache. 3. Check plugins/better-thumbnails/storage permissions. |
| "Server Error" (500) | Backend crash during generation. | Enable Log Generation to see the error. Usually a corrupt video file. |
| Large Images Fail | "Image too large (>100MB)" error. | Plugin strictly rejects source images >100MB to prevent RAM exhaustion. |
| Error/Event | Description | Solution(s) |
|---|---|---|
| High CPU Usage | Server fans spinning up. | Reduce Max Concurrent Generations to 1 or 2. |
| Slow Loading | Thumbnails appear one by one slowly. | Normal on first visit. Second visit uses cached files (Instant). |
This plugin works as an on-demand generation pipeline:
- Intercept: Listens for requests with
?get=thumb. - Hash: Calculates a unique MD5 hash based on
Filename + Timestamp + Dimensions + Quality. - Cache Lookup: Checks
storage/thumbnails/[HASH].webp.- Hit: Serves file immediately (Zero CPU).
- Miss: Pushes task to FIFO Queue.
- Worker Processing:
- Video:
FFmpegseeks to 1s -> Extracts Frame -> Pipes toSharp. - Image: Pipes Source ->
Sharp. - Sharp: Resize -> Rotate (EXIF) -> Convert to WebP.
- Video:
- Finalize: Writes to disk cache and streams to client.
- hfs-thumbnails: Thanks to @rejetto for the original code of hfs-thumbnails this plugin is improved upon.