FAQ

Back to Docs

Common questions about setup, usage, and behavior. For troubleshooting specific errors, see Guides — Troubleshooting. For HDR and Dolby Vision behavior, see Guides — HDR & Dolby Vision.

Contents

• Common questions
• General
• Intro & Credits
• GPUs
• Performance
• Docker
• Processing

Related Docs

• Getting Started
• Guides & Troubleshooting
• Configuration & API Reference

Common questions

Why are my Plex preview thumbnails taking so long?

Plex makes them inside the server, on the CPU, one frame every 2 seconds by default, during its scheduled maintenance window and optionally when media is added. Plex's own help page says a large library can take days. You can space the frames out in Plex, or hand the job to a GPU with this app, which starts on each file as it arrives. More: Why Plex previews are slow

Can I generate Plex preview thumbnails with a GPU?

Not with Plex itself: Plex documents no GPU option for this job. Media Preview Generator runs it with FFmpeg on an NVIDIA, Intel or AMD GPU and writes the result where Plex expects it, in Plex's data folder, which it needs read-write. More: Plex previews with a GPU

How do I make Jellyfin trickplay generation faster?

Start with Jellyfin's own settings: hardware decoding, key-frame-only extraction, and more FFmpeg threads than the default of 1. If it still falls behind, this app can make the trickplay tiles on a GPU, also another machine's (remote nodes), and tell Jellyfin about them. More: Faster Jellyfin trickplay

Does Emby's thumbnail extraction use the GPU?

No. Emby's built-in BIF extraction has no GPU option. This app makes Emby BIF files on a GPU and saves them next to each video, where Emby looks for them, so the media folder must be writable. More: Emby BIF previews with a GPU

Can previews be made as soon as Sonarr or Radarr imports a file?

Yes. Add a webhook in Sonarr or Radarr for import and upgrade. The app waits for a quiet period (60 seconds by default), makes the previews, and retries while the media server is still indexing the new file. More: Previews on Sonarr or Radarr import

Why are my HDR or Dolby Vision preview thumbnails washed out or green?

The frames were grabbed without tone mapping, so HDR colours land in an ordinary picture. This app tone-maps HDR10, HLG and HDR10+, and uses the HDR10 layer of Dolby Vision profiles 7 and 8. Profile 5 needs a GPU with a hardware Vulkan driver in the container. More: HDR and Dolby Vision previews

General

What does Media Preview Generator do?

Generates video preview thumbnails for Plex, Emby, and Jellyfin, alone or in any combination. These are the small images you see when scrubbing through videos. It runs off the media server, on a machine you choose, and uses every GPU it finds. When two or more of your servers contain the same file, FFmpeg runs only once and the output is written in each server's expected format (Plex stores it as a BIF bundle, Emby reads a BIF sidecar file next to the video, Jellyfin reads a folder of JPG tiles called trickplay). It can also add Skip Intro and Skip Credits markers: see Intro & Credits.

Which Plex, Emby and Jellyfin settings should I change?

• Plex: In Settings → Library, set "Generate video preview thumbnails" to 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; it changes them only when you click Disable.
• Jellyfin: In each library's settings, enable "Trickplay image extraction" (Jellyfin reads this app's published tiles only when this is on). For "Extract trickplay images during library scan": turn it off if the Media Preview Bridge plugin is installed. Without the plugin, keep it on — it's how Jellyfin picks up the tiles on its next scan.

The Setup Health tab on the Edit Server modal audits every required flag across all three vendors and offers one-click toggles — see the Setup Health guide. Destructive flips (like disabling Jellyfin's trickplay extraction) require typed confirmation.

Disabling each vendor's built-in generation avoids duplicate work and prevents the server from using CPU for thumbnails when you want this app to handle them. The one exception is Jellyfin without the plugin, as above.

Does it run on Windows or Unraid?

Yes. Run the Docker image on Docker Desktop with the WSL2 backend. If you have an NVIDIA GPU it is accelerated: the NVIDIA Windows driver exposes CUDA and NVDEC into WSL2, so --gpus all works much as it does on Linux (best-effort: WSL2 GPU detection is less reliable than native Linux). AMD and Intel GPUs are not accelerated under Docker (D3D11VA can't be reached from Docker's Linux VM), so those setups process on CPU — add CPU workers under Settings → Workers, or add a Linux machine with the GPU as a worker node. There's no separate Windows native build. See Getting Started — Windows. There is an Unraid Community Applications template: see Unraid.

Does it make chapter thumbnails too?

Yes, optionally for Plex Media Server 1.43.4.x or 1.43.5.x. Chapter generation is off by default and uses CPU, separately from GPU-accelerated scrubber previews. It requires one media version and one part per item; see the chapter thumbnail guide for setup and limits.

Do I need a GPU to use Media Preview Generator?

No. Under Settings → Workers, use a worker group with only a CPU device and set its worker count (for example 4 or 8). Remove GPU devices or switch off groups that use them.

Is there a Windows .exe, or do I need Docker?

Docker is required. There is no standalone executable and no from-source install path. The container bundles the FFmpeg build and codec support the app depends on, so Docker is the only supported deployment. See Getting Started for setup. It runs on Linux, Windows (Docker Desktop, WSL2 backend), macOS, Unraid, Synology, and anywhere else Docker runs.

Does my media server need to run in Docker too?

No. Plex, Emby, and Jellyfin can all run bare-metal, in Docker, or any other way. This app needs:

• Network access to each server's API (port 32400 for Plex, 8096 for Emby/Jellyfin by default).
• For Plex specifically: read/write access to the Plex application data directory (where BIF bundles are stored — mounted as /plex).
• For Emby and Jellyfin: read-write access to the media files, because Emby BIFs and Jellyfin trickplay tiles are written next to each video. A :ro media mount makes every write fail for those servers. No server-config mount needed. The exception is Jellyfin's off-media mode: it writes into Jellyfin's config folder instead, so that folder must be read-write and the media can stay read-only.
• For Plex only: read access to the media is enough.

Can it run on a different machine from Plex, Emby or Jellyfin?

Yes. The app can run anywhere that can reach your servers' APIs over the network. For Plex you also need access to the Plex config directory (NFS, SMB, shared volume, etc.). For Emby and Jellyfin you need the media files visible. See Networking for setup details. For Intro & Credits, chapter thumbnails or loudness on a Plex on another machine, run a Plex database node beside Plex. To use a GPU in another machine, add it as a worker node.

Does it work with Jellyfin and Emby, not just Plex?

Yes. The app supports Plex, Emby, and Jellyfin, alone or in any combination. Each server is added on the Servers page. When two or more servers contain the same file, FFmpeg runs only once and the result is written in each server's expected format (Plex stores it as a BIF bundle, Emby reads a BIF sidecar file next to the video, Jellyfin reads a folder of JPG tiles called trickplay). See the Multi-Server guide for setup, webhook routing, and per-server library/exclude rules.

Intro & Credits

Does it add Skip Intro and Skip Credits buttons?

Yes, on Plex, Emby and Jellyfin, once you turn it on for each server. What each server needs:

• Plex: needs Plex Pass on the server, and for viewers (or their Plex Home). The app runs on the same machine as Plex, or a Plex database node runs there for it.
• Jellyfin 10.11 or 12.0: the Media Preview Bridge plugin.
• Emby 4.9 or 4.10: the Media Preview Bridge for Emby plugin. Skip Intro also needs Emby Premiere, which is Emby's rule; Skip Credits doesn't.

More: Skip Intro and Skip Credits

How does it find intros and credits?

From the file's chapters, online skip databases, the theme song a season's episodes share, or the credit roll itself. It does this once per file and sends the result to every server that has the file. If it can't confirm an intro or credits from the file itself, it writes nothing — you can still add or adjust one in the Inspector.

Will it overwrite Plex's or Emby's own markers?

Only with Use ours, which is the default. Choose Keep Plex's or Keep Emby's in the server's Intro & Credits settings and it leaves them alone.

GPUs

How do I check which GPUs it found?

Open Settings → Processing options → GPU device tuning. It lists each detected GPU with its name and device. Re-scan GPUs checks again. The Workers panel on the Dashboard shows which groups use them.

Can it use more than one GPU?

Yes. In Settings → Workers, add each GPU as a device in a worker group and set its worker count. GPUs in other machines can join as worker nodes. Each group can run on its own hours. FFmpeg threads per worker for each GPU is under Settings → Processing options → GPU device tuning.

Which GPU is best for preview thumbnails?

Whichever one you already have. Any GPU the container can reach decodes the video; with none, the CPU does it, more slowly.

Does it handle HDR and Dolby Vision?

Yes. It tone-maps HDR10, HLG and HDR10+ so thumbnails don't come out grey, and uses the HDR10 layer of Dolby Vision Profile 7 and 8; Profile 5 has its own path for each GPU vendor. See the HDR & Dolby Vision section in Guides for the per-vendor details.

Performance

How many workers and threads should I set?

Set each device's worker count in Settings → Workers (1 to 32). Start low and raise it while watching system load. See the Worker Configuration table in Getting Started for concrete starting points across hardware tiers.

Why is CPU usage high when I have a GPU configured?

GPU workers use both GPU and CPU. This is normal. The GPU handles video decoding and downscaling to thumbnail size; the CPU handles frame selection, JPEG encoding, and (for HDR content) part of the colour conversion. Standard SDR content barely uses the CPU at all; HDR content, especially Dolby Vision, uses noticeably more because frames have to move between CPU and GPU memory for the colour conversion step.

Dolby Vision Profile 5 (no HDR10 fallback layer) needs the most from your setup:

• Intel (iGPU, Arc): just pass the GPU to the container (--device /dev/dri:/dev/dri).
• NVIDIA: set NVIDIA_DRIVER_CAPABILITIES=all (or at minimum compute,video,utility,graphics) so the NVIDIA Vulkan driver is available inside the container. See HDR & Dolby Vision for the full explanation.
• AMD (Radeon): decoded on the GPU and tone-mapped through Vulkan, as for NVIDIA. Not yet tested on AMD hardware.
• Apple / CPU-only: no hardware Vulkan, so Profile 5 thumbnails come out with a green and purple tint (Limits).

FFmpeg threads per worker (Settings → Processing options → GPU device tuning, one value per GPU) caps the CPU threads each GPU worker may use. The default is 2 and 0 means no cap. If several GPU workers fight over the CPU, lower it.

How much RAM does each worker use?

Typical per-worker RSS with hardware decode:

What does thumbnail quality 1-10 change?

Lower numbers = higher quality but larger file sizes.

• Quality 2 = highest quality
• Quality 4 = default (good balance)
• Quality 10 = lowest quality

The value is passed straight to FFmpeg's -q:v. FFmpeg's MJPEG encoder clamps qscale to a minimum of 2, so setting 1 produces byte-identical output to 2 — 2 really is as sharp as it goes.

Why is generation slow on my Unraid or mergerfs array?

On setups where one share is backed by multiple physical disks (unraid's shfs, mergerfs, JBOD), parallel workers processing files in alphabetical order tend to pile onto one disk at a time. Open Start new job (or edit a full-library schedule) and set Processing Order to Random. Workers will pull items from different disks in parallel, so disk read throughput — not GPU — sets the ceiling. Webhook jobs and Recently Added scans don't expose this setting because they only touch a handful of files where ordering doesn't matter. See Issue #219 for background.

Docker

Why does my container fail to start?

Most common cause: init: true in your docker-compose. Remove it — this container manages its own processes internally, and init: true conflicts with that.

Why can't the container find my files?

Path mapping issue. See Path Mappings.

Where do I find the login token?

Use Authentication Token.

Processing

Can I make previews for some libraries only?

Yes. On the Servers page, edit a server and use its Libraries tab to choose which libraries get previews.

How do I redo previews that already exist?

When you start a job, choose Regenerate all instead of Missing only.

Why does it skip some files?

Possible causes:

• Thumbnails already exist (choose Regenerate all when starting a job to force)
• File not found (check path mappings)
• Gone from disk: a newer file replaced it before its job ran (the newer file is processed on its own)
• Invalid file format

Why does a worker's ETA show "-"?

Each worker's ETA is the time left on the file it is working on, worked out from how far FFmpeg has got through the file and how fast it is going. It reads "-" until FFmpeg reports how far it has got. Before FFmpeg starts, for example while the worker is finding the file on a server or reusing frames it already made, the card shows that step instead of an ETA.

What is the webhook / Sonarr / Radarr path column for?

Only relevant if you use webhook integration. When Sonarr, Radarr, or Tdarr fire a webhook, they include the file path as they see it inside their container, which may differ from how your media server sees it and how this app sees it. The webhook column in each server's path-mapping row translates between them. For example:

If you are not using webhooks, or every container uses the same media paths, leave the webhook column blank.