Technology

A few years ago, I built out a home theater system, after not having a TV for nearly a decade. Even after leaving my life of minimalism, I still just watched movies and shows on a regular desktop monitor or laptop. I was surprised at how difficult it was to get HDR support working on Linux, and how limited my options were. For years, I simply used Windows 10 and the VLC media player to play videos with HDR and high quality audio. Although true HDR is now possible on Linux, it’s still not entirely straightforward and took a little bit of work. This guide explains how to setup mpv media player with HDR on KDE Neon Linux, but should be adaptable to other Wayland based setups.

Background and Hardware Choices

I looked at a couple of different options for a Home Theater PC (HTPC). I purchased a Mac Mini M1. However, most of the video players for the Mac that can support HDR are commercial. At the time, mpv on the M1 didn’t support HDR. Also, macOS does not allow direct audio pass-through. That means no matter what, there’s no way to send AC3 (Dolby Digital), DTS-HD, TrueHD or any other surround sound audio formats from a Mac to an external receiver. I’m not sure if this has changed in the past few years or if this can be worked around with additional hardware, but it reminded me once again about how much I hate macOS in the way that it abstracts and sandboxes everything that’s useful to hobbyists and developers. I gave up on the Mac Mini as an HTPC. I intended to use it for other development, but so far it’s mostly collected dust.

For a while I used a Raspberry Pi and LibreELEC. LibreELEC is a bare minimum Linux distribution that runs the Kodi media player. The Raspberry Pi version of LibreELEC allows for HDR output and surround sound audio pass-through on certain supported Pi revisions. This setup was stable for a while, but I wasn’t a huge fan of the user interface. Kodi is designed to mimic popular streaming applications while working with your own media library. The Emby plugin can be used to synchronize your media and watch history across multiple devices. However, I preferred the simplicity of a regular file manager and using my lnSponge script for handling new media.

Eventually I purchased a Minisforum UM270 and simply ran Windows 10. I used VLC, a free and open source media player that supports audio pass-through and HDR. The Minisforum has a Ryzen 7 2700U processor and Radeon graphics. Unfortunately, 4K playback was noticeably jittery. I tried updating drivers and adjusting BIOS settings. It wasn’t terrible, but it was noticeable enough to take me out of what I was watching.

I moved the hard drive from the Minisforum to a Morefine M9 Mini PC. The Morefine uses a low powered Intel N100 with hardware video decoding. I ordered this in 2023 and VLC worked perfectly on it, playing 4k videos without skipping or dropping frames. The Morefine worked well for nearly two years before it started crashing randomly and refusing to power on. Sometimes these devices refuse to boot if the coin cell battery goes bad¹. I replaced the battery, but the device still shut itself off after a while. There may be thermal problems that could have been addressed by cleaning the device and applying fresh thermal paste. However, the device is difficult to take apart, and I was already getting constant notices to upgrade to Windows 11.

I had found a post of someone who had gotten HDR working with mpv on KDE Neon, but the details of exactly how were sparse². Realizing the support for Windows 10 would be ending soon, I decided to experiment with the old Minisforum PC to see if I could get HDR working with mpv on Linux. It was surprisingly easy to get working, and the previous problems with the AMD graphics and video stuttering went away completely when on Linux! This mini PC has been stable for several weeks and is an excellent Linux media player that can do absolutely everything I need it to do.

Guide for HDR with mpv on KDE Neon Linux

In March of 2025, mpv 0.40.0 was released, which includes HDR support via the dmabuf-wayland video output³. Mesa version 25.1 also includes support for an HDR Vulkan layer for users who want to continue to use the gpu-next technique described below⁴. As of writing, the version of KDE Neon I’m on doesn’t yet have mpv 0.40.0 or mesa 25.1. The technique outlined below uses some hacked together components. I may create another guide in the future, comparing these techniques to the newer, and officially supported methods, of getting HDR working with mpv.

To get mpv to properly send HDR metadata to a TV, I’m going to be using a Vulkan Wayland HDR WSI Layer. This is an experimental Vulkan layer, and the project emphasizes that it’s “Hacks. Don’t use for serious color work.” However, for watching videos, it’s quite fine. I installed KDE Neon on my Minisforum, and enabled HDR in KDE’s display settings. Then it was simply a matter of installing all the build dependencies for VK_hdr_layer, checking out the source code and building the project.

# Install mpv and build dependencies

sudo apt install mpv git pkg-config meson cmake libx11-dev libvulkan-dev libwayland-bin libwayland-dev

# Clone, build and install the VK_hdr_layer

git clone https://github.com/Zamundaaa/VK_hdr_layer
cd VK_hdr_layer
meson setup builddir
ninja -C builddir
sudo meson install -C builddir

I created a wrapper script to run mpv with all the necessary parameters. KDE Neon replaces pulseaudio with pipewire. Pulseaudio had a pasuspender command that would allow a process raw access to the ALSA device for audio pass-through, or a pass-through could be configured without suspending Pulseaudio using tools like pavucontrol (which would occasionally work). After trying to figure out how to do this with pipewire, I gave up and just had the wrapper script kill the daemon before running mpv.

#!/bin/sh
export ENABLE_HDR_WSI=1
killall -9 pipewire
mpv --ao=alsa --audio-spdif=ac3,eac3,dts-hd,truehd --vo=gpu-next --target-colorspace-hint --gpu-api=vulkan --gpu-context=waylandvk "$@"

I then configured Dolphin file manager to call my wrapper script, and also have it keep the terminal open so I could see the mpv log output messages.

Is it in HDR?

Previous versions of mpv would show HDR video as dull and washed out. The current version has built-in tone mapping that does an excellent job of mapping HDR color into an SDR color space. Unfortunately, that makes it difficult to tell if I’m really running in HDR. I attempted to look closely at some video clips, but eventually found the Mehanik HDR10 calibration and test patterns. The 04. spiral.mp4 listed under the 05. Chroma sharpness folder is one of the patterns that best illustrates the dramatic difference between SDR and HDR, but I found noticeable differences with many of the other patterns listed in the included guide.

Even when taking an SDR screenshot, the color differences are fairly pronounced in this particular demonstration. There are a variety of other tests in Mehanik guide that also show color and contrast differences between SDR and HDR playback, but they are a bit too subtle to really capture using screenshots or a good camera. I’m fairly confident mpv is sending HDR metadata (BT.2020 color space) correctly to my TV.

Final Thoughts

There are still some things that are not ideal with my setup that I’m sure others will improve upon. For one, I shouldn’t be killing pipewire, but finding a way to have pipewire send raw audio data to my receiver. There are some people who just let mpv split all the audio channels, and honestly the audio quality would probably be good enough to be indistinguishable from raw pass-through. Still, I prefer raw pass-through because my receiver already has decoders for surround sound formats, and I’ve calibrated it for my room.

The experimental Vulkan layer shouldn’t be necessary for much longer as well. As I’ve stated previously, version 0.40.0 of mpv was released in March³. The new dmabuf-wayland video output option should allow for direct HDR pass-through, although image quality might be an issue⁵. Mesa version 25.1 should also remove the need for using the experimental Vulkan layer that needed to be custom compiled in this tutorial⁴. KDE Neon 6.3 is still on an older version of mpv and mesa, so I can’t test out and compare the new mpv features. For now, I’ve had HDR playback working for a few months, and am glad I can finally retire one more Windows 10 device in my home.