{"id":34054902,"url":"https://github.com/stevezau/plex_generate_vid_previews","last_synced_at":"2026-04-15T02:06:29.132Z","repository":{"id":39656252,"uuid":"485100230","full_name":"stevezau/plex_generate_vid_previews","owner":"stevezau","description":"GPU-accelerated video preview thumbnail (BIF) generation for Plex Media Server. Docker-ready with NVIDIA/AMD/Intel support, web UI, scheduling, and Radarr/Sonarr webhooks.","archived":false,"fork":false,"pushed_at":"2026-04-10T11:03:10.000Z","size":2236,"stargazers_count":203,"open_issues_count":4,"forks_count":31,"subscribers_count":5,"default_branch":"dev","last_synced_at":"2026-04-10T11:11:36.188Z","etag":null,"topics":["bif","docker","ffmpeg","hardware-acceleration","media-server","media-server-automation","nvidia-gpu","plex","plex-media-server","thumbnails","thumbnails-preview","unraid","video-previews"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/stevezzau/plex_generate_vid_previews","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stevezau.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-24T17:55:59.000Z","updated_at":"2026-04-10T11:03:14.000Z","dependencies_parsed_at":"2023-01-17T21:31:38.313Z","dependency_job_id":"29c2742a-8cdb-4e9c-aefd-c5a5382ad626","html_url":"https://github.com/stevezau/plex_generate_vid_previews","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/stevezau/plex_generate_vid_previews","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevezau%2Fplex_generate_vid_previews","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevezau%2Fplex_generate_vid_previews/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevezau%2Fplex_generate_vid_previews/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevezau%2Fplex_generate_vid_previews/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stevezau","download_url":"https://codeload.github.com/stevezau/plex_generate_vid_previews/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevezau%2Fplex_generate_vid_previews/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31822906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bif","docker","ffmpeg","hardware-acceleration","media-server","media-server-automation","nvidia-gpu","plex","plex-media-server","thumbnails","thumbnails-preview","unraid","video-previews"],"created_at":"2025-12-14T02:31:55.381Z","updated_at":"2026-04-15T02:06:29.125Z","avatar_url":"https://github.com/stevezau.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003c!-- PROJECT SHIELDS --\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n[![Docker Pulls][docker-shield]][docker-url]\n[![codecov][codecov-shield]][codecov-url]\n[![AI-Assisted][ai-shield]][ai-url]\n\n\u003c/div\u003e\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/icon.svg\" alt=\"Logo\" width=\"120\" height=\"120\"\u003e\n\n  \u003ch1 align=\"center\"\u003ePlex Generate Previews\u003c/h1\u003e\n\n  \u003cp align=\"center\"\u003e\n    GPU-accelerated video preview thumbnail generation for Plex Media Server\n    \u003cbr /\u003e\n    \u003ca href=\"docs/README.md\"\u003e\u003cstrong\u003eExplore the docs\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/stevezau/plex_generate_vid_previews/issues/new?labels=bug\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/stevezau/plex_generate_vid_previews/issues/new?labels=enhancement\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## About\n\nGenerates video preview thumbnails (BIF files) for Plex Media Server. These are the small images you see when scrubbing through videos in Plex.\n\n**The Problem:** Plex's built-in preview generation is painfully slow.\n\n**The Solution:** This tool uses GPU acceleration and parallel processing to generate previews **5-10x faster**.\n\n\u003e [!NOTE]\n\u003e This project was originally hand-written. Recent development is AI-assisted (Cursor + Claude). All changes are reviewed and tested.\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Multi-GPU** | NVIDIA, AMD, Intel, and Windows GPUs |\n| **Parallel Processing** | Configurable GPU and CPU worker threads |\n| **GPU to CPU Fallback** | Optional fallback-only CPU workers for GPU decode failures |\n| **Hardware Acceleration** | CUDA, VAAPI, D3D11VA, VideoToolbox |\n| **Library Filtering** | Process specific Plex libraries |\n| **Quality Control** | Adjustable thumbnail quality (1-10) |\n| **Docker Ready** | Pre-built images with GPU support |\n| **Web Dashboard** | Manage jobs, schedules, and status |\n| **Scheduling** | Cron and interval-based automation |\n| **Smart Skipping** | Automatically skips files that already have thumbnails |\n| **Radarr/Sonarr** | Webhook integration for auto-processing on import |\n| **Plex direct webhook** | Auto-trigger on `library.new` (Plex Pass) for media added without Sonarr/Radarr |\n| **Recently Added scanner** | Polling fallback that catches manually-added items without Plex Pass |\n\n---\n\n## Screenshots\n\n| Home | Settings | Webhooks |\n|:----:|:--------:|:--------:|\n| [![Home](docs/images/home.png)](docs/images/home.png) | [![Settings](docs/images/settings.png)](docs/images/settings.png) | [![Webhooks](docs/images/webhooks.png)](docs/images/webhooks.png) |\n\n*Web UI: dashboard and job management, configuration and GPU detection, Radarr/Sonarr webhook setup.*\n\n---\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\ndocker run -d \\\n  --name plex-generate-previews \\\n  --restart unless-stopped \\\n  -p 8080:8080 \\\n  --device /dev/dri:/dev/dri \\\n  -e PUID=1000 \\\n  -e PGID=1000 \\\n  -v /path/to/media:/media:ro \\\n  -v /path/to/plex/config:/plex:rw \\\n  -v /path/to/app/config:/config:rw \\\n  -v /etc/localtime:/etc/localtime:ro \\\n  stevezzau/plex_generate_vid_previews:latest\n```\n\nReplace `/path/to/media`, `/path/to/plex/config`, and `/path/to/app/config` with your actual paths.\n\n\u003e **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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)).\n\nThen open `http://YOUR_IP:8080`, retrieve the authentication token from container logs, and complete the setup wizard.\n\nFor Docker Compose, Unraid, and GPU-specific setup:\n\n- [Getting Started](docs/getting-started.md)\n- [Configuration \u0026 API Reference](docs/reference.md)\n\n---\n\n## Installation\n\n| Method | Best For | Guide |\n|--------|----------|-------|\n| **Docker** | Most users, easy GPU setup | [Getting Started](docs/getting-started.md) |\n| **Docker Compose** | Managed deployments | [docker-compose.example.yml](docker-compose.example.yml) |\n| **Unraid** | Unraid servers | [Getting Started — Unraid](docs/getting-started.md#unraid) |\n\n- **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.\n- **PyPI:** The package is no longer published on PyPI; use Docker or install from source.\n\n\u003e [!IMPORTANT]\n\u003e Note the extra \"z\" in Docker Hub: [stevezzau/plex_generate_vid_previews](https://hub.docker.com/r/stevezzau/plex_generate_vid_previews)\n\u003e (stevezau was taken)\n\n---\n\n## GPU Support\n\n| GPU Type | Platform | Acceleration | Docker |\n|----------|----------|--------------|--------|\n| **NVIDIA** | Linux | CUDA/NVENC | `--gpus all` |\n| **AMD** | Linux | VAAPI | `--device /dev/dri` |\n| **Intel** | Linux | QuickSync/VAAPI | `--device /dev/dri` |\n| **NVIDIA** | Windows | CUDA | Native only |\n| **AMD/Intel** | Windows | D3D11VA | Native only |\n| **Apple Silicon** | macOS | VideoToolbox | Native only |\n\n\u003e **\"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).\n\nFor complete GPU setup, tuning, and troubleshooting:\n\n- [Getting Started — GPU Acceleration](docs/getting-started.md#gpu-acceleration)\n- [Guides \u0026 Troubleshooting](docs/guides.md#troubleshooting)\n\n**Check detected GPUs:** Open the web UI (http://YOUR_IP:8080) and go to **Settings** or **Setup** — detected GPUs are shown there.\n\n### GPU + CPU Fallback Mode\n\nIf you want GPU-only main processing but still want CPU recovery for unsupported files:\n\n- Set **CPU Workers** to `0`\n- Set **CPU Fallback Workers** to `1` (or higher)\n\nThis keeps normal jobs on GPU workers and only uses CPU when a GPU worker reports an unsupported codec/runtime decode failure.\n\n\u003e [!NOTE]\n\u003e `CPU Fallback Workers` is only used when `CPU Workers=0`.\n\u003e If `CPU Workers\u003e0`, regular CPU workers already handle fallback work.\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Documentation Hub](docs/README.md) | Start here — architecture diagrams |\n| [Getting Started](docs/getting-started.md) | Docker, GPU, Unraid, devcontainer |\n| [Reference](docs/reference.md) | Configuration options \u0026 REST API |\n| [Guides](docs/guides.md) | Web interface, webhooks, FAQ, troubleshooting |\n\n---\n\n## Built With\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python][python-shield]][python-url]\n[![Docker][docker-tech-shield]][docker-tech-url]\n[![FFmpeg][ffmpeg-shield]][ffmpeg-url]\n[![Flask][flask-shield]][flask-url]\n[![Gunicorn][gunicorn-shield]][gunicorn-url]\n\n\u003c/div\u003e\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## License\n\nDistributed under the MIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Acknowledgments\n\n- [Plex](https://www.plex.tv/) for the media server\n- [FFmpeg](https://ffmpeg.org/) for video processing\n- [LinuxServer.io](https://www.linuxserver.io/) for the Docker base image\n- [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- All contributors and users\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nMade with care by [stevezau](https://github.com/stevezau)\n\nStar this repo if you find it useful!\n\n\u003c/div\u003e\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/stevezau/plex_generate_vid_previews.svg?style=for-the-badge\n[contributors-url]: https://github.com/stevezau/plex_generate_vid_previews/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/stevezau/plex_generate_vid_previews.svg?style=for-the-badge\n[forks-url]: https://github.com/stevezau/plex_generate_vid_previews/network/members\n[stars-shield]: https://img.shields.io/github/stars/stevezau/plex_generate_vid_previews.svg?style=for-the-badge\n[stars-url]: https://github.com/stevezau/plex_generate_vid_previews/stargazers\n[issues-shield]: https://img.shields.io/github/issues/stevezau/plex_generate_vid_previews.svg?style=for-the-badge\n[issues-url]: https://github.com/stevezau/plex_generate_vid_previews/issues\n[license-shield]: https://img.shields.io/github/license/stevezau/plex_generate_vid_previews.svg?style=for-the-badge\n[license-url]: https://github.com/stevezau/plex_generate_vid_previews/blob/main/LICENSE\n[docker-shield]: https://img.shields.io/docker/pulls/stevezzau/plex_generate_vid_previews?style=for-the-badge\n[docker-url]: https://hub.docker.com/r/stevezzau/plex_generate_vid_previews\n[codecov-shield]: https://img.shields.io/codecov/c/github/stevezau/plex_generate_vid_previews?style=for-the-badge\n[codecov-url]: https://codecov.io/gh/stevezau/plex_generate_vid_previews\n\n[ai-shield]: https://img.shields.io/badge/AI--Assisted-Cursor%20%2B%20Claude-blue?style=for-the-badge\u0026logo=openai\u0026logoColor=white\n[ai-url]: #about\n\n[python-shield]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\n[python-url]: https://python.org\n[docker-tech-shield]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white\n[docker-tech-url]: https://docker.com\n[ffmpeg-shield]: https://img.shields.io/badge/FFmpeg-007808?style=for-the-badge\u0026logo=ffmpeg\u0026logoColor=white\n[ffmpeg-url]: https://ffmpeg.org\n[flask-shield]: https://img.shields.io/badge/Flask-000000?style=for-the-badge\u0026logo=flask\u0026logoColor=white\n[flask-url]: https://flask.palletsprojects.com\n[gunicorn-shield]: https://img.shields.io/badge/Gunicorn-499848?style=for-the-badge\u0026logo=gunicorn\u0026logoColor=white\n[gunicorn-url]: https://gunicorn.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevezau%2Fplex_generate_vid_previews","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevezau%2Fplex_generate_vid_previews","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevezau%2Fplex_generate_vid_previews/lists"}