GPU-accelerated video preview thumbnail generation for Plex Media Server
Explore the docs
Quick Start
·
Report Bug
·
Request Feature
Generates video preview thumbnails (BIF files) for Plex Media Server. These are the small images you see when scrubbing through videos in Plex.
The Problem: Plex's built-in preview generation is painfully slow.
The Solution: This tool uses GPU acceleration and parallel processing to generate previews 5-10x faster.
Note
This project was originally hand-written. Recent development is AI-assisted (Cursor + Claude). All changes are reviewed and tested.
| Feature | Description |
|---|---|
| Multi-GPU | NVIDIA, AMD, Intel, and Windows GPUs |
| Parallel Processing | Configurable GPU and CPU worker threads |
| GPU to CPU Fallback | Automatic in-place CPU retry when a GPU worker hits an unsupported codec |
| Hardware Acceleration | CUDA, VAAPI, D3D11VA, VideoToolbox |
| Library Filtering | Process specific Plex libraries |
| Quality Control | Adjustable thumbnail quality (1-10) |
| Docker Ready | Pre-built images with GPU support |
| Web Dashboard | Manage jobs, schedules, and status |
| Scheduling | Cron and interval-based automation |
| Smart Skipping | Automatically skips files that already have thumbnails |
| Radarr/Sonarr | Webhook integration for auto-processing on import |
| Plex direct webhook | Auto-trigger on library.new (Plex Pass) for media added without Sonarr/Radarr |
| Recently Added scanner | Polling fallback that catches manually-added items without Plex Pass |
| Home | Settings | Webhooks |
|---|---|---|
 |
 |
 |
Web UI: dashboard and job management, configuration and GPU detection, Radarr/Sonarr webhook setup.
docker run -d \
--name plex-generate-previews \
--restart unless-stopped \
-p 8080:8080 \
--device /dev/dri:/dev/dri \
-e PUID=1000 \
-e PGID=1000 \
-v /path/to/media:/media:ro \
-v /path/to/plex/config:/plex:rw \
-v /path/to/app/config:/config:rw \
-v /etc/localtime:/etc/localtime:ro \
stevezzau/plex_generate_vid_previews:latestReplace /path/to/media, /path/to/plex/config, and /path/to/app/config with your actual paths.
Timezone: The
/etc/localtimemount ensures log timestamps and scheduled jobs use your local time. Alternatively, use-e TZ=America/New_York(replace with your timezone).
Then open http://YOUR_IP:8080, retrieve the authentication token from container logs, and complete the setup wizard.
For Docker Compose, Unraid, and GPU-specific setup:
| Method | Best For | Guide |
|---|---|---|
| Docker | Most users, easy GPU setup | Getting Started |
| Docker Compose | Managed deployments | docker-compose.example.yml |
| Unraid | Unraid servers | Getting Started — Unraid |
- Web UI only: The Docker image runs the web interface. There is no CLI; all configuration and job management is done via the web UI.
- PyPI: The package is no longer published on PyPI; use Docker or install from source.
Important
The Docker Hub image is published as stevezzau/plex_generate_vid_previews (double-z):
stevezzau/plex_generate_vid_previews.
| Platform | Supported GPUs | Via |
|---|---|---|
| Linux (Docker) | NVIDIA, AMD, Intel | CUDA/NVENC, VAAPI, QuickSync |
| Windows (native) | NVIDIA, AMD, Intel | CUDA, D3D11VA |
| macOS (native) | Apple Silicon, Intel | VideoToolbox |
| Linux / Windows / macOS | No GPU | CPU workers only |
On Docker Desktop (Windows/WSL2 and macOS) the container runs inside a Linux VM, so D3D11VA and VideoToolbox aren't reachable — Docker on those platforms processes on CPU. For GPU acceleration on Windows or macOS, install from source.
See Getting Started — GPU Acceleration for per-vendor setup, tuning, and detection. Detected GPUs are shown in the web UI under Settings or Setup.
CPU fallback is automatic and built into every GPU worker — there is no separate "fallback" pool to configure. If FFmpeg fails on the GPU (unsupported codec, hardware-accelerator error, driver crash), the same worker retries the file on CPU in-place and the dashboard shows a yellow CPU fallback badge.
If you have a lot of content that never decodes on the GPU, raise CPU Workers above 0 so that those files route straight to dedicated CPU workers instead of blocking a GPU worker each time.
See Automatic GPU → CPU Fallback for details.
| Document | What's there |
|---|---|
| Documentation Hub | Pick the right doc for your task |
| Getting Started | Install with Docker, GPU setup, Unraid, networking |
| Guides | Web UI, schedules, webhooks, HDR handling, troubleshooting |
| Reference | Config options, env vars, REST API, WebSocket events |
| FAQ | Common questions about setup, performance, and compatibility |
Contributions are welcome. See CONTRIBUTING.md for local setup, tests, code style, and the PR workflow.
Distributed under the MIT License. See LICENSE for details.
- Plex for the media server
- FFmpeg for video processing
- LinuxServer.io for the Docker base image
- Rich for beautiful terminal output
- All contributors and users
Made with care by stevezau
Star this repo if you find it useful!