Overlays

voxctrl displays a transparent always-on-top HUD while recording, while TTS is speaking, or while the MCP server is actively recording. Eight built-in styles are rendered by a dedicated native helper process. Switch between them in Settings → Visual tab.

Built-in styles

The default is Ocean Wave. All styles share three state palettes: Recording (the style's signature color), Initializing (amber), and Processing (sky blue).

To disable the overlay entirely, set ui.overlay_style = "none" in ~/.config/voxctrl/config.json or toggle it off in Settings → Visual.

Selecting a style

Open Settings → Visual tab → Overlay Style dropdown. Changes take effect immediately and are hot-switched without restarting the overlay helper. The setting is written to config.json as ui.overlay_style.

// config.json excerpt
{
  "ui": {
    "show_overlay": true,
    "overlay_style": "blue_wave",
    "overlay_position": "center",
    "overlay_monitor": "primary"
  }
}

Valid overlay_style values: "blue_wave", "voice_card", "waveform", "pulse", "mono_bars", "spectrum", "terminal", "vinyl", "none".

Positioning

The overlay window can be positioned dynamically on the active monitor via Settings → Visual & Feedback → Overlay position, or via ui.overlay_position in config.json:

• "center" (default) — exact horizontal and vertical center of the active monitor
• "top" — horizontal center, 60 logical pixels from the top
• "bottom" — horizontal center, 60 logical pixels from the bottom

Positions are calculated in physical pixels relative to the display's current scale factor, so placement is resolution-independent on 1080p, 1440p, and 4K monitors. Changes apply instantly if the overlay is currently visible.

Multi-monitor targeting

In multi-monitor setups, you can pin the overlay to a specific display via Settings → Visual & Feedback → Overlay display, or ui.overlay_monitor:

• "primary" (default) — constrains the overlay to the OS-defined primary display
• Specific monitor name (e.g. "HDMI-1", "DP-2") — connected displays are queried once at startup; selecting one binds the overlay to that panel

If the configured target monitor is unplugged or disconnected at runtime, VoxCtrl automatically fails over to the primary monitor and shows a golden warning badge in the settings UI to flag that fallback mode is active.

Routing indicator badge

Every overlay shows a small label with the active target's human-readable name (e.g. "Focused Window", "Hermes Agent", "Voice Journal"). When you use multiple hotkeys to route to different destinations, the badge changes with each activation. The label comes from the label field on the active target definition in targets.toml.

Speaking pill

While TTS is responding, a green "SYSTEM RESPONDING" pill slides up from the bottom of the overlay with a live mini-equalizer and the active target label, and slides back down when speech ends.

How it works

The built-in overlay styles are rendered by a dedicated native helper process (voxctrl-overlay, built with Slint) in a borderless, transparent, always-on-top, click-through window (560×190 logical px) drawn over whatever application is in focus. The main VoxCtrl process spawns this helper at startup and streams newline-delimited JSON messages (status, position, shutdown) to its stdin — recording/processing/ speaking state, smoothed microphone level, the active routing target label, the configured style, and screen coordinates.

The window is fully transparent except for drawn pixels, stays always-on-top (re-asserted on every re-appearance), and is click-through (cursor hit-testing disabled at the windowing-system level), so mouse events pass cleanly through to the window beneath it.

Every built-in style plays a dedicated spring-driven load animation when it appears and an unload animation when it disappears — the helper window stays alive until the unload animation finishes, rather than vanishing the instant recording stops.

The overlay is shown automatically when recording starts and hidden when transcription completes, provided ui.show_overlay = true.

Configuration reference