hdr-helper 💻

Linux script to control and automatically toggle HDR on KDE Plasma.

I've personally tested this on Fedora 41 Plasma Edition on an RX 6800XT using the standard RADV drivers which are built into the Linux Kernel. I only have one display, I've not accounted for multi-display scenarios so please take this into consideration :)

Supported Features 📋

• Automatically & manually toggling HDR on and off.
• Notifying you whether HDR has been successfully activated.
• Setting a target SDR brightness level whilst in HDR mode.
• Setting a target SDR to HDR coversion brightness level in nits.
  • Your original non-HDR brightness level will be preserved when switching back.

The Problem

At this moment in time, pretty much all games require HDR to be manually enabled for it to properly function. Normally this isn't a problem when using Gamescope as your native compositor. Most people however run a fully fledged desktop environment on their PCs unless they're using SteamOS or Bazzite.

This can be annoying because running Gamescope from within KDE Plasma with the HDR flag enabled still won't magically make HDR work, unless it's also enabled from your compositor's side too; in this case, KWin. Although KWin has a way to enable HDR from the command line, the implementation is flawed as most monitors will only properly display HDR after also changing video modes. In other words, the HDR signal must be present BEFORE HDR-compatible monitors will recognise what to do; this happens usually once the monitor is forced to change resolution or refresh rate.

The Solution

I've created a script which will toggle HDR from KDE Plasma's in-built kscreen-doctor helper and also force change video modes. This means that whenever you launch a HDR-compatible game, you won't ever need to manually enable HDR again since this script can be used as a launch parameter for Steam and third party apps. Of course you may also call this script manually and force HDR to be on or off if you so desire.

Some configuration is required!

---

Setup

To start with, clone this repository and create a symbolic link to the file:

git clone https://github.com/dunestorm333/hdr-helper.git
cd hdr-helper
# Not all distros will create the below path, create it assuming that it doesn't
# exist on your system
mkdir ~/.local/bin/
ln -s hdr-helper ~/.local/bin/
chmod +x ~/.local/bin/hdr-helper

# You will also need to copy monitor.conf into ~/.config/hdr-helper
mkdir ~/.config/hdr-helper
cp monitor.conf ~/.config/hdr-helper

Ensure to modify monitor.conf with your desired settings.

xrandr will give you the following output; in the below example DP-3 is the value we need to use to target the active monitor.

Screen 0: minimum 16 x 16, current 3440 x 1440, maximum 32767 x 32767
DP-3 connected primary 3440x1440+0+0 (normal left inverted right x axis y axis) 800mm x 337mm
...

Below is an example of the help output of the script:

--- Usage ---
hdr-helper    | The default behaviour will automatically enable or disable HDR
hdr-helper -e | Force enables HDR
hdr-helper -d | Force disables HDR
hdr-helper -s | Shows detected HDR status as a system notification
hdr-helper -v | Displays version information
hdr-helper -h | Displays this help screen

--- Info ---
Currently only KDE Plasma is supported running Wayland. Ensure that kscreen-doctor
is present on your system for HDR Helper to function.

--- Config ---
Please modify the MONITOR, NATIVE_RES and TEMP_RES values in monitor.conf.

Usage

Using with Steam & Gamescope

Firstly, ensure that Gamescope is installed and working. From Steam, right click on the game you'd like to automatically enable HDR for and click on Properties...

Now enter the below command into the launch options:

Effectively what we're doing here is affixing and suffixing the standard Gamescope launch commands with hdr-helper.

hdr-helper ; gamescope -W 3440 -H 1440 -r 165 -f --hdr-enabled -- %command% ; hdr-helper

Using with standalone Apps & Gamescope

The commands you need to get this working with pretty much any app or game is very similar to the Steam method. Note that in both cases, Gamescope is required as HDR requires a valid HDR layer and compositor to properly function in addition to working drivers.

hdr-helper; gamescope -W 3440 -H 1440 -r 165 -f --hdr-enabled ~/my-app-or-game; hdr-helper

Manual Approach

If you'd like to manually bind HDR Helper to a shortcut key for example, this can easily by configured in most desktop environments.

Using KDE Plasma, you may do this from the System Shortcuts page. Click Add New > Command or Script...

Now specify the hdr-helper command in the command field and give the shortcut a name.

You may now assign a key-combination to toggle the shortcut. Remember to click Apply when done!