Plex Generate Previews

GPU-accelerated video preview thumbnail generation for Plex Media Server
Explore the docs

Quick Start · Report Bug · Request Feature

---

About

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.

---

Features

Feature	Description
Multi-GPU	NVIDIA, AMD, Intel, and Windows GPUs
Parallel Processing	Configurable GPU and CPU worker threads
GPU to 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
Smart Skipping	Automatically skips files that already have thumbnails
Radarr/Sonarr	Webhook integration for auto-processing on import

---

Screenshots

Home	Settings	Webhooks

Web UI: dashboard and job management, configuration and GPU detection, Radarr/Sonarr webhook setup.

---

Quick Start

Docker (Recommended)

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:latest

Replace /path/to/media, /path/to/plex/config, and /path/to/app/config with your actual paths.

Timezone: The /etc/localtime mount 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:

• Getting Started
• Configuration & API Reference

---

Installation

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

Note the extra "z" in Docker Hub: stevezzau/plex_generate_vid_previews (stevezau was taken)

---

GPU Support

GPU Type	Platform	Acceleration	Docker
NVIDIA	Linux	CUDA/NVENC	--gpus all
AMD	Linux	VAAPI	--device /dev/dri
Intel	Linux	QuickSync/VAAPI	--device /dev/dri
NVIDIA	Windows	CUDA	Native only
AMD/Intel	Windows	D3D11VA	Native only
Apple Silicon	macOS	VideoToolbox	Native only

"Native only" means GPU acceleration requires running the app from source on that platform. Docker on Windows (WSL2) and macOS runs a Linux VM — D3D11VA and VideoToolbox are not available inside Docker. Docker on these platforms will use CPU-only processing. Apple Silicon users benefit from the native ARM64 Docker image (no Rosetta overhead).

For complete GPU setup, tuning, and troubleshooting:

• Getting Started — GPU Acceleration
• Guides & Troubleshooting

Check detected GPUs: Open the web UI (http://YOUR_IP:8080) and go to Settings or Setup — detected GPUs are shown there.

GPU + CPU Fallback Mode

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.

---

Documentation

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

---

Built With

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

Distributed under the MIT License. See LICENSE for details.

---

Acknowledgments

• 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!