search

maximbaz / wluma

Automatic brightness adjustment based on screen contents and ALS
ISC License
658 stars 28 forks source link
adaptive adaptive-brightness adaptive-learning ambient-light ambient-light-sensor backlight backlight-dimming brightness brightness-adjustment brightness-control brightness-level dark-mode dark-theme dimmer night-mode screen sway swaywm vulkan wlroots

readme

wluma

A tool for Wayland compositors to automatically adjust screen brightness based on the screen contents and amount of ambient light around you.

Supported screen capture protocols

With default config, wluma will automatically detect which protocols are supported, and pick the most appropriate one. See "Configuration" section below for more information and how to force a specific protocol.

The list of supported protocols:

Idea

The app will automatically brighten the screen when you are looking at a dark window (such as a fullscreen terminal) and darken the screen when you are looking at a bright window (such as web browser). The algorithm takes into consideration the amount of ambient light around you, so the same window can be brighter during the day than during the night.

With permission of Lumen's author (the project that inspired me to create this app), I'm reusing a demo GIF:

demo

Usage

Simply launch wluma and continue adjusting your screen brightness as you usually do - the app will learn your preferences.

wluma will not do anything on the first launch! You have to adjust the brightness by hand a few times, in different environment and/or with different screen contents, that way wluma will learn your preferences and only then it will begin to automatically change your screen brightness for you.

Performance

The app has minimal impact on system resources and battery life even though it is able to monitor screen contents several times a second. This is achieved by using Wayland protocols to get access to the screen contents and doing computations entirely on GPU using Vulkan API.

Installation

Packaging status

Use one of the available packages and methods below:

Build

CI

If you want to build the app yourself, make sure you use latest stable Rust, otherwise you might get compilation errors! Using rustup is perhaps the easiest. Ubuntu needs the following dependencies: sudo apt-get -y install v4l-utils libv4l-dev libudev-dev libvulkan-dev libdbus-1-dev.

Then simply run make build.

Permissions

In order to access backlight devices, wluma must either:

Configuration

The config.toml in repository represents default config values. To change them, copy the file into $XDG_CONFIG_HOME/wluma/config.toml and adjust as desired.

ALS

Choose whether to use a real IIO-based ambient light sensor ([als.iio]), a webcam-based simulation ([als.webcam]), a time-based simulation ([als.time]) or disable it altogether ([als.none]).

Each of them contains a thresholds field, which comes with good default values. It is there to convert generally exponential lux values into a linear scale to improve the prediction algorithm in wluma. Keys are the raw values from ambient light sensor (maximal value depends on the implementation), values are arbitrary "profiles". wluma will predict the best screen brightness according to the data learned within the same ALS profile.

Displays

Multiple outputs are supported, using backlight (common for internal laptop screens) and ddcutil (for external screens).

Each output is identified by compositor using model, manufacturer and serial number (e.g.eDP-1 'Sharp Corporation 0x14A8 0x00000000' (eDP-1).

The name field in the output config will be matched as a substring, so you are free to put simply eDP-1, or a serial number (if you have two identical external screens). It is your responsibility to make sure that the values you use match uniquely to one output only.

Tip: run wluma with RUST_LOG=debug to see how your outputs are being identified, so that you can choose an appropriate name configuration value.

The capturer field will determine how screen contents will be captured. Currently supported values are wayland (works only on Wayland compositors that support protocols listed in the top) and none (ignores screen contents and predicts brightness only based on ALS). The value wayland will automatically choose the most appropriate protocol, but if you want to force a specific one, you can also use ext-image-capture-source-v1, wlr-screencopy-unstable-v1 or wlr-export-dmabuf-unstable-v1 as the value.

Tip: run wluma with RUST_LOG=debug and capturer="wayland" to see which protocols are supported by your Wayland compositor, and which one wluma chooses to use.

Run

To run the app, simply launch wluma or use the provided systemd user service.

Debugging

To enable logging, set environment variable RUST_LOG to one of these values: error, warn, info, debug, trace.

For more complex selectors, see env_logger's documentation.

Known issues (help wanted!)

Help is wanted and much appreciated! If you want to implement some of these, feel free to open an issue and I'll provide more details and try to help you along the way.

Relevant projects