77c5250b08
wallaura works on any Linux distro with KDE Plasma, not just Manjaro, and supports any wallpaper image file — not only KDE packaged wallpapers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
158 lines
5.2 KiB
Markdown
158 lines
5.2 KiB
Markdown
# wallaura
|
||
|
||
Automatically syncs your Lenovo Legion / LOQ keyboard LED zone colors with your KDE Plasma desktop wallpaper.
|
||
|
||
When the wallpaper changes — whether you change it manually or a slideshow rotates — wallaura analyzes the image, extracts a dominant color from each of its four horizontal sections, and applies those colors to the keyboard's four LED zones in real time.
|
||
|
||
Works on **any Linux distribution running KDE Plasma** (Arch, Ubuntu, Fedora, openSUSE, …). Supports **any wallpaper image** — custom photos, downloaded images, or KDE's packaged wallpapers — as long as KDE Plasma knows about it.
|
||
|
||
---
|
||
|
||
## How it works
|
||
|
||
1. **Detects wallpaper changes** by listening to the `org.kde.PlasmaShell.wallpaperChanged` D-Bus signal emitted by KDE Plasma. This covers both manual changes and automatic slideshow rotations.
|
||
2. **Resolves the image file** via the PlasmaShell D-Bus API. Both plain image files (custom wallpapers set to a direct path) and KDE wallpaper packages (directories containing `contents/images/`) are supported. For packages, the highest-resolution image is picked automatically.
|
||
3. **Splits the image** into four equal vertical strips corresponding to the keyboard's four LED zones (left → right).
|
||
4. **Extracts a dominant color** from each strip using median-cut quantization (via Pillow), selecting the color that covers the most pixels rather than a blended average.
|
||
5. **Scales the colors** by the configured brightness factor (default 67%) and sends them to the keyboard via `legionaura static <c1> <c2> <c3> <c4> --brightness 2`.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- **KDE Plasma** desktop (Wayland or X11) — any Linux distro
|
||
- **[LegionAura](https://github.com/nivedck/LegionAura)** — the `legionaura` CLI must be installed and working
|
||
- **Python 3.10+**
|
||
- Python packages: `dbus-python`, `PyGObject`, `Pillow`
|
||
|
||
On Arch-based systems:
|
||
|
||
```bash
|
||
sudo pacman -S python-dbus python-gobject python-pillow
|
||
```
|
||
|
||
On Debian/Ubuntu:
|
||
|
||
```bash
|
||
sudo apt install python3-dbus python3-gi python3-pil
|
||
```
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### 1. Clone the repository
|
||
|
||
```bash
|
||
git clone https://github.com/pongsn/wallaura.git ~/wallaura
|
||
cd ~/wallaura
|
||
```
|
||
|
||
### 2. Make the script executable
|
||
|
||
```bash
|
||
chmod +x wallaura.py
|
||
```
|
||
|
||
### 3. Add to PATH
|
||
|
||
```bash
|
||
ln -sf ~/wallaura/wallaura.py ~/.local/bin/wallaura
|
||
```
|
||
|
||
Verify it is found:
|
||
|
||
```bash
|
||
wallaura --get-brightness
|
||
```
|
||
|
||
### 4. Install the systemd user service
|
||
|
||
```bash
|
||
cp wallaura.service ~/.config/systemd/user/
|
||
systemctl --user daemon-reload
|
||
systemctl --user enable --now wallaura.service
|
||
```
|
||
|
||
The service starts automatically on graphical login.
|
||
|
||
---
|
||
|
||
## Usage
|
||
|
||
### Daemon
|
||
|
||
The daemon is managed via systemctl:
|
||
|
||
```bash
|
||
systemctl --user start wallaura # start now
|
||
systemctl --user stop wallaura # stop now
|
||
systemctl --user restart wallaura # restart (pick up code changes)
|
||
systemctl --user status wallaura # show running status
|
||
journalctl --user -u wallaura -f # live log output
|
||
```
|
||
|
||
To enable or disable automatic startup on login:
|
||
|
||
```bash
|
||
systemctl --user enable wallaura # start automatically on login
|
||
systemctl --user disable wallaura # stop starting automatically on login
|
||
```
|
||
|
||
Enabling and disabling does not start or stop the currently running service — combine with `start`/`stop` if needed:
|
||
|
||
```bash
|
||
systemctl --user disable --now wallaura # disable and stop immediately
|
||
systemctl --user enable --now wallaura # enable and start immediately
|
||
```
|
||
|
||
### Brightness
|
||
|
||
wallaura applies software brightness scaling to the extracted colors, giving smooth control across the full 0–100% range.
|
||
|
||
The default brightness is **67%** (approximately two-thirds of maximum).
|
||
|
||
```bash
|
||
wallaura --set-brightness 80% # set to 80%
|
||
wallaura --set-brightness 0.5 # set to 50% (decimal form)
|
||
wallaura --set-brightness 50 # set to 50% (plain integer)
|
||
wallaura --get-brightness # print current brightness
|
||
```
|
||
|
||
The brightness setting is saved to `~/.config/wallaura/config.json`. The running daemon detects the change within five seconds and re-applies the current wallpaper colors at the new brightness — no restart needed.
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
Settings are stored in `~/.config/wallaura/config.json`:
|
||
|
||
```json
|
||
{
|
||
"brightness": 0.6667
|
||
}
|
||
```
|
||
|
||
This file can be edited by hand. The daemon polls it every five seconds and reloads it automatically when it changes.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
**`legionaura` command not found**
|
||
Install LegionAura and ensure the `legionaura` binary is in your PATH. See [LegionAura's README](https://github.com/nivedck/LegionAura) for installation instructions.
|
||
|
||
**Colors are not applied / keyboard does not respond**
|
||
Run `legionaura static ff0000 ff0000 ff0000 ff0000` manually. If that fails, the issue is with LegionAura or USB permissions, not wallaura.
|
||
|
||
**Slideshow changes are not detected**
|
||
Ensure slideshow is configured through KDE's desktop settings (right-click desktop → Configure Desktop). wallaura relies on the `wallpaperChanged` D-Bus signal from PlasmaShell, which is only emitted when Plasma manages the slideshow.
|
||
|
||
**Service fails to start**
|
||
Check the logs with `journalctl --user -u wallaura -f`. The most common cause is a missing Python package; install the dependencies listed in the Requirements section.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT
|