ICC Brightness

Control display brightness by applying ICC color profiles.

This is a maintained fork of the icc-brightness project by Udi Fuchs.

Introduction

This tool is a work-around for displays whose brightness control is not supported by the Linux kernel (e.g. OLED displays before version 5.12). It performs well on OLED displays, since these have very dark black point and their power consumption is relative to the brightness of the viewed content. It can also be used on an LCD display, but in that case you really want to control the brightness directly using the display backlight.

Embedded laptop displays are the default target, however, you can use the --target option described below to target external displays instead.

This tool was developed by @udifuchs for the Lenovo ThinkPad X1 Yoga OLED display. Later development by @tartansandal was performed on a Dell XPS 15 7590 with an OLED display. Support for Razer Blade/Stealth and other non-Intel systems was suggested by @midnex.

Build

The tool consists of an Python script, icc-brightness, which is a wrapper around a compiled executable, icc-brightness-gen. To build icc-brightness-gen you will need to install the lcms2 development package.

For Ubuntu run

sudo apt install liblcms2-dev

For Fedora run

sudo dnf install lcms2-devel

To build the executable simply run

make

If all has gone well, then you should be able to run

$ ./icc-brightness-gen
./icc-brightness-gen filename brightness max-brightness
brightness and max-brightness must be integers.

Given appropriate parameters, this command generates a new ICC color profile that has its gamma value set relative to the ration between 'brightness' and 'max-brightness'.

Running

The icc-brightness script is a convenience wrapper that manages the color profiles created by the icc-brightness-gen command. It has a number of modes and options:

$ ./icc-brightness
usage: icc-brightness [-h] [--target TARGET] [--loglevel LOGLEVEL]
                      [--logfile LOGFILE]
                      {apply,watch,clean,list,set} ...

Control OLED display brightness by applying ICC color profiles

positional arguments:
  {apply,watch,clean,list,set}
    apply               apply brightness from system setting
    watch               continuously update to system setting
    clean               remove all profiles generated by us
    list                list visible device models
    set                 set brightness manually

optional arguments:
  -h, --help            show this help message and exit
  --target TARGET       prefix of device models to target
  --loglevel LOGLEVEL   set the logging level
  --logfile LOGFILE     log to the specified file

The apply mode looks at the current system brightness settings and attempts to apply a color profile that matches the intended brightness, creating a new profile if necessary.

The watch mode operates as a daemon, continuously watching for changes to the system brightness settings and updating the current color profile as appropriate. The installation instructions below use a auto-start file to launch this daemon when logging in under Gnome.

The set mode applies a profile corresponding to the given brightness and max-brightness values, creating a new profile if necessary. For example, the following set the brightness level to approximately 67% of the maximum.

./icc-brightness set 67 100

The clean mode removes all the profiles generated by this tool. By default, up to 20 profiles are generated to cover potential brightness values. If this tool is not working as expected, say after an upgrade, you can use this command to force the profiles to be regenerated with each new setting.

$ ./icc-brightness clean
2021-08-17 11:34:56,362 - INFO: Removing: ~/.local/share/icc/brightness_102_512.icc
2021-08-17 11:34:56,376 - INFO: Removing: ~/.local/share/icc/brightness_128_512.icc
...
2021-08-17 11:34:56,700 - INFO: Removing: ~/.local/share/icc/brightness_486_512.icc
2021-08-17 11:34:56,730 - INFO: Removing: ~/.local/share/icc/brightness_435_512.icc

The list mode lists the device models that the script can currently 'see' and create profiles for. This is provided as a helper for setting the --target option.

$ ./icc-brightness list
XPS 15 7590
LG Ultra HD

The --target option allows you to target a specific display rather than the default embedded one. This may be useful if the embedded display is not being reliably detected. It may also be useful if you want to target an external display. Note that we select the first display whose model name (as shown by list) starts with the value of this option, so this may not be useful if you have more than one external display with the same model name. (This is a fringe feature, so if you want it improved, please submit an issue).

./icc-brightness --target XPS apply

The --loglevel ands --logfile options may be useful for tracking down bugs and submitting bug reports.

Installation

You can install this tool globally with:

$ sudo make install
cp icc-brightness-gen /usr/local/bin/
cp icc-brightness /usr/local/bin/
cp icc-brightness.desktop /usr/share/gnome/autostart/

This install includes an auto-start file to start a watch daemon when logging-in to a Gnome session. The daemon will start on your next login. You can change brightness using the brightness key or any other method that controls the display "backlight".

To remove this global installation:

$ sudo make uninstall
rm -f /usr/local/bin/icc-brightness-gen
rm -f /usr/local/bin/icc-brightness
rm -f /usr/share/gnome/autostart/icc-brightness.desktop

If you prefer to install this daemon as a local user:

$ make local-install
mkdir -p ~/.local/bin/
install -m 755 icc-brightness-gen ~/.local/bin/
install -m 755 icc-brightness ~/.local/bin/
mkdir -p ~/.config/autostart/
install -m 644 icc-brightness.desktop ~/.config/autostart/

And you can remove this local installation with:

$ make local-uninstall
rm -f ~/.local/bin/icc-brightness-gen
rm -f ~/.local/bin/icc-brightness
rm -f ~/.config/autostart/icc-brightness.desktop

Troubleshooting

If things are not working as you expect, you might want to check the system logs. On systems that use systemd journal you can do this with the following command:

journalctl --user --identifier icc-brightness.desktop --boot

Note that log lines containing

WARNING: No matching device found yet

immediately after logging in are to be expected. They are due to the icc-brightness autostart application being started before the colord service is ready. If these messages persist, you may have and issue with the colord service.

Thanks

Huge thanks to Udi Fuchs (@udifuchs) for creating the initial project and making my shiny new laptop usable.

Thanks to Llane Rost (@midnex) for code clean up and non-Intel support suggestions 😄

tartansandal / icc-brightness