plex-generate-previews

Name	plex-generate-previews JSON
Version	2.3.0 JSON
	download
home_page	None
Summary	Generate video preview thumbnails for Plex Media Server
upload_time	2025-10-16 09:28:28
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	None
keywords	plex media server video thumbnails previews ffmpeg gpu acceleration
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # [stevezau/plex_generate_vid_previews](https://github.com/stevezau/plex_generate_vid_previews/)

[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/stevezau/plex_generate_vid_previews)
[![Python](https://img.shields.io/badge/python-3.7+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-available-blue.svg)](https://hub.docker.com/repository/docker/stevezzau/plex_generate_vid_previews)
[![codecov](https://codecov.io/gh/stevezau/plex_generate_vid_previews/branch/main/graph/badge.svg)](https://codecov.io/gh/stevezau/plex_generate_vid_previews)

## Table of Contents

- [What This Tool Does](#what-this-tool-does)
- [Quick Start](#quick-start)
- [Features](#features)
- [Requirements](#requirements)
- [Installation Options](#installation-options)
  - [Docker](#docker)
  - [Pip Installation](#pip-installation)
  - [Unraid](#unraid)
- [Configuration](#configuration)
  - [Command-line Arguments](#command-line-arguments)
  - [Environment Variables](#environment-variables)
- [GPU Support](#gpu-support)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)

## What This Tool Does

Generates video preview thumbnails for Plex Media Server using GPU acceleration and parallel processing. Plex's built-in preview generation is slow - this tool makes it much faster.

Preview thumbnails are the small images you see when scrubbing through videos in Plex.

## Quick Start

**Before you begin, you'll need:**
1. A Plex Media Server running and accessible
2. Your Plex authentication token ([how to get it](https://support.plex.tv/articles/204059436/))
3. The path to your Plex config folder

**Docker (easiest):**
```bash
# 1. Check your GPUs
docker run --rm stevezzau/plex_generate_vid_previews:latest --list-gpus

# 2. Run with your details (using environment variables)
docker run --rm --gpus all \
  -e PLEX_URL=http://localhost:32400 \
  -e PLEX_TOKEN=your-token-here \
  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\ Support/Plex\ Media\ Server \
  -v /path/to/your/plex/config:/config/plex \
  -v /path/to/your/media:/media \
  stevezzau/plex_generate_vid_previews:latest

# Or use CLI arguments instead (both work)
docker run --rm --gpus all \
  -v /path/to/your/plex/config:/config/plex \
  -v /path/to/your/media:/media \
  stevezzau/plex_generate_vid_previews:latest \
  --plex-url http://localhost:32400 \
  --plex-token your-token-here \
  --plex-config-folder /config/plex/Library/Application\ Support/Plex\ Media\ Server
```

**Pip (local install):**
```bash
# 1. Install
pip install git+https://github.com/stevezau/plex_generate_vid_previews.git

# 2. Check your GPUs
plex-generate-previews --list-gpus

# 3. Run with your details
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token your-token-here \
  --plex-config-folder /path/to/your/plex/Library/Application\ Support/Plex\ Media\ Server
```

## Features

- **Multi-GPU Support**: NVIDIA, AMD, Intel, and WSL2 GPUs
- **Parallel Processing**: Configurable GPU and CPU worker threads
- **Hardware Acceleration**: CUDA, VAAPI, and D3D11VA
- **Library Filtering**: Process specific Plex libraries
- **Quality Control**: Adjustable thumbnail quality (1-10)
- **Docker Support**: Pre-built images with GPU acceleration
- **Command-line Interface**: CLI arguments and environment variables

## Requirements

- **Plex Media Server**: Running and accessible
- **FFmpeg 7.0+**: For video processing and hardware acceleration
- **Python 3.7+**: For local installation
- **Docker**: For containerized deployment (optional)

### Platform Support

| Platform | Support | Notes |
|----------|---------|-------|
| **Linux** | ✅ Full | GPU + CPU support (CUDA, VAAPI, etc.) |
| **Docker** | ✅ Full | GPU + CPU support (Recommended) |
| **WSL2** | ✅ Full | GPU + CPU support (D3D11VA, VAAPI) |
| **macOS** | ✅ Full | VideoToolbox + CPU support |
| **Windows** | ✅ Full | D3D11VA GPU + CPU support |

**Windows GPU Support:**
- ✅ D3D11VA hardware decode works with ANY GPU (NVIDIA, AMD, Intel)
- ✅ Significantly speeds up thumbnail generation (2-5x faster)
- ✅ Automatic GPU detection - just install latest drivers
- ⚠️ Requires FFmpeg with D3D11VA support (most builds include it)

### GPU Requirements
- **NVIDIA**: CUDA-compatible GPU + NVIDIA drivers
- **AMD**: ROCm-compatible GPU + amdgpu drivers  
- **Intel**: VAAPI-compatible iGPU/dGPU
- **WSL2**: D3D11VA-compatible GPU (Intel Arc, etc.)

## Installation Options

Choose the installation method that best fits your setup:

### Docker (Recommended)

> [!IMPORTANT]  
> Note the extra "z" in the Docker Hub URL: [stevezzau/plex_generate_vid_previews](https://hub.docker.com/repository/docker/stevezzau/plex_generate_vid_previews)  
> (stevezau was already taken on Docker Hub)

**Quick Start:**
```bash
# 1. Check available GPUs
docker run --rm stevezzau/plex_generate_vid_previews:latest --list-gpus

# 2. Run with GPU acceleration (using environment variables)
docker run --rm --gpus all \
  -e PLEX_URL=http://localhost:32400 \
  -e PLEX_TOKEN=your-token \
  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\ Support/Plex\ Media\ Server \
  -v /path/to/plex/config:/config/plex \
  -v /path/to/media:/media \
  stevezzau/plex_generate_vid_previews:latest

# 3. Alternative: using CLI arguments (environment variables and CLI arguments both work)
docker run --rm --gpus all \
  -v /path/to/plex/config:/config/plex \
  -v /path/to/media:/media \
  stevezzau/plex_generate_vid_previews:latest \
  --plex-url http://localhost:32400 \
  --plex-token your-token \
  --plex-config-folder /config/plex/Library/Application\ Support/Plex\ Media\ Server
```

**GPU Requirements:**
- **NVIDIA**: Install [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
- **AMD/Intel**: Mount `/dev/dri` with `--device /dev/dri:/dev/dri` (see [Troubleshooting](#troubleshooting) if you get permission errors)
- **WSL2**: No special configuration needed - automatically detects WSL2 GPUs

### Pip Installation

**Quick Start:**
```bash
# Install from GitHub
pip install git+https://github.com/stevezau/plex_generate_vid_previews.git

# Check available GPUs
plex-generate-previews --list-gpus

# Basic usage
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token your-token \
  --plex-config-folder /path/to/plex/Library/Application\ Support/Plex\ Media\ Server
```

**Prerequisites:**
Install FFmpeg and MediaInfo:

**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg mediainfo
```

**macOS (with Homebrew):**
```bash
brew install ffmpeg mediainfo
```

**Windows:**
Download from [FFmpeg](https://ffmpeg.org/download.html) and [MediaInfo](https://mediaarea.net/en/MediaInfo/Download)

**Usage Methods:**
```bash
# Method 1: Console script (recommended)
plex-generate-previews --help

# Method 2: Python module
python -m plex_generate_previews --help
```

### Windows GPU Support

Native Windows supports GPU acceleration using D3D11VA (Direct3D 11 Video Acceleration).

**GPU Requirements:**
- Compatible GPU: NVIDIA, AMD, or Intel
- Latest GPU drivers installed
- FFmpeg with D3D11VA support (included in most builds)

**Basic Windows usage with GPU:**
```bash
# Install
pip install git+https://github.com/stevezau/plex_generate_vid_previews.git

# Run with GPU acceleration (default)
plex-generate-previews ^
  --plex-url http://localhost:32400 ^
  --plex-token your-token-here ^
  --plex-config-folder "C:\Users\YourName\AppData\Local\Plex Media Server" ^
  --gpu-threads 4 ^
  --cpu-threads 2

# Run CPU-only (if no GPU or drivers)
plex-generate-previews ^
  --plex-url http://localhost:32400 ^
  --plex-token your-token-here ^
  --plex-config-folder "C:\Users\YourName\AppData\Local\Plex Media Server" ^
  --gpu-threads 0 ^
  --cpu-threads 4
```

**Important Windows Notes:**
- ✅ GPU support works with any modern GPU (NVIDIA, AMD, Intel)
- ✅ D3D11VA provides hardware video decode acceleration
- ✅ 2-5x faster than CPU-only processing
- ⚠️ Update GPU drivers for best performance
- 💡 Use `--list-gpus` to verify GPU detection

### Unraid

This guide is for Unraid users following the [TRaSH Guide](https://trash-guides.info/) folder structure with the linuxserver/plex Docker image.

**Setup Steps:**
1. **Configure Plex Container Paths:**
   - Add a second container path: `/server/media/plex/`
   - Map to host path: `/mnt/user/media/plex/`

2. **Update Plex Library Mappings:**
   - Delete existing library path mappings in Plex
   - Add new mappings with format: `//server/media/plex/<media-folder>`
   - Example: `//server/media/plex/tv`

3. **Configure Environment Variables:**
   ```bash
   PLEX_URL=http://localhost:32400
   PLEX_TOKEN=your-plex-token
   PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server
   ```

4. **Set Permissions:**
   ```bash
   chmod -R 777 /mnt/cache/appdata/plex/Library/Application\ Support/Plex\ Media\ Server/Media/
   ```

5. **Run the Script:**
   - The script may appear frozen initially but will start processing
   - Check the temporary folder for generated thumbnails

## Configuration

You can configure using either **command-line arguments** or **environment variables**. CLI arguments take precedence over environment variables.

### Basic Configuration

**Required settings:**
- `PLEX_URL` - Your Plex server URL (e.g., http://localhost:32400)
- `PLEX_TOKEN` - Your Plex authentication token
- `PLEX_CONFIG_FOLDER` - Path to Plex config folder

**Common settings:**
- `GPU_THREADS` - Number of GPU worker threads (default: 4)
- `CPU_THREADS` - Number of CPU worker threads (default: 4)
- `THUMBNAIL_QUALITY` - Preview quality 1-10 (default: 4)
- `PLEX_LIBRARIES` - Specific libraries to process (default: all)

### Command-line Arguments

```bash
# Basic usage
plex-generate-previews --plex-url http://localhost:32400 --plex-token YOUR_TOKEN

# With custom settings
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token YOUR_TOKEN \
  --plex-config-folder /path/to/plex/config \
  --gpu-threads 8 \
  --cpu-threads 4 \
  --thumbnail-quality 2
```

### Environment Variables

Create a `.env` file for persistent settings:

```bash
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your-token-here
PLEX_CONFIG_FOLDER=/path/to/plex/config
GPU_THREADS=4
CPU_THREADS=4
THUMBNAIL_QUALITY=4
```

### Advanced Configuration

For detailed configuration options, see the complete reference tables below:

#### All Configuration Options

| Variable | CLI Argument | Description | Default |
|----------|--------------|-------------|---------|
| `PLEX_URL` | `--plex-url` | Plex server URL | *Required* |
| `PLEX_TOKEN` | `--plex-token` | Plex authentication token | *Required* |
| `PLEX_CONFIG_FOLDER` | `--plex-config-folder` | Path to Plex config folder | *Required* |
| `PLEX_TIMEOUT` | `--plex-timeout` | Plex API timeout in seconds | 60 |
| `PLEX_LIBRARIES` | `--plex-libraries` | Comma-separated library names | All libraries |
| `GPU_THREADS` | `--gpu-threads` | Number of GPU worker threads (0-32) | 4 |
| `CPU_THREADS` | `--cpu-threads` | Number of CPU worker threads (0-32) | 4 |
| `GPU_SELECTION` | `--gpu-selection` | GPU selection: "all" or "0,1,2" | "all" |
| `THUMBNAIL_QUALITY` | `--thumbnail-quality` | Preview quality 1-10 (2=highest, 10=lowest) | 4 |
| `PLEX_BIF_FRAME_INTERVAL` | `--plex-bif-frame-interval` | Interval between preview images (1-60 seconds) | 5 |
| `REGENERATE_THUMBNAILS` | `--regenerate-thumbnails` | Regenerate existing thumbnails | false |
| `TMP_FOLDER` | `--tmp-folder` | Temporary folder for processing | System temp dir |
| `LOG_LEVEL` | `--log-level` | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO |
| `PUID` | N/A | User ID to run container as (Docker only) | 1000 |
| `PGID` | N/A | Group ID to run container as (Docker only) | 1000 |

**Note:** `PUID`/`PGID` let you run the container as your host user (prevents file permission issues). Defaults to 1000. For GPU access, you may also need `--group-add` (see [Troubleshooting](#troubleshooting)).

#### Special Commands

| Command | Description |
|---------|-------------|
| `--list-gpus` | List detected GPUs and exit |
| `--help` | Show help message and exit |

#### Path Mappings (Docker/Remote)

Path mappings are crucial when running in Docker or when Plex and the tool see different file paths. This is one of the most common issues users encounter.

**What are Path Mappings?**
Path mappings tell the tool how to convert Plex's file paths to the actual file paths accessible within the container or on the remote machine.

**The Problem:**
- Plex stores file paths like: `/server/media/movies/avatar.mkv`
- Inside Docker container, files are at: `/media/movies/avatar.mkv`
- The tool needs to know how to convert between these paths

**When You Need Path Mappings:**
- Running in Docker with volume mounts
- Plex running on a different machine than the tool
- Different path structures between Plex and the tool
- Using network shares or mounted drives

**How to Use Path Mappings:**

Using the Avatar example from above:
```bash
# Plex sees: /server/media/movies/avatar.mkv
# Container sees: /media/movies/avatar.mkv
# Solution: Map /server/media to /media
--plex-videos-path-mapping "/server/media" \
--plex-local-videos-path-mapping "/media"
```

**Common Examples:**

**Example 1: Docker with Volume Mounts**
```bash
# Plex sees: /server/media/movies/avatar.mkv
# Container sees: /media/movies/avatar.mkv
docker run --rm --gpus all \
  -e PLEX_URL=http://localhost:32400 \
  -e PLEX_TOKEN=your-token \
  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\ Support/Plex\ Media\ Server \
  -v /path/to/plex/config:/config/plex \
  -v /path/to/media:/media \
  stevezzau/plex_generate_vid_previews:latest \
  --plex-videos-path-mapping "/server/media" \
  --plex-local-videos-path-mapping "/media"
```

**Example 2: Different Server Names**
```bash
# Plex sees: /mnt/media/movies/avatar.mkv
# Container sees: /media/movies/avatar.mkv
--plex-videos-path-mapping "/mnt/media" \
--plex-local-videos-path-mapping "/media"
```

**Example 3: Windows Network Shares**
```bash
# Plex sees: \\server\media\movies\avatar.mkv
# Container sees: /media/movies/avatar.mkv
--plex-videos-path-mapping "\\\\server\\media" \
--plex-local-videos-path-mapping "/media"
```

**Example 4: Multiple Path Mappings**
```bash
# If you have multiple different path structures
--plex-videos-path-mapping "/server/media,/mnt/media" \
--plex-local-videos-path-mapping "/media,/media"
```

**How to Find Your Path Mappings:**

1. **Check Plex Library Settings:**
   - Go to Plex Web → Settings → Libraries
   - Click on a library → Edit → Folders
   - Note the path Plex shows (e.g., `/server/media/movies`)

2. **Check Your Docker Volume Mounts:**
   ```bash
   # Your Docker command should have something like:
   -v /host/path/to/media:/container/path/to/media
   ```

3. **Test the Mapping:**
   ```bash
   # Run with debug logging to see path conversions
   plex-generate-previews --log-level DEBUG \
     --plex-videos-path-mapping "/server/media" \
     --plex-local-videos-path-mapping "/media"
   ```

**Troubleshooting Path Mappings:**

**Problem: "Skipping as file not found"**
- **Cause**: Incorrect path mappings
- **Solution**: Check that the mapping correctly converts Plex paths to accessible paths

**Problem: "Permission denied"**
- **Cause**: Container can't access the mapped path
- **Solution**: Check Docker volume mount permissions and user mapping

**Problem: "No videos found"**
- **Cause**: Path mapping doesn't match any Plex library paths
- **Solution**: Verify Plex library paths match your mapping

**Quick Test:**
```bash
# Test if your paths are correct
docker run --rm -v /your/media:/media stevezzau/plex_generate_vid_previews:latest \
  --list-gpus --plex-videos-path-mapping "/server/media" \
  --plex-local-videos-path-mapping "/media"
```

**Pro Tips:**
- Always use absolute paths
- Test with `--log-level DEBUG` to see path conversions
- Check Plex library settings to see exact paths
- Use forward slashes even on Windows
- Escape backslashes in Windows paths: `\\\\server\\share`

## GPU Support

The tool automatically detects and supports multiple GPU types with hardware acceleration:

### Supported GPU Types

| GPU Type | Acceleration | Requirements | Docker Support |
|----------|--------------|--------------|----------------|
| **NVIDIA** | CUDA | NVIDIA drivers + CUDA toolkit | ✅ NVIDIA Container Toolkit |
| **AMD** | VAAPI | amdgpu drivers + ROCm | ✅ ROCm Docker support |
| **Intel** | VAAPI | Intel drivers + VA-API | ✅ Device access |
| **Apple Silicon** | VideoToolbox | macOS with FFmpeg + mediainfo | ❌ Native macOS only |
| **WSL2 (NVIDIA)** | D3D11VA | WSL2 + /dev/dxg + mesa-utils | ✅ Native WSL2 |
| **WSL2 (AMD)** | VAAPI | WSL2 + ROCm + /dev/dri devices | ✅ Native WSL2 |

### GPU Detection

The tool automatically detects available GPUs and their capabilities:

```bash
# List all detected GPUs
plex-generate-previews --list-gpus

# Example output:
# ✅ Found 2 GPU(s):
#   [0] NVIDIA GeForce RTX 4090 (CUDA)
#   [1] Intel UHD Graphics 770 (VAAPI - /dev/dri/renderD128)
```

### Multi-GPU Support

Configure GPU usage with the `--gpu-selection` parameter:

```bash
# Use all detected GPUs (default)
plex-generate-previews --gpu-selection all

# Use specific GPUs by index
plex-generate-previews --gpu-selection "0,2"

# Use only the first GPU
plex-generate-previews --gpu-selection "0"
```

### Hardware Acceleration Methods

- **NVIDIA**: Uses CUDA for maximum performance
- **AMD**: Uses VAAPI with ROCm drivers (native Linux and WSL2)
- **Intel**: Uses VAAPI (Video Acceleration API)
- **Apple Silicon**: Uses VideoToolbox (M1/M2/M3/M4 chips on macOS)
- **WSL2**: Automatically detects GPU type and uses appropriate acceleration:
  - **NVIDIA GPUs**: D3D11VA via `/dev/dxg`
  - **AMD GPUs**: VAAPI via `/dev/dri` with ROCm support

### Docker GPU Requirements

#### NVIDIA
Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) on your host system.

#### AMD
Follow the [ROCm Docker setup guide](https://rocm.docs.amd.com/en/docs-5.0.2/deploy/docker.html) for container GPU access.

#### Intel
Ensure the container has access to `/dev/dri` devices and the render group:

```yaml
services:
  previews:
    user: 1000:1000
    group_add:
      - 109  # render group GID
    devices:
      - /dev/dri:/dev/dri
```

#### WSL2
GPU support in WSL2 uses a hybrid detection approach:

**Primary Method (All Vendors):**
- Uses DirectX acceleration (D3D11VA) via `/dev/dxg`
- Works universally for NVIDIA, AMD, and Intel GPUs
- No special configuration needed

**Alternative Method (AMD/Intel):**
- If Linux drivers are properly loaded, may use VAAPI via `/dev/dri`
- Requires proper driver configuration in WSL2
- May offer better performance but is less reliable

**Important Notes:**
- AMD GPU support in WSL2 is still evolving
- ROCm support is limited and not officially supported by AMD in WSL2
- The script automatically detects and uses the best available method
- If VAAPI fails, automatically falls back to D3D11VA

## Usage Examples

### Docker Compose Examples

> [!WARNING]  
> **Do NOT use `init: true` in your compose file!** This container uses LinuxServer.io's s6-overlay which is a more capable init system. Adding `init: true` will cause errors and disable important features like PUID/PGID support. See `docker-compose.example.yml` for a complete working example.

**NVIDIA GPU:**
```yaml
version: '3.8'
services:
  previews:
    image: stevezzau/plex_generate_vid_previews:latest
    user: 1000:1000
    environment:
      - PLEX_URL=http://localhost:32400
      - PLEX_TOKEN=your-plex-token
      - PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server
    volumes:
      - /path/to/plex/config:/config/plex
      - /path/to/media:/media
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    runtime: nvidia
```

**AMD GPU:**
```yaml
version: '3.8'
services:
  previews:
    image: stevezzau/plex_generate_vid_previews:latest
    user: 1000:1000
    environment:
      - PLEX_URL=http://localhost:32400
      - PLEX_TOKEN=your-plex-token
      - PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server
    volumes:
      - /path/to/plex/config:/config/plex
      - /path/to/media:/media
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - 109  # render group
```

### Docker CLI Examples

> **Note:** Docker supports both environment variables (shown below) and CLI arguments. To use CLI arguments, append them after the image name (e.g., `stevezzau/plex_generate_vid_previews:latest --plex-url http://... --plex-token ...`). See [Quick Start](#quick-start) for CLI argument examples.

**NVIDIA GPU:**
```bash
docker run --rm --gpus all \
  -e PLEX_URL=http://localhost:32400 \
  -e PLEX_TOKEN=your-token \
  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\ Support/Plex\ Media\ Server \
  -v /path/to/plex/config:/config/plex \
  -v /path/to/media:/media \
  stevezzau/plex_generate_vid_previews:latest
```

**AMD GPU:**
```bash
docker run --rm \
  --device=/dev/dri:/dev/dri \
  --group-add 109 \
  -e PLEX_URL=http://localhost:32400 \
  -e PLEX_TOKEN=your-token \
  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\ Support/Plex\ Media\ Server \
  -v /path/to/plex/config:/config/plex \
  -v /path/to/media:/media \
  stevezzau/plex_generate_vid_previews:latest
```

### Advanced Usage

**Process specific libraries:**
```bash
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token your-token \
  --plex-config-folder /path/to/plex/config \
  --plex-libraries "Movies, TV Shows"
```

**Use specific GPUs:**
```bash
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token your-token \
  --plex-config-folder /path/to/plex/config \
  --gpu-selection "0,2" \
  --gpu-threads 8
```

**CPU-only processing:**
```bash
plex-generate-previews \
  --plex-url http://localhost:32400 \
  --plex-token your-token \
  --plex-config-folder /path/to/plex/config \
  --gpu-threads 0 \
  --cpu-threads 8
```

## Troubleshooting

### Common Issues

#### "s6-overlay-suexec: fatal: can only run as pid 1" or container fails to start
- **Cause**: You have `init: true` in your docker-compose.yml or using `--init` with docker run
- **Why this breaks**: This container uses s6-overlay (LinuxServer.io base) as its init system. Docker's init conflicts with it.
- **What you lose with `init: true`**:
  - ❌ PUID/PGID support (file permissions will be wrong)
  - ❌ Process supervision
  - ❌ Proper initialization
- **Solution**: 
  - **Docker Compose**: Remove `init: true` from your compose file
  - **Docker CLI**: Remove the `--init` flag
  - s6-overlay is MORE capable than Docker's basic init - you don't need both!
- **Example**: See `docker-compose.example.yml` for correct configuration

#### "No GPUs detected"
- **Cause**: GPU drivers not installed or FFmpeg doesn't support hardware acceleration
- **Solution**: 
  - Install proper GPU drivers
  - Update FFmpeg to version 7.0+
  - Use `--list-gpus` to check detection
  - Fall back to CPU-only: `--gpu-threads 0 --cpu-threads 4`

#### "GPU permission denied" (Intel/AMD VAAPI)
- **Cause**: The container needs to run as a user that has GPU device permissions
- **Solution**: Set `PUID` and `PGID` environment variables on the container
- **The error message tells you what values to use** - look for your user ID in the output
- **Example**:
  ```bash
  docker run -e PUID=1000 -e PGID=1000 --device /dev/dri:/dev/dri ...
  ```

#### "PLEX_CONFIG_FOLDER does not exist"
- **Cause**: Incorrect path to Plex Media Server configuration folder
- **Solution**:
  - Verify the path exists: `ls -la "/path/to/plex/Library/Application Support/Plex Media Server"`
  - Check for proper Plex folder structure (Cache, Media folders)
  - Use absolute paths, not relative paths

#### "Permission denied" errors
- **Cause**: Insufficient permissions to access files or directories
- **Solution**:
  - Check file ownership: `ls -la /path/to/plex/config`
  - Fix permissions: `chmod -R 755 /path/to/plex/config`
  - For Docker: ensure proper user/group mapping

#### "Connection failed" to Plex
- **Cause**: Plex server not accessible or incorrect credentials
- **Solution**:
  - Verify Plex URL is correct and accessible
  - Check Plex token is valid and not expired
  - Test connection: `curl -H "X-Plex-Token: YOUR_TOKEN" http://localhost:32400/status/sessions`

#### Docker GPU not working
- **Cause**: Missing GPU runtime or device access
- **Solution**:
  - **NVIDIA**: Install NVIDIA Container Toolkit
  - **AMD**: Add `--device=/dev/dri:/dev/dri --group-add 109`
  - **Intel**: Add `--device=/dev/dri:/dev/dri --group-add 109`
  - Test with: `docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi`

#### "Skipping as file not found"
- **Cause**: Incorrect path mappings or missing media files
- **Solution**:
  - Verify media file paths are correct
  - Check path mappings in Plex settings
  - For Windows mapped drives, use UNC paths: `\\server\share\path`

#### "No GPUs detected on Windows"
- **Cause**: GPU not detected or drivers not installed
- **Solution**:
  - Install latest GPU drivers (NVIDIA, AMD, or Intel)
  - Verify GPU is working in Windows Device Manager
  - Test with: `plex-generate-previews --list-gpus`
  - If needed, use CPU-only: `--gpu-threads 0 --cpu-threads 4`

### Debug Mode

Enable debug logging for detailed troubleshooting:

```bash
plex-generate-previews --log-level DEBUG
```

### Getting Help

1. Check the [GitHub Issues](https://github.com/stevezau/plex_generate_vid_previews/issues)
2. Enable debug logging and check logs
3. Verify your configuration with `--help`
4. Test GPU detection with `--list-gpus`


## FAQ

### General Questions

**Q: What's new in version 2.0.0?**
A: Version 2.0.0 introduces multi-GPU support, improved CLI interface, better error handling, WSL2 support, and a complete rewrite with modern Python practices.

**Q: Does this work on Windows?**
A: Yes! Windows fully supports GPU acceleration via D3D11VA, which works with NVIDIA, AMD, and Intel GPUs. Install the latest GPU drivers and the tool will automatically detect and use your GPU for faster processing. 

**Q: Can I use this without a GPU?**
A: Yes! Set `--gpu-threads 0` and use `--cpu-threads 4` (or higher) for CPU-only processing.

**Q: How do I know which GPUs are detected?**
A: Run `plex-generate-previews --list-gpus` to see all detected GPUs and their capabilities.

**Q: Can I process specific libraries only?**
A: Yes! Use `--plex-libraries "Movies, TV Shows"` to process only specific Plex libraries.

**Q: What's the difference between thumbnail quality 1-10?**
A: Lower numbers = higher quality but larger file sizes. Quality 2 is highest quality, quality 10 is lowest quality.

### Performance Questions

**Q: How many threads should I use?**
A: Start with 4 GPU threads and 4 CPU threads. Adjust based on your hardware - more threads = faster processing but higher resource usage.

**Q: Can I use multiple GPUs?**
A: Yes! The tool automatically detects and can use multiple GPUs. Use `--gpu-selection "0,1,2"` to select specific GPUs.

### Troubleshooting Questions

**Q: "Skipping as file not found" error?**
A: This usually means incorrect path mappings. Check your Docker volume mounts or Plex library path mappings.

**Q: Docker GPU not working?**
A: Ensure you have the proper GPU runtime installed (NVIDIA Container Toolkit, ROCm, etc.) and correct device access.

**Q: How do I enable debug logging?**
A: Use `--log-level DEBUG` or set `LOG_LEVEL=DEBUG` in your environment.

## Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/stevezau/plex_generate_vid_previews/issues)
- **Documentation**: This README and inline help (`--help`)
- **Community**: Check existing issues for solutions to common problems

## Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Plex](https://www.plex.tv/) for the amazing media server
- [FFmpeg](https://ffmpeg.org/) for video processing capabilities
- [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- All contributors and users who help improve this project

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "plex-generate-previews",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "plex, media, server, video, thumbnails, previews, ffmpeg, gpu, acceleration",
    "author": null,
    "author_email": "stevezau <stevezau@example.com>",
    "download_url": "https://files.pythonhosted.org/packages/82/cd/a3ef3266733b26dd18bb65f93673e230651ee222a5b107e7d48340ea6cf9/plex_generate_previews-2.3.0.tar.gz",
    "platform": null,
    "description": "# [stevezau/plex_generate_vid_previews](https://github.com/stevezau/plex_generate_vid_previews/)\n\n[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/stevezau/plex_generate_vid_previews)\n[![Python](https://img.shields.io/badge/python-3.7+-green.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Docker](https://img.shields.io/badge/docker-available-blue.svg)](https://hub.docker.com/repository/docker/stevezzau/plex_generate_vid_previews)\n[![codecov](https://codecov.io/gh/stevezau/plex_generate_vid_previews/branch/main/graph/badge.svg)](https://codecov.io/gh/stevezau/plex_generate_vid_previews)\n\n## Table of Contents\n\n- [What This Tool Does](#what-this-tool-does)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation Options](#installation-options)\n  - [Docker](#docker)\n  - [Pip Installation](#pip-installation)\n  - [Unraid](#unraid)\n- [Configuration](#configuration)\n  - [Command-line Arguments](#command-line-arguments)\n  - [Environment Variables](#environment-variables)\n- [GPU Support](#gpu-support)\n- [Usage Examples](#usage-examples)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n\n## What This Tool Does\n\nGenerates video preview thumbnails for Plex Media Server using GPU acceleration and parallel processing. Plex's built-in preview generation is slow - this tool makes it much faster.\n\nPreview thumbnails are the small images you see when scrubbing through videos in Plex.\n\n## Quick Start\n\n**Before you begin, you'll need:**\n1. A Plex Media Server running and accessible\n2. Your Plex authentication token ([how to get it](https://support.plex.tv/articles/204059436/))\n3. The path to your Plex config folder\n\n**Docker (easiest):**\n```bash\n# 1. Check your GPUs\ndocker run --rm stevezzau/plex_generate_vid_previews:latest --list-gpus\n\n# 2. Run with your details (using environment variables)\ndocker run --rm --gpus all \\\n  -e PLEX_URL=http://localhost:32400 \\\n  -e PLEX_TOKEN=your-token-here \\\n  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\\ Support/Plex\\ Media\\ Server \\\n  -v /path/to/your/plex/config:/config/plex \\\n  -v /path/to/your/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest\n\n# Or use CLI arguments instead (both work)\ndocker run --rm --gpus all \\\n  -v /path/to/your/plex/config:/config/plex \\\n  -v /path/to/your/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token-here \\\n  --plex-config-folder /config/plex/Library/Application\\ Support/Plex\\ Media\\ Server\n```\n\n**Pip (local install):**\n```bash\n# 1. Install\npip install git+https://github.com/stevezau/plex_generate_vid_previews.git\n\n# 2. Check your GPUs\nplex-generate-previews --list-gpus\n\n# 3. Run with your details\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token-here \\\n  --plex-config-folder /path/to/your/plex/Library/Application\\ Support/Plex\\ Media\\ Server\n```\n\n## Features\n\n- **Multi-GPU Support**: NVIDIA, AMD, Intel, and WSL2 GPUs\n- **Parallel Processing**: Configurable GPU and CPU worker threads\n- **Hardware Acceleration**: CUDA, VAAPI, and D3D11VA\n- **Library Filtering**: Process specific Plex libraries\n- **Quality Control**: Adjustable thumbnail quality (1-10)\n- **Docker Support**: Pre-built images with GPU acceleration\n- **Command-line Interface**: CLI arguments and environment variables\n\n## Requirements\n\n- **Plex Media Server**: Running and accessible\n- **FFmpeg 7.0+**: For video processing and hardware acceleration\n- **Python 3.7+**: For local installation\n- **Docker**: For containerized deployment (optional)\n\n### Platform Support\n\n| Platform | Support | Notes |\n|----------|---------|-------|\n| **Linux** | \u2705 Full | GPU + CPU support (CUDA, VAAPI, etc.) |\n| **Docker** | \u2705 Full | GPU + CPU support (Recommended) |\n| **WSL2** | \u2705 Full | GPU + CPU support (D3D11VA, VAAPI) |\n| **macOS** | \u2705 Full | VideoToolbox + CPU support |\n| **Windows** | \u2705 Full | D3D11VA GPU + CPU support |\n\n**Windows GPU Support:**\n- \u2705 D3D11VA hardware decode works with ANY GPU (NVIDIA, AMD, Intel)\n- \u2705 Significantly speeds up thumbnail generation (2-5x faster)\n- \u2705 Automatic GPU detection - just install latest drivers\n- \u26a0\ufe0f Requires FFmpeg with D3D11VA support (most builds include it)\n\n### GPU Requirements\n- **NVIDIA**: CUDA-compatible GPU + NVIDIA drivers\n- **AMD**: ROCm-compatible GPU + amdgpu drivers  \n- **Intel**: VAAPI-compatible iGPU/dGPU\n- **WSL2**: D3D11VA-compatible GPU (Intel Arc, etc.)\n\n## Installation Options\n\nChoose the installation method that best fits your setup:\n\n### Docker (Recommended)\n\n> [!IMPORTANT]  \n> Note the extra \"z\" in the Docker Hub URL: [stevezzau/plex_generate_vid_previews](https://hub.docker.com/repository/docker/stevezzau/plex_generate_vid_previews)  \n> (stevezau was already taken on Docker Hub)\n\n**Quick Start:**\n```bash\n# 1. Check available GPUs\ndocker run --rm stevezzau/plex_generate_vid_previews:latest --list-gpus\n\n# 2. Run with GPU acceleration (using environment variables)\ndocker run --rm --gpus all \\\n  -e PLEX_URL=http://localhost:32400 \\\n  -e PLEX_TOKEN=your-token \\\n  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\\ Support/Plex\\ Media\\ Server \\\n  -v /path/to/plex/config:/config/plex \\\n  -v /path/to/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest\n\n# 3. Alternative: using CLI arguments (environment variables and CLI arguments both work)\ndocker run --rm --gpus all \\\n  -v /path/to/plex/config:/config/plex \\\n  -v /path/to/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token \\\n  --plex-config-folder /config/plex/Library/Application\\ Support/Plex\\ Media\\ Server\n```\n\n**GPU Requirements:**\n- **NVIDIA**: Install [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)\n- **AMD/Intel**: Mount `/dev/dri` with `--device /dev/dri:/dev/dri` (see [Troubleshooting](#troubleshooting) if you get permission errors)\n- **WSL2**: No special configuration needed - automatically detects WSL2 GPUs\n\n### Pip Installation\n\n**Quick Start:**\n```bash\n# Install from GitHub\npip install git+https://github.com/stevezau/plex_generate_vid_previews.git\n\n# Check available GPUs\nplex-generate-previews --list-gpus\n\n# Basic usage\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token \\\n  --plex-config-folder /path/to/plex/Library/Application\\ Support/Plex\\ Media\\ Server\n```\n\n**Prerequisites:**\nInstall FFmpeg and MediaInfo:\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update && sudo apt install ffmpeg mediainfo\n```\n\n**macOS (with Homebrew):**\n```bash\nbrew install ffmpeg mediainfo\n```\n\n**Windows:**\nDownload from [FFmpeg](https://ffmpeg.org/download.html) and [MediaInfo](https://mediaarea.net/en/MediaInfo/Download)\n\n**Usage Methods:**\n```bash\n# Method 1: Console script (recommended)\nplex-generate-previews --help\n\n# Method 2: Python module\npython -m plex_generate_previews --help\n```\n\n### Windows GPU Support\n\nNative Windows supports GPU acceleration using D3D11VA (Direct3D 11 Video Acceleration).\n\n**GPU Requirements:**\n- Compatible GPU: NVIDIA, AMD, or Intel\n- Latest GPU drivers installed\n- FFmpeg with D3D11VA support (included in most builds)\n\n**Basic Windows usage with GPU:**\n```bash\n# Install\npip install git+https://github.com/stevezau/plex_generate_vid_previews.git\n\n# Run with GPU acceleration (default)\nplex-generate-previews ^\n  --plex-url http://localhost:32400 ^\n  --plex-token your-token-here ^\n  --plex-config-folder \"C:\\Users\\YourName\\AppData\\Local\\Plex Media Server\" ^\n  --gpu-threads 4 ^\n  --cpu-threads 2\n\n# Run CPU-only (if no GPU or drivers)\nplex-generate-previews ^\n  --plex-url http://localhost:32400 ^\n  --plex-token your-token-here ^\n  --plex-config-folder \"C:\\Users\\YourName\\AppData\\Local\\Plex Media Server\" ^\n  --gpu-threads 0 ^\n  --cpu-threads 4\n```\n\n**Important Windows Notes:**\n- \u2705 GPU support works with any modern GPU (NVIDIA, AMD, Intel)\n- \u2705 D3D11VA provides hardware video decode acceleration\n- \u2705 2-5x faster than CPU-only processing\n- \u26a0\ufe0f Update GPU drivers for best performance\n- \ud83d\udca1 Use `--list-gpus` to verify GPU detection\n\n### Unraid\n\nThis guide is for Unraid users following the [TRaSH Guide](https://trash-guides.info/) folder structure with the linuxserver/plex Docker image.\n\n**Setup Steps:**\n1. **Configure Plex Container Paths:**\n   - Add a second container path: `/server/media/plex/`\n   - Map to host path: `/mnt/user/media/plex/`\n\n2. **Update Plex Library Mappings:**\n   - Delete existing library path mappings in Plex\n   - Add new mappings with format: `//server/media/plex/<media-folder>`\n   - Example: `//server/media/plex/tv`\n\n3. **Configure Environment Variables:**\n   ```bash\n   PLEX_URL=http://localhost:32400\n   PLEX_TOKEN=your-plex-token\n   PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server\n   ```\n\n4. **Set Permissions:**\n   ```bash\n   chmod -R 777 /mnt/cache/appdata/plex/Library/Application\\ Support/Plex\\ Media\\ Server/Media/\n   ```\n\n5. **Run the Script:**\n   - The script may appear frozen initially but will start processing\n   - Check the temporary folder for generated thumbnails\n\n## Configuration\n\nYou can configure using either **command-line arguments** or **environment variables**. CLI arguments take precedence over environment variables.\n\n### Basic Configuration\n\n**Required settings:**\n- `PLEX_URL` - Your Plex server URL (e.g., http://localhost:32400)\n- `PLEX_TOKEN` - Your Plex authentication token\n- `PLEX_CONFIG_FOLDER` - Path to Plex config folder\n\n**Common settings:**\n- `GPU_THREADS` - Number of GPU worker threads (default: 4)\n- `CPU_THREADS` - Number of CPU worker threads (default: 4)\n- `THUMBNAIL_QUALITY` - Preview quality 1-10 (default: 4)\n- `PLEX_LIBRARIES` - Specific libraries to process (default: all)\n\n### Command-line Arguments\n\n```bash\n# Basic usage\nplex-generate-previews --plex-url http://localhost:32400 --plex-token YOUR_TOKEN\n\n# With custom settings\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token YOUR_TOKEN \\\n  --plex-config-folder /path/to/plex/config \\\n  --gpu-threads 8 \\\n  --cpu-threads 4 \\\n  --thumbnail-quality 2\n```\n\n### Environment Variables\n\nCreate a `.env` file for persistent settings:\n\n```bash\nPLEX_URL=http://localhost:32400\nPLEX_TOKEN=your-token-here\nPLEX_CONFIG_FOLDER=/path/to/plex/config\nGPU_THREADS=4\nCPU_THREADS=4\nTHUMBNAIL_QUALITY=4\n```\n\n### Advanced Configuration\n\nFor detailed configuration options, see the complete reference tables below:\n\n#### All Configuration Options\n\n| Variable | CLI Argument | Description | Default |\n|----------|--------------|-------------|---------|\n| `PLEX_URL` | `--plex-url` | Plex server URL | *Required* |\n| `PLEX_TOKEN` | `--plex-token` | Plex authentication token | *Required* |\n| `PLEX_CONFIG_FOLDER` | `--plex-config-folder` | Path to Plex config folder | *Required* |\n| `PLEX_TIMEOUT` | `--plex-timeout` | Plex API timeout in seconds | 60 |\n| `PLEX_LIBRARIES` | `--plex-libraries` | Comma-separated library names | All libraries |\n| `GPU_THREADS` | `--gpu-threads` | Number of GPU worker threads (0-32) | 4 |\n| `CPU_THREADS` | `--cpu-threads` | Number of CPU worker threads (0-32) | 4 |\n| `GPU_SELECTION` | `--gpu-selection` | GPU selection: \"all\" or \"0,1,2\" | \"all\" |\n| `THUMBNAIL_QUALITY` | `--thumbnail-quality` | Preview quality 1-10 (2=highest, 10=lowest) | 4 |\n| `PLEX_BIF_FRAME_INTERVAL` | `--plex-bif-frame-interval` | Interval between preview images (1-60 seconds) | 5 |\n| `REGENERATE_THUMBNAILS` | `--regenerate-thumbnails` | Regenerate existing thumbnails | false |\n| `TMP_FOLDER` | `--tmp-folder` | Temporary folder for processing | System temp dir |\n| `LOG_LEVEL` | `--log-level` | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO |\n| `PUID` | N/A | User ID to run container as (Docker only) | 1000 |\n| `PGID` | N/A | Group ID to run container as (Docker only) | 1000 |\n\n**Note:** `PUID`/`PGID` let you run the container as your host user (prevents file permission issues). Defaults to 1000. For GPU access, you may also need `--group-add` (see [Troubleshooting](#troubleshooting)).\n\n#### Special Commands\n\n| Command | Description |\n|---------|-------------|\n| `--list-gpus` | List detected GPUs and exit |\n| `--help` | Show help message and exit |\n\n#### Path Mappings (Docker/Remote)\n\nPath mappings are crucial when running in Docker or when Plex and the tool see different file paths. This is one of the most common issues users encounter.\n\n**What are Path Mappings?**\nPath mappings tell the tool how to convert Plex's file paths to the actual file paths accessible within the container or on the remote machine.\n\n**The Problem:**\n- Plex stores file paths like: `/server/media/movies/avatar.mkv`\n- Inside Docker container, files are at: `/media/movies/avatar.mkv`\n- The tool needs to know how to convert between these paths\n\n**When You Need Path Mappings:**\n- Running in Docker with volume mounts\n- Plex running on a different machine than the tool\n- Different path structures between Plex and the tool\n- Using network shares or mounted drives\n\n**How to Use Path Mappings:**\n\nUsing the Avatar example from above:\n```bash\n# Plex sees: /server/media/movies/avatar.mkv\n# Container sees: /media/movies/avatar.mkv\n# Solution: Map /server/media to /media\n--plex-videos-path-mapping \"/server/media\" \\\n--plex-local-videos-path-mapping \"/media\"\n```\n\n**Common Examples:**\n\n**Example 1: Docker with Volume Mounts**\n```bash\n# Plex sees: /server/media/movies/avatar.mkv\n# Container sees: /media/movies/avatar.mkv\ndocker run --rm --gpus all \\\n  -e PLEX_URL=http://localhost:32400 \\\n  -e PLEX_TOKEN=your-token \\\n  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\\ Support/Plex\\ Media\\ Server \\\n  -v /path/to/plex/config:/config/plex \\\n  -v /path/to/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest \\\n  --plex-videos-path-mapping \"/server/media\" \\\n  --plex-local-videos-path-mapping \"/media\"\n```\n\n**Example 2: Different Server Names**\n```bash\n# Plex sees: /mnt/media/movies/avatar.mkv\n# Container sees: /media/movies/avatar.mkv\n--plex-videos-path-mapping \"/mnt/media\" \\\n--plex-local-videos-path-mapping \"/media\"\n```\n\n**Example 3: Windows Network Shares**\n```bash\n# Plex sees: \\\\server\\media\\movies\\avatar.mkv\n# Container sees: /media/movies/avatar.mkv\n--plex-videos-path-mapping \"\\\\\\\\server\\\\media\" \\\n--plex-local-videos-path-mapping \"/media\"\n```\n\n**Example 4: Multiple Path Mappings**\n```bash\n# If you have multiple different path structures\n--plex-videos-path-mapping \"/server/media,/mnt/media\" \\\n--plex-local-videos-path-mapping \"/media,/media\"\n```\n\n**How to Find Your Path Mappings:**\n\n1. **Check Plex Library Settings:**\n   - Go to Plex Web \u2192 Settings \u2192 Libraries\n   - Click on a library \u2192 Edit \u2192 Folders\n   - Note the path Plex shows (e.g., `/server/media/movies`)\n\n2. **Check Your Docker Volume Mounts:**\n   ```bash\n   # Your Docker command should have something like:\n   -v /host/path/to/media:/container/path/to/media\n   ```\n\n3. **Test the Mapping:**\n   ```bash\n   # Run with debug logging to see path conversions\n   plex-generate-previews --log-level DEBUG \\\n     --plex-videos-path-mapping \"/server/media\" \\\n     --plex-local-videos-path-mapping \"/media\"\n   ```\n\n**Troubleshooting Path Mappings:**\n\n**Problem: \"Skipping as file not found\"**\n- **Cause**: Incorrect path mappings\n- **Solution**: Check that the mapping correctly converts Plex paths to accessible paths\n\n**Problem: \"Permission denied\"**\n- **Cause**: Container can't access the mapped path\n- **Solution**: Check Docker volume mount permissions and user mapping\n\n**Problem: \"No videos found\"**\n- **Cause**: Path mapping doesn't match any Plex library paths\n- **Solution**: Verify Plex library paths match your mapping\n\n**Quick Test:**\n```bash\n# Test if your paths are correct\ndocker run --rm -v /your/media:/media stevezzau/plex_generate_vid_previews:latest \\\n  --list-gpus --plex-videos-path-mapping \"/server/media\" \\\n  --plex-local-videos-path-mapping \"/media\"\n```\n\n**Pro Tips:**\n- Always use absolute paths\n- Test with `--log-level DEBUG` to see path conversions\n- Check Plex library settings to see exact paths\n- Use forward slashes even on Windows\n- Escape backslashes in Windows paths: `\\\\\\\\server\\\\share`\n\n## GPU Support\n\nThe tool automatically detects and supports multiple GPU types with hardware acceleration:\n\n### Supported GPU Types\n\n| GPU Type | Acceleration | Requirements | Docker Support |\n|----------|--------------|--------------|----------------|\n| **NVIDIA** | CUDA | NVIDIA drivers + CUDA toolkit | \u2705 NVIDIA Container Toolkit |\n| **AMD** | VAAPI | amdgpu drivers + ROCm | \u2705 ROCm Docker support |\n| **Intel** | VAAPI | Intel drivers + VA-API | \u2705 Device access |\n| **Apple Silicon** | VideoToolbox | macOS with FFmpeg + mediainfo | \u274c Native macOS only |\n| **WSL2 (NVIDIA)** | D3D11VA | WSL2 + /dev/dxg + mesa-utils | \u2705 Native WSL2 |\n| **WSL2 (AMD)** | VAAPI | WSL2 + ROCm + /dev/dri devices | \u2705 Native WSL2 |\n\n### GPU Detection\n\nThe tool automatically detects available GPUs and their capabilities:\n\n```bash\n# List all detected GPUs\nplex-generate-previews --list-gpus\n\n# Example output:\n# \u2705 Found 2 GPU(s):\n#   [0] NVIDIA GeForce RTX 4090 (CUDA)\n#   [1] Intel UHD Graphics 770 (VAAPI - /dev/dri/renderD128)\n```\n\n### Multi-GPU Support\n\nConfigure GPU usage with the `--gpu-selection` parameter:\n\n```bash\n# Use all detected GPUs (default)\nplex-generate-previews --gpu-selection all\n\n# Use specific GPUs by index\nplex-generate-previews --gpu-selection \"0,2\"\n\n# Use only the first GPU\nplex-generate-previews --gpu-selection \"0\"\n```\n\n### Hardware Acceleration Methods\n\n- **NVIDIA**: Uses CUDA for maximum performance\n- **AMD**: Uses VAAPI with ROCm drivers (native Linux and WSL2)\n- **Intel**: Uses VAAPI (Video Acceleration API)\n- **Apple Silicon**: Uses VideoToolbox (M1/M2/M3/M4 chips on macOS)\n- **WSL2**: Automatically detects GPU type and uses appropriate acceleration:\n  - **NVIDIA GPUs**: D3D11VA via `/dev/dxg`\n  - **AMD GPUs**: VAAPI via `/dev/dri` with ROCm support\n\n### Docker GPU Requirements\n\n#### NVIDIA\nInstall the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) on your host system.\n\n#### AMD\nFollow the [ROCm Docker setup guide](https://rocm.docs.amd.com/en/docs-5.0.2/deploy/docker.html) for container GPU access.\n\n#### Intel\nEnsure the container has access to `/dev/dri` devices and the render group:\n\n```yaml\nservices:\n  previews:\n    user: 1000:1000\n    group_add:\n      - 109  # render group GID\n    devices:\n      - /dev/dri:/dev/dri\n```\n\n#### WSL2\nGPU support in WSL2 uses a hybrid detection approach:\n\n**Primary Method (All Vendors):**\n- Uses DirectX acceleration (D3D11VA) via `/dev/dxg`\n- Works universally for NVIDIA, AMD, and Intel GPUs\n- No special configuration needed\n\n**Alternative Method (AMD/Intel):**\n- If Linux drivers are properly loaded, may use VAAPI via `/dev/dri`\n- Requires proper driver configuration in WSL2\n- May offer better performance but is less reliable\n\n**Important Notes:**\n- AMD GPU support in WSL2 is still evolving\n- ROCm support is limited and not officially supported by AMD in WSL2\n- The script automatically detects and uses the best available method\n- If VAAPI fails, automatically falls back to D3D11VA\n\n## Usage Examples\n\n### Docker Compose Examples\n\n> [!WARNING]  \n> **Do NOT use `init: true` in your compose file!** This container uses LinuxServer.io's s6-overlay which is a more capable init system. Adding `init: true` will cause errors and disable important features like PUID/PGID support. See `docker-compose.example.yml` for a complete working example.\n\n**NVIDIA GPU:**\n```yaml\nversion: '3.8'\nservices:\n  previews:\n    image: stevezzau/plex_generate_vid_previews:latest\n    user: 1000:1000\n    environment:\n      - PLEX_URL=http://localhost:32400\n      - PLEX_TOKEN=your-plex-token\n      - PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server\n    volumes:\n      - /path/to/plex/config:/config/plex\n      - /path/to/media:/media\n    deploy:\n      resources:\n        reservations:\n          devices:\n            - capabilities: [gpu]\n    runtime: nvidia\n```\n\n**AMD GPU:**\n```yaml\nversion: '3.8'\nservices:\n  previews:\n    image: stevezzau/plex_generate_vid_previews:latest\n    user: 1000:1000\n    environment:\n      - PLEX_URL=http://localhost:32400\n      - PLEX_TOKEN=your-plex-token\n      - PLEX_CONFIG_FOLDER=/config/plex/Library/Application Support/Plex Media Server\n    volumes:\n      - /path/to/plex/config:/config/plex\n      - /path/to/media:/media\n    devices:\n      - /dev/dri:/dev/dri\n    group_add:\n      - 109  # render group\n```\n\n### Docker CLI Examples\n\n> **Note:** Docker supports both environment variables (shown below) and CLI arguments. To use CLI arguments, append them after the image name (e.g., `stevezzau/plex_generate_vid_previews:latest --plex-url http://... --plex-token ...`). See [Quick Start](#quick-start) for CLI argument examples.\n\n**NVIDIA GPU:**\n```bash\ndocker run --rm --gpus all \\\n  -e PLEX_URL=http://localhost:32400 \\\n  -e PLEX_TOKEN=your-token \\\n  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\\ Support/Plex\\ Media\\ Server \\\n  -v /path/to/plex/config:/config/plex \\\n  -v /path/to/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest\n```\n\n**AMD GPU:**\n```bash\ndocker run --rm \\\n  --device=/dev/dri:/dev/dri \\\n  --group-add 109 \\\n  -e PLEX_URL=http://localhost:32400 \\\n  -e PLEX_TOKEN=your-token \\\n  -e PLEX_CONFIG_FOLDER=/config/plex/Library/Application\\ Support/Plex\\ Media\\ Server \\\n  -v /path/to/plex/config:/config/plex \\\n  -v /path/to/media:/media \\\n  stevezzau/plex_generate_vid_previews:latest\n```\n\n### Advanced Usage\n\n**Process specific libraries:**\n```bash\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token \\\n  --plex-config-folder /path/to/plex/config \\\n  --plex-libraries \"Movies, TV Shows\"\n```\n\n**Use specific GPUs:**\n```bash\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token \\\n  --plex-config-folder /path/to/plex/config \\\n  --gpu-selection \"0,2\" \\\n  --gpu-threads 8\n```\n\n**CPU-only processing:**\n```bash\nplex-generate-previews \\\n  --plex-url http://localhost:32400 \\\n  --plex-token your-token \\\n  --plex-config-folder /path/to/plex/config \\\n  --gpu-threads 0 \\\n  --cpu-threads 8\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"s6-overlay-suexec: fatal: can only run as pid 1\" or container fails to start\n- **Cause**: You have `init: true` in your docker-compose.yml or using `--init` with docker run\n- **Why this breaks**: This container uses s6-overlay (LinuxServer.io base) as its init system. Docker's init conflicts with it.\n- **What you lose with `init: true`**:\n  - \u274c PUID/PGID support (file permissions will be wrong)\n  - \u274c Process supervision\n  - \u274c Proper initialization\n- **Solution**: \n  - **Docker Compose**: Remove `init: true` from your compose file\n  - **Docker CLI**: Remove the `--init` flag\n  - s6-overlay is MORE capable than Docker's basic init - you don't need both!\n- **Example**: See `docker-compose.example.yml` for correct configuration\n\n#### \"No GPUs detected\"\n- **Cause**: GPU drivers not installed or FFmpeg doesn't support hardware acceleration\n- **Solution**: \n  - Install proper GPU drivers\n  - Update FFmpeg to version 7.0+\n  - Use `--list-gpus` to check detection\n  - Fall back to CPU-only: `--gpu-threads 0 --cpu-threads 4`\n\n#### \"GPU permission denied\" (Intel/AMD VAAPI)\n- **Cause**: The container needs to run as a user that has GPU device permissions\n- **Solution**: Set `PUID` and `PGID` environment variables on the container\n- **The error message tells you what values to use** - look for your user ID in the output\n- **Example**:\n  ```bash\n  docker run -e PUID=1000 -e PGID=1000 --device /dev/dri:/dev/dri ...\n  ```\n\n#### \"PLEX_CONFIG_FOLDER does not exist\"\n- **Cause**: Incorrect path to Plex Media Server configuration folder\n- **Solution**:\n  - Verify the path exists: `ls -la \"/path/to/plex/Library/Application Support/Plex Media Server\"`\n  - Check for proper Plex folder structure (Cache, Media folders)\n  - Use absolute paths, not relative paths\n\n#### \"Permission denied\" errors\n- **Cause**: Insufficient permissions to access files or directories\n- **Solution**:\n  - Check file ownership: `ls -la /path/to/plex/config`\n  - Fix permissions: `chmod -R 755 /path/to/plex/config`\n  - For Docker: ensure proper user/group mapping\n\n#### \"Connection failed\" to Plex\n- **Cause**: Plex server not accessible or incorrect credentials\n- **Solution**:\n  - Verify Plex URL is correct and accessible\n  - Check Plex token is valid and not expired\n  - Test connection: `curl -H \"X-Plex-Token: YOUR_TOKEN\" http://localhost:32400/status/sessions`\n\n#### Docker GPU not working\n- **Cause**: Missing GPU runtime or device access\n- **Solution**:\n  - **NVIDIA**: Install NVIDIA Container Toolkit\n  - **AMD**: Add `--device=/dev/dri:/dev/dri --group-add 109`\n  - **Intel**: Add `--device=/dev/dri:/dev/dri --group-add 109`\n  - Test with: `docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi`\n\n#### \"Skipping as file not found\"\n- **Cause**: Incorrect path mappings or missing media files\n- **Solution**:\n  - Verify media file paths are correct\n  - Check path mappings in Plex settings\n  - For Windows mapped drives, use UNC paths: `\\\\server\\share\\path`\n\n#### \"No GPUs detected on Windows\"\n- **Cause**: GPU not detected or drivers not installed\n- **Solution**:\n  - Install latest GPU drivers (NVIDIA, AMD, or Intel)\n  - Verify GPU is working in Windows Device Manager\n  - Test with: `plex-generate-previews --list-gpus`\n  - If needed, use CPU-only: `--gpu-threads 0 --cpu-threads 4`\n\n### Debug Mode\n\nEnable debug logging for detailed troubleshooting:\n\n```bash\nplex-generate-previews --log-level DEBUG\n```\n\n### Getting Help\n\n1. Check the [GitHub Issues](https://github.com/stevezau/plex_generate_vid_previews/issues)\n2. Enable debug logging and check logs\n3. Verify your configuration with `--help`\n4. Test GPU detection with `--list-gpus`\n\n\n## FAQ\n\n### General Questions\n\n**Q: What's new in version 2.0.0?**\nA: Version 2.0.0 introduces multi-GPU support, improved CLI interface, better error handling, WSL2 support, and a complete rewrite with modern Python practices.\n\n**Q: Does this work on Windows?**\nA: Yes! Windows fully supports GPU acceleration via D3D11VA, which works with NVIDIA, AMD, and Intel GPUs. Install the latest GPU drivers and the tool will automatically detect and use your GPU for faster processing. \n\n**Q: Can I use this without a GPU?**\nA: Yes! Set `--gpu-threads 0` and use `--cpu-threads 4` (or higher) for CPU-only processing.\n\n**Q: How do I know which GPUs are detected?**\nA: Run `plex-generate-previews --list-gpus` to see all detected GPUs and their capabilities.\n\n**Q: Can I process specific libraries only?**\nA: Yes! Use `--plex-libraries \"Movies, TV Shows\"` to process only specific Plex libraries.\n\n**Q: What's the difference between thumbnail quality 1-10?**\nA: Lower numbers = higher quality but larger file sizes. Quality 2 is highest quality, quality 10 is lowest quality.\n\n### Performance Questions\n\n**Q: How many threads should I use?**\nA: Start with 4 GPU threads and 4 CPU threads. Adjust based on your hardware - more threads = faster processing but higher resource usage.\n\n**Q: Can I use multiple GPUs?**\nA: Yes! The tool automatically detects and can use multiple GPUs. Use `--gpu-selection \"0,1,2\"` to select specific GPUs.\n\n### Troubleshooting Questions\n\n**Q: \"Skipping as file not found\" error?**\nA: This usually means incorrect path mappings. Check your Docker volume mounts or Plex library path mappings.\n\n**Q: Docker GPU not working?**\nA: Ensure you have the proper GPU runtime installed (NVIDIA Container Toolkit, ROCm, etc.) and correct device access.\n\n**Q: How do I enable debug logging?**\nA: Use `--log-level DEBUG` or set `LOG_LEVEL=DEBUG` in your environment.\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/stevezau/plex_generate_vid_previews/issues)\n- **Documentation**: This README and inline help (`--help`)\n- **Community**: Check existing issues for solutions to common problems\n\n## Contributing\n\nWe welcome contributions! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Plex](https://www.plex.tv/) for the amazing media server\n- [FFmpeg](https://ffmpeg.org/) for video processing capabilities\n- [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- All contributors and users who help improve this project\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Generate video preview thumbnails for Plex Media Server",
    "version": "2.3.0",
    "project_urls": {
        "Homepage": "https://github.com/stevezau/plex_generate_vid_previews",
        "Issues": "https://github.com/stevezau/plex_generate_vid_previews/issues",
        "Repository": "https://github.com/stevezau/plex_generate_vid_previews"
    },
    "split_keywords": [
        "plex",
        " media",
        " server",
        " video",
        " thumbnails",
        " previews",
        " ffmpeg",
        " gpu",
        " acceleration"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b4284b769ae64528b878aade852da1f785ea604b5a1fd844c2f841c55383fb86",
                "md5": "cedf2aa3f086b4ca7145644bdff82408",
                "sha256": "f5baa053e1d822eaeb10bcd5bce84dd32404080aeb84f2049244e14a8359570d"
            },
            "downloads": -1,
            "filename": "plex_generate_previews-2.3.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cedf2aa3f086b4ca7145644bdff82408",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 75805,
            "upload_time": "2025-10-16T09:28:26",
            "upload_time_iso_8601": "2025-10-16T09:28:26.946050Z",
            "url": "https://files.pythonhosted.org/packages/b4/28/4b769ae64528b878aade852da1f785ea604b5a1fd844c2f841c55383fb86/plex_generate_previews-2.3.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "82cda3ef3266733b26dd18bb65f93673e230651ee222a5b107e7d48340ea6cf9",
                "md5": "ba36376ca98ce4e9aa9863585af89dc5",
                "sha256": "fbac18bc4f1dc1535cd2730caffce90a091fb0ab733daea4f0afbe3f2bb9072b"
            },
            "downloads": -1,
            "filename": "plex_generate_previews-2.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ba36376ca98ce4e9aa9863585af89dc5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 107694,
            "upload_time": "2025-10-16T09:28:28",
            "upload_time_iso_8601": "2025-10-16T09:28:28.349798Z",
            "url": "https://files.pythonhosted.org/packages/82/cd/a3ef3266733b26dd18bb65f93673e230651ee222a5b107e7d48340ea6cf9/plex_generate_previews-2.3.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-16 09:28:28",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "stevezau",
    "github_project": "plex_generate_vid_previews",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "plex-generate-previews"
}