Custom FFmpeg¶
Screenshots from HDR content need ffmpeg filters that not every build ships:
- HDR10 / HDR10+ / Dolby Vision Profile 7 and 8 need
zscaleandtonemapfor HDR-to-SDR conversion. Both are required:tonemapexpects linear light andzscaleis what linearizes the PQ input, sotonemapon 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
libplacebofilter 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:
or if upPollo warns during a Profile 5 upload:
Setup¶
1. Download a full-featured build¶
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¶
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¶
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¶
- ffmpeg built with
--enable-libplacebo, and - 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:
ffmpeg-full is keg-only, so it does not replace an existing ffmpeg. Its directory
is what goes into custom_ffmpeg_path:
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 |