Skip to main content
otter-osd shows brief overlays for volume, brightness, and lock keys. Run it as a daemon. Scripts, the bar, and compositor keybindings send commands over a UNIX socket.

​
Usage

Start the daemon (autostart at login):
Send commands from scripts, the status bar, or compositor keybindings:
The optional step value (default 5) applies to volume and brightness commands. Text messages are centered and wrap to fit the OSD. Bind your microphone-mute key to otter-osd microphone-mute-toggle to toggle the default PipeWire microphone and display its mute state. When Do Not Disturb is on, popup surfaces stay hidden. Hardware commands still change volume and brightness. Run otter-notifications dnd-off to show future OSD updates again. otter-timer and otter-rec also use otter-osd for completion notifications.

​
Architecture

One binary, two roles:
  • Daemon (no args): Connects to Wayland, opens a UNIX datagram socket, and renders overlays. Surface buffers are allocated when needed and released after timeout. The daemon and its PipeWire connection remain running.
  • Client (with args): Sends a command to the daemon and exits.
Socket path: $XDG_RUNTIME_DIR/otter-shell/osd-{WAYLAND_DISPLAY}.sock

​
Configuration

Config file: ~/.config/otter-shell/otter-osd.conf
Color fields inherit from theme.conf when omitted. Position and size changes need new surfaces. Save the config and the daemon recreates the overlay on reload.

​
Lua surface

If osd.lua is available on the UI script search path, it describes the overlay while native code handles hardware state and rendering. User overrides live under $XDG_DATA_HOME/otter-shell/ui/ (normally ~/.local/share/otter-shell/ui/). Script edits hot-reload; a failed frame falls back to native drawing. Use otter-settings UI Scripts to create or reset an override, choose Native UI, inspect reported errors, or request Reload now. From a terminal, otter-osd ui-reload requests a script reload. See Settings.