Skip to content

Custom FFmpeg

Screenshots from HDR content need ffmpeg filters that not every build ships:

  • HDR10 / HDR10+ / Dolby Vision Profile 7 and 8 need zscale and tonemap for HDR-to-SDR conversion. Both are required: tonemap expects linear light and zscale is what linearizes the PQ input, so tonemap on its own is not a usable fallback. Without the pair, screenshots are written out untonemapped and look washed out and grey. Some environments — notably seedbox providers like Ultra.cc — ship ffmpeg without these filters.
  • Dolby Vision Profile 5 needs the libplacebo filter plus a working Vulkan device. Without it screenshots have a green/purple color cast, see Dolby Vision Profile 5 below.

This guide sets up a self-contained ffmpeg build and points upPollo at it.

You need this if upPollo warns during an HDR upload:

[WARN] HDR source: screenshots will not be tonemapped and will look washed out and grey because ...

or if upPollo warns during a Profile 5 upload:

[WARN] Dolby Vision Profile 5: screenshots will have a green/purple color cast because ...

Setup

The GPL static builds from BtbN/FFmpeg-Builds include all required filters (LGPL builds do not).

Linux (most seedboxes):

wget https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz
tar -xf ffmpeg-master-latest-linux64-gpl.tar.xz -C ~/
mv ~/ffmpeg-master-latest-linux64-gpl ~/ffmpeg
chmod +x ~/ffmpeg/bin/ffmpeg ~/ffmpeg/bin/ffprobe

macOS: brew install ffmpeg (then use /opt/homebrew/bin on Apple Silicon or /usr/local/bin on Intel as the path below), or the matching darwin64/darwinarm64 build from BtbN. Windows: ffmpeg-master-latest-win64-gpl.zip.

2. Verify the filters

~/ffmpeg/bin/ffmpeg -filters | grep -E "zscale|tonemap"

Both filters should be listed.

Blu-ray ISO screenshots

Blu-ray ISO uploads are analyzed directly with go-bdinfo; the ISO is not mounted or unpacked. Screenshots need no special FFmpeg build: upPollo reads the image's UDF structure, locates the stream files of the selected playlist and passes FFmpeg the byte range around each screenshot position, which is a plain MPEG-TS stream. A build without libbluray works.

The selected playlist is probed through the same byte range the screenshots are taken from, so HDR and Dolby Vision on a full disc are detected and tonemapped like any other source — zscale and tonemap are needed here too.

Encrypted commercial ISOs are not supported, because their stream files cannot be read as plain MPEG-TS.

DVD ISO screenshots

DVD ISO/IMG uploads do not require a special FFmpeg protocol. upPollo extracts the main title's IFO and VOB files to a temporary directory and uses the same MediaInfo and FFmpeg flow as an unpacked VIDEO_TS folder.

3. Point upPollo at it

screenshots:
    custom_ffmpeg_path: "/home/username/ffmpeg/bin"

The path must be absolute and point to the directory containing both ffmpeg and ffprobe — not to a binary.

Dolby Vision Profile 5

Profile 5 has no HDR10-compatible base layer. What the decoder produces is IPT-PQ-c2, not YCbCr, and the per-frame matrices needed to turn it into normal colors are carried in the Dolby Vision RPU inside the stream. ffmpeg's software filters cannot apply the RPU, so any screenshot taken without it keeps a green/purple cast, no matter which tonemapping is used. libplacebo can apply it, on the GPU.

upPollo detects Profile 5 from dv_profile in the stream's side data, checks once per run whether libplacebo really works, and then either uses it or warns and leaves the frame untouched. Tonemapping a Profile 5 frame as if it were HDR10 is not attempted: with the color tags these files usually lack, the zscale chain fails outright (no path between colorspaces).

Only Profile 5 uses libplacebo. HDR10 and Profile ⅞ keep the software chain, which needs no Vulkan device.

Requirements

  1. ffmpeg built with --enable-libplacebo, and
  2. a Vulkan device ffmpeg can create.

Check both at once — this is the same probe upPollo runs:

ffmpeg -hide_banner -init_hw_device vulkan -f lavfi -i color=c=black:s=64x64 \
  -vf libplacebo -frames:v 1 -f null -

No output means it works. Unable to open the libvulkan library! or Device creation failed means the Vulkan side is missing.

Linux

The BtbN GPL builds include libplacebo. The Vulkan driver comes from the distribution:

# Debian/Ubuntu, discrete or integrated GPU
sudo apt install mesa-vulkan-drivers vulkan-tools
vulkaninfo --summary

On a headless server without a usable GPU, mesa-vulkan-drivers also provides the software renderer (lavapipe). It works, but see the note under Software rendering.

macOS

macOS has no native Vulkan, so it runs through MoltenVK. Homebrew's regular ffmpeg formula has no libplacebo; ffmpeg-full does:

brew install ffmpeg-full vulkan-loader molten-vk

ffmpeg-full is keg-only, so it does not replace an existing ffmpeg. Its directory is what goes into custom_ffmpeg_path:

screenshots:
    custom_ffmpeg_path: "/opt/homebrew/opt/ffmpeg-full/bin"

Two environment variables are needed, because the Vulkan loader has to be told where its driver is, and ffmpeg loads the loader itself by name only — Homebrew's lib directory is not in dyld's search path:

export VK_ICD_FILENAMES=/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib:/usr/local/lib:/usr/lib

Use DYLD_FALLBACK_LIBRARY_PATH, not DYLD_LIBRARY_PATH: the latter takes precedence over the absolute library paths of a Homebrew ffmpeg and stops it from starting. On Intel Macs replace /opt/homebrew with /usr/local. upPollo passes its own environment on to ffmpeg, so exporting these in the shell (or the service unit) that starts upPollo is enough.

Windows

The BtbN win64-gpl build includes libplacebo, and the Vulkan runtime comes with current GPU drivers. Nothing else to set up.

Docker

The upPollo image ships ffmpeg with libplacebo but no Vulkan driver, so Profile 5 screenshots are not corrected inside the container. Options:

  • Pass a GPU into the container and install the matching Vulkan driver in a derived image.
  • Install the software renderer in a derived image:
FROM uppollo/uppollo:stable
USER root
RUN apk add --no-cache mesa-vulkan-swrast
ENV LP_NUM_THREADS=1
USER uppollo

LP_NUM_THREADS=1 is not optional, see below. - Generate screenshots outside the container.

Software rendering

Mesa's software renderer (lavapipe) runs the filter without a GPU, but with more than one thread it produced visible horizontal banding in testing: measured as the largest brightness step between neighbouring rows, a 3840x1920 frame came out at 15.0 against 0.45 on a GPU. With LP_NUM_THREADS=1 the same frame matched the GPU result (0.45), at the cost of speed. If you rely on the software renderer, set LP_NUM_THREADS=1 and check a few screenshots before uploading.

Validation and fallback

Before generating screenshots, upPollo checks that the directory exists, both binaries are present and executable, and that they actually run (catching wrong-architecture downloads). If any check fails, it logs the error and falls back to ffmpeg/ffprobe from the system PATH, so screenshot generation keeps working either way.

With logging.level: "debug" you can see which binaries and filters are used:

[DEBUG] Using custom ffmpeg from: /home/username/ffmpeg/bin/ffmpeg
[DEBUG] HDR detected: Using zscale+tonemap for HDR→SDR conversion
[DEBUG] Dolby Vision profile 5 detected: applying the RPU with libplacebo

Common errors

Error Cause and fix
exec format error Binary built for a different OS/architecture — download the matching build (linux64, darwin64, darwinarm64, win64)
ffmpeg not found or not executable Missing execute permission — chmod +x both binaries
custom_ffmpeg_path ... is not a valid directory Path doesn't exist or points at a file — it must be the bin directory containing both binaries
Washed-out HDR screenshots despite custom build Build lacks the filters — verify with step 2; use a GPL (not LGPL) build
this ffmpeg build has no libplacebo filter Build without --enable-libplacebo — on macOS use ffmpeg-full, elsewhere a BtbN GPL build
no usable Vulkan device for libplacebo Vulkan driver missing or not found — see the platform sections above
the libplacebo probe timed out Vulkan device creation hangs, usually a broken driver — update it or remove the software renderer