FAQ¶
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¶
Related Docs¶
General¶
What does this tool 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 preview generation off the media server, on a machine of your choosing, using 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).
What Plex/Emby/Jellyfin settings should I use?¶
- 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 (
ExtractTrickplayImagesDuringLibraryScanandExtractChapterImagesDuringLibraryScan). The readiness card 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 Previews Readiness card on the Edit Server modal audits every required flag across all three vendors and offers one-click toggles — see the Previews Readiness 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 this work on Windows?¶
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 — raise CPU Workers in Settings, or run the container on a Linux host. There's no separate Windows native build. See Getting Started — Windows.
Does this generate chapter thumbnails?¶
No. This tool only generates video preview thumbnails (the timeline-scrubbing strip). It does not generate chapter thumbnails, intro/credit detection, or other server-side media analysis.
Can I use this without a GPU?¶
Yes. In Settings → Processing Options, disable all GPUs (or set workers to 0) and set CPU Workers to your desired value (e.g. 4 or 8).
Is Docker required? Is there a standalone .exe?¶
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 tool just 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
:romedia 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 I run this on a different machine than my media server(s)?¶
Yes. The tool 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/Jellyfin you just need the media files visible. See Networking for setup details.
Does this work with Jellyfin or Emby?¶
Yes. The app supports Plex, Emby, and Jellyfin — alone or in any combination. Each server is added under Settings → Media Servers. 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.
GPUs¶
How do I know which GPUs are detected?¶
Open Settings → Processing Options. The GPU panel lists all detected GPUs with their device IDs, names, and types.
Can I use multiple GPUs?¶
Yes. In Settings → Processing Options, enable individual GPUs and set workers and FFmpeg threads per GPU. Each GPU can be enabled/disabled independently.
Which GPU should I use?¶
| GPU Type | Best For |
|---|---|
| NVIDIA | Fastest for video processing |
| Intel iGPU | Great for low-power setups, common on Unraid |
| AMD | Good VAAPI support on Linux |
| CPU-only | Works everywhere, slower |
HDR / Dolby Vision support?¶
See the dedicated HDR & Dolby Vision section in Guides for the full per-vendor breakdown and expected speeds.
Performance¶
How many threads should I use?¶
Start with the defaults and increase gradually while monitoring system load. See the Performance Tuning 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.
Expected speeds on 4K content:
- SDR / HDR10 / HDR10+ / HLG / Dolby Vision Profile 7/8 — 15–60× across all GPU vendors.
- Dolby Vision Profile 5 (the trickier format, no HDR10 fallback layer):
- Intel (iGPU, Arc): ~17× — fastest path. Just needs the GPU passed to the container (
--device /dev/dri:/dev/dri). - NVIDIA: ~10–16× — needs
NVIDIA_DRIVER_CAPABILITIES=all(or at minimumcompute,video,utility,graphics) so the NVIDIA Vulkan driver is available inside the container. See HDR & Dolby Vision for the full explanation. - AMD / Apple / CPU-only: ~5–10× via software decode.
The FFmpeg Threads setting per GPU controls how many CPU cores each worker can use. If you're running multiple GPU workers and seeing CPU contention, lower this value.
How much RAM does each worker use?¶
Typical per-worker RSS with hardware decode:
| Content | Per-worker RSS |
|---|---|
| SDR 1080p | ~90–200 MB |
| 4K HDR10 / DV P7+8 | ~250–300 MB |
| 4K DV Profile 5 (libplacebo) | ~350–500 MB |
Earlier builds used ~1 GB per worker on 4K HDR content because frames were downloaded from the GPU at full source resolution. A recent fix moved the downscale onto the GPU itself, so only the small thumbnail-sized frame moves back to system RAM. An 8 GB container now comfortably supports 12+ GPU workers.
What's thumbnail quality 1-10?¶
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.
Generation feels disk-bound on my multi-disk setup (unraid/mergerfs/JBOD) — how do I speed it up?¶
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 the New Job modal (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.
How do I get the authentication token?¶
Use Authentication Token.
Processing¶
Can I process specific libraries only?¶
Yes. In Settings → Libraries, select which libraries to process.
How do I regenerate existing thumbnails?¶
When starting a job, use the Regenerate option to force regeneration of existing thumbnails.
Why is it "skipping" some files?¶
Possible causes:
- Thumbnails already exist (use the Regenerate option when starting a job to force)
- File not found (check path mappings)
- Invalid file format
Why does ETA show "Calculating..." for so long?¶
The ETA calculation is designed to be accurate, not fast:
- Initial skip burst (0–30 seconds) — shows "Calculating…"; many files may already have thumbnails and are skipped instantly.
- First few items processed (30s–5 min) — still shows "Calculating…"; real FFmpeg encoding is underway, but not enough data yet.
- Realistic estimate appears (5+ min) — shows time like "8h 30m"; calculated from actual per-item processing time, updates every 3 seconds.
- During processing — ETA counts down and adjusts in real-time as processing rate varies.
Early ETA guesses based on incomplete data are wildly inaccurate. The "Calculating…" phase filters out this noise.
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:
| Container | Might see the file as |
|---|---|
| Plex (or Emby, or Jellyfin) | /data/tv/Show/episode.mkv |
| Sonarr | /tv/Show/episode.mkv |
| This tool | /mnt/media/tv/Show/episode.mkv |
If you are not using webhooks, or every container uses the same media paths, leave the webhook column blank.