> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-osd

> Short-lived overlays for volume, brightness, and lock-key state.

`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):

```bash theme={null}
otter-osd
```

Send commands from scripts, the status bar, or compositor keybindings:

```bash theme={null}
otter-osd volume-up 5
otter-osd volume-down 10
otter-osd volume-mute-toggle
otter-osd brightness-up 5
otter-osd brightness-down 5
otter-osd caps-lock
otter-osd num-lock
otter-osd scroll-lock
```

The optional step value (default `5`) applies to volume and brightness commands.

[otter-timer](/apps/otter-timer) and [otter-rec](/apps/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, renders overlays on demand. Surfaces are created lazily and destroyed after timeout so idle RAM stays near zero.
* **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`

```conf theme={null}
timeout = 1500
position = bottom_center
width = 340
height = 60
margin_bottom = 60
icon_size = 28
border_width = 2
bar_height = 14
font_size = 15
animation_duration = 150
```

Color fields inherit from [theme.conf](/configuration/themes) when omitted. Position and size changes need new surfaces. Save the config and the daemon recreates the overlay on reload.