Home

Voice Input Wiki

简体中文

Voice Input is a resident, agent-aware dictation service for Omarchy, Hyprland, and Wayland. It combines Qwen realtime ASR, experimental Audio3 Streaming and Native recognition, optional full-audio recovery, conservative LLM cleanup, Pi/Codex terminology context, a click-through Quickshell HUD, and on-demand Quickshell Settings.

This page is an index. For the short project introduction, see the repository README.

Start here

Goal	Page
Install from a fresh clone	Installation
Understand every TOML option	Configuration
See the capture, ASR, refinement, and output pipeline	Architecture
Enable terminology from the Pi/Codex session focused when dictation starts	Agent Context
Add Hyprland, Quickshell, and Waybar integration	Desktop Integration
Review what leaves the machine	Security and Privacy
Diagnose a failure	Troubleshooting
Build, test, package, or contribute	Development

Supported operating model

Voice Input is currently designed around a Linux graphical user session with Hyprland and Wayland. The standard installation uses two systemd user services:

• voice-input.service runs the Rust daemon.
• voice-input-hud.service keeps the Quickshell HUD resident from assets/quickshell.

Settings is a separate, on-demand Quickshell configuration from assets/quickshell-settings; it is a regular floating window, not a third service.

The public configuration starts in local-ASR mode and points explicitly to /usr/bin/voxtype. Alibaba Qwen realtime ASR, Qwen full-audio final ASR, LLM refinement, agent context, and microphone pre-roll are opt-in.

Everyday commands

voice-input record toggle
voice-input record restart
voice-input record cancel
voice-input diagnostics
voice-input status
voice-input status --follow --format json --extended
voice-input settings
voice-input setup model
voice-input llm test

Use voice-input diagnostics [--format text|json] for support reports. Do not share voice-input status output, including --extended: status is intended for local UI integration and may contain the current or most recent transcript and tooltip.

Service checks:

systemctl --user status voice-input.service voice-input-hud.service
journalctl --user -u voice-input.service -u voice-input-hud.service -b

Important behavior at a glance

• Qwen realtime ASR supplies partial and final text; Server VAD also controls speech activity. Its worker can reconstruct the session at most once for a qualifying pre-finish transport or transcript stall, replaying retained audio before complete-audio recovery takes over.
• Experimental Audio3 Streaming supplies live text over WebSocket. One recoverable pre-finish disconnect creates a fresh task, discards the interrupted task's transcript, and replays the complete retained prefix at 4× realtime. A second disconnect, a disconnect after finish-task, or another degraded result uses the configured Audio3 Native or local complete-audio recovery path.
• For Qwen Realtime, the optional final pass uploads the complete temporary WAV to the configured Alibaba-compatible HTTP endpoint and replaces realtime text when successful.
• Recording stops and finalizes automatically at audio.max_duration_secs (five minutes by default), on both dedicated and shared pre-roll capture paths.
• Realtime audio delivery is bounded and nonblocking. If the remote stream falls behind, capture continues and the complete recording is recovered through the enabled final pass or local fallback instead of trusting incomplete remote text.
• LLM refinement fails open to ASR text. Its contextual attempt and any transcript-only retry share one budget: 15 seconds by default and never more than 30 seconds.
• Pi/Codex context is optional, terminology-only, redacted, validated, and capped. The terminology source is captured when dictation starts and frozen for both Audio3 Streaming and Refine; focus at stop selects only the refinement destination style. Pi/Codex destinations use faithful compact Markdown even when session context is disabled.
• Every transcript uses clipboard paste with restoration: wl-copy plus Hyprland sendshortcut on Wayland, or xclip plus xdotool on XWayland. On native Wayland, both the temporary transcript and the restored clipboard content are marked sensitive and must still be treated as sensitive data.
• The Quickshell HUD reads status and configured visibility/geometry from state.json, plus waveform frames from a separate Unix socket, so visual updates do not define ASR packet timing. Its integrated bottom row shows the active stage and effective recording time without counting arming or processing delays.
• voice-input settings activates an existing Settings window or starts one. QML exchanges versioned NDJSON with a Rust child backend; Rust alone validates and atomically writes configuration and credentials.

Project boundaries

Voice Input is an independent community project. It is not affiliated with or endorsed by Omarchy, Alibaba, OpenAI, OpenRouter, Pi, Codex, or Voxtype.

Next: Installation · Architecture · Troubleshooting