nfrastack/dms-backlightIdleActions

About

Backlight Idle Actions is a DankMaterialShell (DMS) daemon plugin that adds a pre-blank dim stage to DMS's existing AC/battery idle pipeline. When the user is idle for the configured timeout, the plugin silently lowers the display backlight and keyboard backlight (with an optional fade) and restores them on resume, meant as a replacement for swayidle or hypridle.

Features

• Native Quickshell.Wayland.IdleMonitor (ext-idle-notify-v1); no external idle daemon required
• Independent AC profile and battery profile - each with its own enable toggle, idle timeout, display dim percent, and keyboard dim percent
• Smooth configurable fade between current and dim brightness
• Silent dim/restore - no OSD popups
• Ability to override idle inhibitors

Maintainer

• Nfrastack

Table of Contents

• About
• Features
• Maintainer
• Requirements
• Screenshots
• Installation
• Configuration
• Usage
• Permissions
• Troubleshooting
• Support & Maintenance
• License

Requirements

• DankMaterialShell 1.5-beta or later (provides Quickshell.Wayland.IdleMonitor and DisplayService.setBrightness(_, _, suppressOsd))
• A Wayland compositor that implements ext-idle-notify-v1 (Hyprland, niri, Sway)
• Optional: brightnessctl (fallback restore path)

Screenshots

• Settings

Installation

mkdir -p ~/.config/DankMaterialShell/plugins/
git clone https://github.com/daveconroy/dms-backlightIdleActions ~/.config/DankMaterialShell/plugins/backlightIdleActions

Reload DMS, then enable Idle Actions in Settings -> Plugins.

Configuration

Top-level:

Key	Type	Description	Default
displayDevice	string	Brightness device id for the display, e.g. backlight:amdgpu_bl1. Leave unset to skip display dimming.	""
kbdDevice	string	Brightness device id for the keyboard backlight, e.g. leds:tpacpi::kbd_backlight. Leave unset to skip kbd dimming.	""
respectInhibitors	bool	When on, dim is suppressed while any Wayland idle inhibitor is held. Off means dim always fires.	false
fadeDurationMs	int 0-3000	Fade animation duration in ms. 0 disables the fade and snaps.	500
debugLog	bool	Print verbose state transitions and heartbeats to journalctl --user -t dms.	false

Per profile (acEnabled, acTimeout, acDimDisplayPercent, acDimKbdPercent, plus battEnabled, battTimeout, battDimDisplayPercent, battDimKbdPercent):

Key	Type	Description	AC default	Battery default
*Enabled	bool	Enable the dim stage for this power state.	false	false
*Timeout	int 5-1800 (s)	Idle timeout before dim fires. Capped to DMS's *MonitorTimeout - 1.	600	30
*DimDisplayPercent	int 0-100	Target display brightness percent during dim.	20	10
*DimKbdPercent	int 0-100	Target keyboard backlight percent during dim.	0	0

Usage

The plugin runs as a daemon. Once enabled and configured:

• After your configured idle timeout, the plugin reads the current display + kbd brightness, then fades them to the dim targets silently.
• On any user input (mouse/keyboard), it fades brightness back to the snapshotted pre-dim values.
• DMS's own acMonitorTimeout / acLockTimeout / acSuspendTimeout (and battery equivalents) continue to handle the rest of the idle pipeline - this plugin only adds the dim stage.

When you swap AC <> battery, the IdleMonitor is rearmed with the new profile's timeout and dim levels reactively.

Permissions

The plugin requests these permissions:

• settings_read - read AC/battery profiles and device assignments
• settings_write - save toggle and slider changes
• process - fallback brightnessctl invocations

Troubleshooting

• Dim never fires: enable verbose log, watch journalctl --user -t dms | grep backlightIdleActions. Heartbeats every 5 s show isIdle and inhibitor state. If isIdle stays false despite no input, an inhibitor is held - turn Respect idle inhibitors off.
• OSD pops up during dim - your DMS build doesn't honour suppressOsd on DisplayService.setBrightness. Update DMS or file an issue.

Support & Maintenance

• For community help, tips, and community discussions, visit the Discussions board.
• For personalized support or a support agreement, see Nfrastack Support.
• To report bugs, submit a Bug Report. Usage questions may be closed as not-a-bug.
• Feature requests are welcome, but not guaranteed. For prioritized development, consider a support agreement.
• Updates are best-effort, with priority given to active production use and support agreements.

License

MIT. See the LICENSE file.