From af82b10d3c6ed7455f2cfdfe66876c534f8e2c00 Mon Sep 17 00:00:00 2001 From: Daniele Fucini Date: Tue, 13 Oct 2026 21:22:54 +0200 Subject: [PATCH] Add README --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f44269 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# xautolock-inhibit + +Makes screen locking with `xautolock` respect the "don't lock the screen" requests that apps send, on X11 sessions without a desktop environment (for example a plain window manager like xmonad). + +Browsers, Steam, gamemode and other apps ask the desktop not to lock or blank the screen while a video or game is running, through the D-Bus service `org.freedesktop.ScreenSaver`. Without a desktop environment nothing provides that service, so the requests are dropped and the screen locks in the middle of a video. xautolock-inhibit provides it: + +- While at least one request is active, it runs `xautolock -disable` and pauses X screen blanking and DPMS. +- When the last request is released, it waits a few seconds, then runs `xautolock -enable` and resumes blanking. + +xautolock stays your locker; xautolock-inhibit only switches it off and on. + +## How it works + +- Owns `org.freedesktop.ScreenSaver` on the session bus at both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` (apps differ on the path), and implements `Inhibit` and `UnInhibit`. +- Tracks requests per D-Bus client. If a client disconnects without releasing them (for example a browser crash), its requests are released. +- Runs `xautolock` only when the number of active requests goes from 0 to 1 or back to 0. Re-enabling waits a few seconds (`--release-delay`), because browsers send short bursts of requests when a video starts. +- Pauses X blanking with `XScreenSaverSuspend`, the same mechanism mpv uses, instead of changing `xset` settings. The X server ends the pause by itself if the daemon exits or crashes. +- Requests whose reason is on an ignore list (default: `Playing audio`) are accepted and logged, but don't block locking. Firefox-based browsers send one for audio playback, which would otherwise keep the screen unlocked while music plays with nobody at the computer. +- On exit (including SIGTERM), it re-enables xautolock. The systemd unit also runs `xautolock -enable` when it stops, as a fallback. +- If another program (a desktop environment) already owns `org.freedesktop.ScreenSaver`, it exits with status 2 instead of taking over. + +## Requirements + +- `xautolock`, already running in the session +- `python`, `python-gobject` +- `libx11`, `libxss` + +## Installation + +Build and install the package with the included PKGBUILD: + +``` +makepkg -si +``` + +Then start it from your window manager's startup, after `xautolock`. For xmonad: + +```haskell +spawnOnce "xautolock -time 10 -locker slock -detectsleep" +spawnOnce "systemctl --user start xautolock-inhibit" +``` + +The unit has no `[Install]` section on purpose. Enabling it at login would also start it in a desktop environment, or before X is up; starting it from the window manager limits it to that session. The user service manager needs `DISPLAY` (and `XAUTHORITY`) in its environment, which `/etc/X11/xinit/xinitrc.d/50-systemd-user.sh` sets up for `startx` sessions. + +## Usage + +``` +xautolock-inhibit [-i REASON] [--count-all] [-d SECONDS] +``` + +- `-i`, `--ignore-reason REASON`: request reason that doesn't block locking. Can be repeated; replaces the default (`Playing audio`). +- `--count-all`: every request blocks locking; no reasons are ignored. +- `-d`, `--release-delay SECONDS`: wait this long after the last release before re-enabling xautolock (default 5). + +To change the options used by the service: + +``` +systemctl --user edit xautolock-inhibit.service +``` + +```ini +[Service] +ExecStart= +ExecStart=/usr/bin/xautolock-inhibit --count-all +``` + +Every request, release and xautolock call is logged to the journal: + +``` +journalctl --user -u xautolock-inhibit +``` + +## App notes + +- **Sandboxed apps** may be blocked from reaching the service. For a firejail profile that filters D-Bus (`dbus-user filter`, as the Firefox-based profiles do), allow it in the app's `.local` file, e.g. `zen-browser.local`: + + ``` + dbus-user.talk org.freedesktop.ScreenSaver + ``` + +- **Games**: Steam's overlay and gamemode (`inhibit_screensaver=1`) send requests on their own. +- **scrcpy** only sends a request when started with `--disable-screensaver`. +- **mpv** talks to the X server directly and doesn't need this daemon. + +## Limitations + +- Restarting the daemon loses the requests it holds; apps don't send them again. Avoid restarting it while a video or game is running. +- `SimulateUserActivity` is accepted and logged, but does nothing. +- `GetActive` always returns `false`. + +## License + +GPL-3.0-or-later. See [LICENSE](LICENSE).