GPU-accelerated video preview thumbnail generation for Plex Media Server
Explore the docs »
Quick Start
·
Report Bug
·
Request Feature
📑 Table of Contents
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.
| Feature | Description |
|---|---|
| 🚀 Multi-GPU | NVIDIA, AMD, Intel, and Windows GPUs |
| ⚡ Parallel Processing | Configurable GPU and CPU worker threads |
| 🔁 GPU→CPU Fallback | Optional fallback-only CPU workers for GPU decode failures |
| 🎮 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 |
| 📡 Radarr/Sonarr | Webhook integration for auto-processing on import |
| 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 \
stevezzau/plex_generate_vid_previews:latestThen 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 |
- CLI: The command-line interface still works when run inside the container or from source; we recommend using the Docker image and Web UI for normal use.
- PyPI: The package is no longer published on PyPI; use Docker or install from source.
Important
Note the extra "z" in Docker Hub: stevezzau/plex_generate_vid_previews (stevezau was taken)
| GPU Type | Platform | Acceleration | Docker |
|---|---|---|---|
| NVIDIA | Linux | CUDA/NVENC | --gpus all |
| AMD | Linux | VAAPI | --device /dev/dri |
| Intel | Linux | QuickSync/VAAPI | --device /dev/dri |
| All | Windows | D3D11VA | Native only |
| Apple Silicon | macOS | VideoToolbox | Native only |
For complete GPU setup, tuning, and troubleshooting:
Check detected GPUs: Open the web UI (http://YOUR_IP:8080) and go to Settings or Setup — detected GPUs are shown there.
If you want GPU-only main processing but still want CPU recovery for unsupported files:
- Set CPU Workers to
0 - Set CPU Fallback Workers to
1(or higher)
This keeps normal jobs on GPU workers and only uses CPU when a GPU worker reports an unsupported codec/runtime decode failure.
Note
CPU Fallback Workers is only used when CPU Workers=0.
If CPU Workers>0, regular CPU workers already handle fallback work.
| Document | Description |
|---|---|
| 📖 Documentation Hub | Start here — architecture diagrams |
| ⚡ Getting Started | Docker, GPU, Unraid, devcontainer |
| ⚙️ Reference | Configuration options & REST API |
| 📘 Guides | Web interface, webhooks, FAQ, troubleshooting |
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for details.
- Plex for the amazing media server
- FFmpeg for video processing
- LinuxServer.io for the Docker base image
- Rich for beautiful terminal output
- All contributors and users
Made with ❤️ by stevezau
⭐ Star this repo if you find it useful!