Desktop Integration

Desktop Integration

简体中文 · Home

Hyprland controls

Voice Input does not grab keys. Hyprland runs small client commands that connect to the daemon control socket.

The installed snippet is:

source = ~/.local/share/voice-input/omarchy-hyprland-snippet.conf

Its main binding is toggle mode:

bindd = SUPER CTRL, X, Voice input, exec, voice-input record toggle

Toggle is the robust choice when release events are unreliable. Each toggle client includes a request timestamp; the daemon ignores one that spent more than 750 ms queued behind finalization.

For push-to-talk, pair press and release:

bind = SUPER CTRL, X, exec, voice-input record start
bindr = SUPER CTRL, X, exec, voice-input record stop

The release must reach Hyprland. If a multi-modifier release is unreliable, return to toggle. hotkey.mode does not install a binding by itself; it affects generated output from:

voice-input setup hyprland

Cancel without output:

voice-input record cancel

Quickshell HUD

The primary HUD is a separate service:

systemctl --user status voice-input-hud.service
systemctl --user restart voice-input-hud.service

The unit runs:

/usr/bin/qs --no-duplicate --path ~/.local/share/voice-input/quickshell

It sets XDG_RUNTIME_DIR=%t, creates one PanelWindow variant per screen, displays only on the focused Hyprland monitor, uses the overlay layer, requests no keyboard focus, ignores exclusive-zone layout, and subtracts its complete input mask so it is click-through.

HUD data paths

$XDG_RUNTIME_DIR/voice-input/state.json
$XDG_RUNTIME_DIR/voice-input/waveform.sock

StateStore.qml polls the atomic JSON state every 50 ms. A Quickshell local socket receives newline-delimited waveform frames independently and reconnects after 400 ms when disconnected. Long transcript display is clipped to roughly five lines and shifted upward so the newest text remains visible.

The daemon service sets VOICE_INPUT_EXTERNAL_HUD=1, preventing the daemon from spawning the legacy Python HUD. Consequently:

• restarting the daemon does not restart Quickshell;
• a HUD crash does not stop ASR/output;
• [hud].enabled = false does not disable the separately enabled HUD service—disable/stop voice-input-hud.service for that;
• [hud].margin_bottom and [hud].height currently configure the Python fallback, while the Quickshell implementation directly uses 72 and 56 respectively.

Theme

Quickshell watches:

~/.config/omarchy/current/theme/colors.toml

It maps accent, foreground, color3, color5, and color1 to phase colors and retains built-in colors if the file cannot be read or parsed. This theme file is optional.

HUD placement

The current position and offsets live in config and runtime state:

voice-input hud position bottom-left
voice-input hud move right
voice-input hud move up 12
voice-input hud center
voice-input hud reset

• move uses [hud].nudge_step unless an amount is given.
• Positive X moves right; positive Y raises the HUD.
• center selects bottom-center and clears X only.
• reset selects bottom-center and clears both offsets.

Suggested optional bindings:

bind = SUPER CTRL ALT, left,  exec, voice-input hud move left
bind = SUPER CTRL ALT, right, exec, voice-input hud move right
bind = SUPER CTRL ALT, up,    exec, voice-input hud move up
bind = SUPER CTRL ALT, down,  exec, voice-input hud move down
bind = SUPER CTRL ALT, c,     exec, voice-input hud center

Waybar

The supplied JSONC fragment defines custom/voice-input:

voice-input setup waybar

Its command is:

voice-input status --follow --format json --extended

status --follow checks state every 250 ms and prints only when the payload changes. The snippet maps phase classes to icons, opens Settings on right click, and opens the model setup wizard on left click.

Merge the object into your Waybar configuration and add custom/voice-input to the desired module list. The setup command prints a fragment; it does not edit an existing Waybar file or restart Waybar.

Wayland and XWayland output targeting

At recording start, the CLI asks Hyprland whether the active window is XWayland and passes a hint to the daemon. At output time the daemon queries again. If either the captured hint or current target says XWayland, it takes the XWayland route.

Target	Direct type	Clipboard	Paste
Wayland	wtype	wl-copy	wl-copy + wtype chord
XWayland	wtype if explicitly allowed	xclip	xclip + xdotool

The default prefer_paste_for_xwayland = true avoids direct typing in XWayland. Text over 120 characters also switches from type to paste on Wayland. Paste backs up and restores the target clipboard; clipboard mode copies only.

Hyprland discovery first tries the command socket and falls back to hyprctl. It can import HYPRLAND_INSTANCE_SIGNATURE, WAYLAND_DISPLAY, DISPLAY, and XDG_RUNTIME_DIR from the systemd user-manager environment. If a service cannot see the session, update that environment from your graphical-session startup and restart the service rather than hard-coding another user's runtime path.

Legacy Python HUD

When VOICE_INPUT_EXTERNAL_HUD is absent/false and [hud].enabled = true, the daemon may launch assets/hud.py on non-idle state. It needs Python GTK4, Gtk4LayerShell, and optionally the layer-shell preload library. This fallback reads the same state and waveform paths. The standard installed service intentionally disables it in favor of Quickshell.

See also: Troubleshooting · Configuration