oled-blackout

A pure-black fullscreen overlay for OLED displays, used as a "screen off" that never actually drops the video signal — so waking up is instant, with no GPU re-handshake or blank flash.

On OLED, black pixels emit no light, so this gets you the same panel-off effect as DPMS, without DPMS. It also sidesteps the desktop's own idle-lock, so it stays purely cosmetic — no password prompt on wake.

What's here

• bin/blackout-overlay.py — a GTK window, fullscreened on every monitor, painted flat black, cursor hidden. Exits on any keypress, click, or deliberate mouse movement (small jitters are ignored).
• bin/blackout — wrapper script: blackout [on|off|toggle].
• systemd/blackout-idle.service — user service that runs swayidle to trigger the overlay after 2 minutes of inactivity, and dismiss it on resume.

Install

./install.sh

This copies the scripts to ~/.local/bin, installs and enables the systemd user service, and starts it immediately.

Manual toggle

Bind ~/.local/bin/blackout toggle to a key in your desktop environment's shortcut settings. On COSMIC this is Settings → Keyboard → Custom Shortcuts. This repo's own setup uses Super+Shift+B.

Requirements

• Python 3 with PyGObject (python3-gi) and GTK 3
• swayidle
• A systemd user session (or adapt blackout-idle.service to your init)

Uninstall

systemctl --user disable --now blackout-idle.service
rm ~/.config/systemd/user/blackout-idle.service
rm ~/.local/bin/blackout ~/.local/bin/blackout-overlay.py
systemctl --user daemon-reload