Getting Started

Generate preview thumbnails for Plex, Emby, Jellyfin, or any combination of them.

Prerequisites

1. At least one media server reachable from this container — any of:
   • Plex Media Server — sign in with your Plex account in the Setup Wizard, or enter a server URL + token if you can't reach plex.tv
   • Emby Server — server URL + username and password, or an API key
   • Jellyfin Server — use Quick Connect (a code you enter in Jellyfin, no password to type), or a username and password, or an API key
2. Docker installed on your server

The container can run on the same machine as your media server or on another one. If the best GPU is in a different machine, run the app anywhere and add that machine as a worker node.

You can configure several servers, even a mix of vendors. One FFmpeg pass publishes to every server that owns the file.

Quick Start (Docker)

Step 1: Run the Container

docker run -d \
  --name media-preview-generator \
  --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/media_preview_generator:latest

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

Step 2: Get Your Access Token

Find your token using the Authentication Token section below.

Step 3: Complete the Setup Wizard

1. Open http://YOUR_SERVER_IP:8080
2. Enter the authentication token
3. Follow the wizard. Its steps are Server type, Connect, Paths, Options and Security:
   • Step 1 — Choose your media server: click Plex, Emby or Jellyfin.
     • Plex → Sign in with Plex, then Next. If plex.tv is blocked, open Can't reach plex.tv? Enter server details manually, enter the URL and token, and click Verify connection.
     • Emby → enter the server URL, then choose Username + Password or API Key. Click Test connection, then Save server.
     • Jellyfin → enter the server URL, then choose Quick Connect, Username + Password or API Key. With Quick Connect, click Start Quick Connect and enter the code it shows in your Jellyfin profile menu. Then click Test connection and Save server.
     • Skip for now ends the wizard and takes you to Servers, where you can add servers later.
   • Step 2 — Connect your server (Plex only): pick the Plex server, then tick the libraries to monitor. Tick none to monitor all. Emby and Jellyfin skip this step. Their libraries come in when you save the server, and you manage them later in Servers → Edit → Libraries.
   • Step 3 — Where are your files?: for Plex, confirm the Plex Media Server data folder (usually /plex in this container). Use Check a real file to confirm this container can read a media file at the path your server reports. Under Advanced, add path mappings and exclude paths if you need them.
   • Step 4 — Processing options: GPU device tuning lists detected GPUs (Re-scan GPUs re-detects them). Below it, set up your worker groups, then the Thumbnails interval and quality. These are shared by every configured server.
   • Step 5 — Set your access token: choose a new token (at least 8 characters, different from the current one), then click Complete Setup. If WEB_AUTH_TOKEN is set, the token is fixed and this step says so.

You can add more servers, any vendor and any number of each, at any time with Servers → Add Server. A file present on multiple servers is generated once and published to each in its native format. To go through the wizard again, use Tools → Run setup again.

Recommended media-server settings

This app's main job is video preview thumbnails, the small frames you see when you drag the scrub bar. Plex stores them as BIF bundles, Emby reads a BIF sidecar next to the media file, and Jellyfin reads a folder of JPG tile sheets called trickplay next to the media file. The app writes the right format for each. Optional CPU generation of Plex chapter thumbnails is also available for Plex 1.43.4.x or 1.43.5.x, off by default. It can also send Skip Intro / Skip Credits markers to your servers, off until you turn it on per server (see the Intro & Credits guide).

Turn off built-in preview generation on each server you configure so this tool isn't competing with a redundant CPU job:

• Plex — Settings → Library → Generate video preview thumbnails → Never.
• Emby — Emby can make its own thumbnails during library scans. Turn off its scan-time thumbnail extraction and chapter-image extraction on each library (ExtractTrickplayImagesDuringLibraryScan and ExtractChapterImagesDuringLibraryScan). The Setup Health tab recommends this and turns them off when you click Disable; the app never changes them on its own.
• Jellyfin — keep "Trickplay image extraction" enabled on each library (Jellyfin only reads this app's published tiles when that flag is on). What to do with "Extract trickplay images during library scan" depends on the Media Preview Bridge plugin:
  • Plugin installed: turn it off. The plugin registers new tiles directly, so Jellyfin's own extraction is wasted CPU.
  • No plugin: keep it on. Without the plugin, this flag is what lets Jellyfin pick up the tiles on its next library scan. Off means new previews wait for Jellyfin's daily trickplay task (3 AM by default).

The Setup Health tab (Servers → Edit) checks all of these and can toggle them for you.

Volume Mounts

Which servers need the media mounted read-write:

• Plex: no. Previews go into /plex. Nothing is written next to the video, so :ro is fine.
• Emby: yes. The BIF is written next to each video (for example <video>-320-10.bif).
• Jellyfin, default layout: yes. Tiles are written next to each video (<video>.trickplay/).
• Jellyfin, off-media mode: no. Tiles go into Jellyfin's data folder instead. This needs the Media Preview Bridge plugin and Jellyfin's config folder mounted read-write in this container. See off-media mode.

With a :ro media mount, Emby and default-layout Jellyfin can't save anything. Each file fails for that server with "Could not write preview file: … Read-only file system" in the job's per-server result and the logs. Those files aren't retried. Other servers on the same file are unaffected. No setup check warns about this in advance.

Authentication Token

Use this section whenever documentation asks for your authentication token.

On first start the app makes a random token and saves it in auth.json, in the folder you mounted as /config. The logs show only its last 4 characters, so read it from that file:

docker exec media-preview-generator cat /config/auth.json

You can also set a fixed token for predictable logins:

WEB_AUTH_TOKEN=your-password

Docker Compose

See docker-compose.example.yml for ready-to-use configurations:

Copy the file, uncomment the section for your hardware, and adjust volume paths.

GPU Acceleration

Hardware-accelerated video processing for faster thumbnail generation. To use a GPU in another machine, add it as a worker node. To check what's detected on your system, open the web UI (http://YOUR_IP:8080) and go to Settings → Processing options → GPU device tuning. Detected GPUs are listed there with device IDs, names, and types. The setup wizard shows the same list in step 4.

Supported GPUs

Intel iGPU (QuickSync)

Most common setup, especially on Unraid.

docker run -d \
  --device /dev/dri:/dev/dri \
  -e PUID=1000 \
  -e PGID=1000 \
  stevezzau/media_preview_generator:latest

Verify the device exists:

ls -la /dev/dri
# Should show: card0, renderD128

The container auto-detects GPU device groups at startup and adds the internal user to them. If you still see permission errors, check that you are passing the entire /dev/dri directory (not a single sub-device):

# Correct — pass the whole directory
--device /dev/dri:/dev/dri

# Wrong — single device may prevent group auto-detection for other nodes
--device /dev/dri/renderD128:/dev/dri/renderD128

To debug, find the device group on the host:

stat -c '%g' /dev/dri/renderD128
# Common groups: 'video' (44), 'render' (105) — varies by distro

NVIDIA GPU

Prerequisites (Linux hosts):

1. Install NVIDIA drivers
2. Install NVIDIA Container Toolkit

docker run -d \
  --gpus all \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=all \
  stevezzau/media_preview_generator:latest

Docker Compose:

services:
  plex-previews:
    image: stevezzau/media_preview_generator:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

AMD GPU

docker run -d \
  --device /dev/dri:/dev/dri \
  -e PUID=1000 \
  -e PGID=1000 \
  stevezzau/media_preview_generator:latest

AMD requires proper VAAPI drivers on the host system. GPU device groups are auto-detected at container startup.

Windows

NVIDIA: works under Docker. Requirements:

1. Docker Desktop using the WSL2 backend (Settings → General → Use the WSL 2 based engine) — GPU support is WSL2-only, it does not work with the Hyper-V backend.
2. A current NVIDIA Windows driver with WSL2 GPU paravirtualization support. This is what provides CUDA and NVDEC inside WSL2.
3. An up-to-date WSL2 kernel — run wsl --update.

Then use the same docker run command as Linux, including --gpus all; see NVIDIA GPU above. There is nothing to install inside WSL itself, and the NVIDIA Container Toolkit step is not needed — Docker Desktop wires that up for you.

Omit --device /dev/dri:/dev/dri on Windows. Under WSL2 that node is a WSLg/d3d12 stub rather than a real GPU, and passing it through can register a phantom device or muddy vendor detection.

Verify by opening the web UI and checking Settings → Processing options → GPU device tuning; your card should be listed with CUDA acceleration.

Plex installed on Windows (not in Docker): previews work as they are. Intro & Credits, chapter thumbnails, loudness and Library Health's full counts use Plex's database, which Docker Desktop's mount of a Windows folder can't open safely. Run the Plex database node for Windows beside Plex and add it as http://host.docker.internal:9494 (see Plex on another machine).

AMD and Intel: not accelerated under Docker. These rely on D3D11VA, a Windows-only framework that Docker Desktop's Linux VM cannot reach, so processing falls back to CPU. Add CPU workers in Settings → Workers to compensate. Or run a worker node on a Linux machine with the GPU.

macOS

Not accelerated under Docker, on either Apple Silicon or Intel. VideoToolbox is a macOS framework and Docker Desktop's Linux VM has no access to it, so processing uses CPU. Add CPU workers in Settings → Workers to compensate, or run the container on a Linux host for GPU acceleration.

Apple Silicon Macs still benefit from the native ARM64 image: it runs without Rosetta emulation, so CPU processing is faster than with an emulated x86 image.

Worker Configuration

A worker is a parallel slot that processes one file at a time. More workers means more files at once, but higher CPU/GPU load.

Workers are set up in worker groups under Settings → Workers. Each group has a name, when it is available (always, or on a weekly schedule) and up to 8 devices. Each device is the CPU or a specific GPU, with a worker count from 1 to 32 and the job types it runs (previews, intro & credits, and loudness on the CPU only). For CPU-only mode, use CPU devices only.

Settings → Processing options → GPU device tuning sets FFmpeg threads per worker for each GPU: how many CPU threads each GPU worker may use. The default is 2, and 0 means no cap.

Start with a few workers and raise the count while you watch system load. Devices on worker nodes appear here too. The Dashboard's Workers panel shows each group's and device's activity. Manage groups opens the group settings.

Unraid

Two install paths: the Community Applications template (easiest) or a manual docker run command (more control).

Easiest: search for media-preview-generator in Community Applications and install the template.

Quick start (either path):

1. Run the container (CA template or docker run below).
2. Open the Web UI at http://YOUR_UNRAID_IP:8080.
3. Sign in with the token from auth.json in the app's config folder (/mnt/user/appdata/media-preview-generator in the example below), or set WEB_AUTH_TOKEN on the container.
4. Complete the Setup Wizard — connect a server and review the options.

Manual Docker Run — Intel iGPU (Most Common)

docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  -p 8080:8080 \
  -l net.unraid.docker.webui="http://[IP]:[PORT:8080]/" \
  --device /dev/dri:/dev/dri \
  -e WEB_AUTH_TOKEN=my-secret-password \
  -e PUID=99 \
  -e PGID=100 \
  -v /mnt/user/data/plex:/data/plex:ro \
  -v "/mnt/cache/appdata/plex/Library/Application Support/Plex Media Server":/plex:rw \
  -v /mnt/user/appdata/media-preview-generator:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

Intel iGPU with Custom Network (br0/br1)

If you use a custom Docker network with fixed IPs (common on Unraid):

docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  --network=br0 \
  --ip=192.168.1.50 \
  --device /dev/dri:/dev/dri \
  -e WEB_AUTH_TOKEN=my-secret-password \
  -e PUID=99 \
  -e PGID=100 \
  -v /mnt/user/data/plex:/data/plex:ro \
  -v "/mnt/cache/appdata/plex/Library/Application Support/Plex Media Server":/plex:rw \
  -v /mnt/user/appdata/media-preview-generator:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

NVIDIA GPU on Unraid

Requires: Nvidia-Driver plugin from Community Applications.

docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  --runtime=nvidia \
  -p 8080:8080 \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=all \
  -e WEB_AUTH_TOKEN=my-secret-password \
  -e PUID=99 \
  -e PGID=100 \
  -v /mnt/user/data/plex:/data/plex:ro \
  -v "/mnt/cache/appdata/plex/Library/Application Support/Plex Media Server":/plex:rw \
  -v /mnt/user/appdata/media-preview-generator:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

Important Unraid Notes

PUID/PGID Values — Unraid uses nobody:users by default:

Emby or Jellyfin on Unraid — the commands above are for Plex. For Emby, or Jellyfin in its default layout, change /data/plex:ro to /data/plex:rw, because those previews are written next to each video. See Volume Mounts.

Network Considerations — When completing the Setup Wizard, make sure each media server you pick is reachable from the container (not localhost from Unraid's perspective). Plex servers appear in a dropdown after sign-in; Emby and Jellyfin are connected by URL.

Check Intel GPU Exists:

ls -la /dev/dri
# Should show: card0, renderD128

Path Mapping for Plex

Path mapping is only needed when this container mounts media to a different path than Plex uses.

No Mapping Needed (Recommended) — mount media to the same container path as Plex:

Plex:           /mnt/user/data/plex → /data/plex
This container: /mnt/user/data/plex → /data/plex  ← Same path!

With Path Mapping — if you prefer mounting to /media:

Plex:           /mnt/user/data/plex → /data/plex
This container: /mnt/user/data/plex → /media      ← Different path

Add the mapping in the wizard (step 3, Advanced) or later in Servers → Edit → Path mappings:

• Path on the server: /data/plex
• Path in this app: /media

See Path Mappings for more examples.

TRaSH Guide Folder Structure

For users following TRaSH Guides:

1. Configure Plex Container — add a second container path:
   • Container path: /server/media/plex/
   • Host path: /mnt/user/media/plex/
2. Update Plex Libraries — use the new mapping:
   • Format: //server/media/plex/<media-folder>
   • Example: //server/media/plex/tv
3. Set Permissions:

   # Make the Plex Media folder writable by the Unraid 'users' group (PGID=100)
   # so this app's container (running as PUID=99 / PGID=100) can write previews into it.
   chown -R 99:100 /mnt/cache/appdata/plex/Library/Application\ Support/Plex\ Media\ Server/Media/
   chmod -R 775   /mnt/cache/appdata/plex/Library/Application\ Support/Plex\ Media\ Server/Media/
   

   (Older guides recommended chmod 777 — that works but grants world-writable access; chown + 775 is the safer equivalent.)

Networking

Quick Decision Tree

Where is the media server?
│
├── Same Docker host as this app?
│   ├── Server uses host network      → Use --network host
│   ├── Server uses bridge (default)  → Use same network or server IP:port
│   └── Server uses custom (br1, macvlan) → Use same custom network
│
└── Different machine?
    └── Use bridge network with the server's IP address

If Plex runs on another machine and you want Intro & Credits markers, chapter thumbnails or loudness, also run a Plex database node beside it.

The same logic applies whether the target is Plex (port 32400), Emby (port 8096), or Jellyfin (port 8096). If you run more than one server, check each is reachable from the container independently — the Servers page shows a red status dot on any server card the app can't reach.

Custom Network Example (Unraid)

docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  --network=br1 \
  --ip=192.168.1.51 \
  -l net.unraid.docker.webui="http://[IP]:[PORT:8080]/" \
  --device /dev/dri:/dev/dri \
  -e WEB_AUTH_TOKEN=your-password \
  -e PUID=99 \
  -e PGID=100 \
  -v /mnt/user/data/plex:/data/plex:ro \
  -v "/mnt/cache/appdata/plex/Library/Application Support/Plex Media Server":/plex:rw \
  -v /mnt/user/appdata/media-preview-generator:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

Common Operations

View Logs

docker logs media-preview-generator          # All logs
docker logs -f media-preview-generator       # Follow logs

Update

docker pull stevezzau/media_preview_generator:latest
docker stop media-preview-generator
docker rm media-preview-generator
# Re-run your docker run command

Your /config/settings.json persists between upgrades, so server connections, worker groups, and schedules come back automatically after re-running the container.

Image Tags

See the releases page for version history and per-release notes.

The web UI's version banner behaves accordingly: :latest / pinned versions compare against the latest GitHub release; :dev compares the baked commit SHA against the dev branch HEAD on GitHub.

Next Steps

• Run and monitor jobs from the Web Interface Guide
• Configure webhooks in Webhook Integration
• Review all tunables in Configuration & API Reference

Related Docs

• Guides & Troubleshooting
• Configuration & API Reference
• FAQ
• Contributing & Development