Installation

Installation

简体中文 · Home

Platform assumptions

The current implementation targets a Linux graphical user session with Hyprland and Wayland. The supplied service files are systemd user units. Other compositors and init systems are not covered by the included integration.

Dependencies

Required for a standard full installation

Dependency	Used for
Stable Rust toolchain with Rust 2024 support, Cargo	Building the binary
GNU Make, install, sed, grep	Running the supplied Makefile
PipeWire pw-record	Mono PCM microphone capture
Hyprland tools (hyprctl)	Active-window/monitor discovery and target classification
wl-clipboard 2.3 or newer (wl-copy, wl-paste)	Wayland paste, backup, restoration, and sensitive clipboard hints
systemd user session	Supplied daemon/HUD services; encrypted credential loading
Quickshell 0.3 or newer, installed as /usr/bin/qs	Resident HUD and on-demand Settings; Voice Input uses this exact path
Qt Shader Tools / qsb 6.7 or newer	Compiling the HUD shader with the Qt 6 target set during installation

Verify the command-line programs rather than assuming a package name across distributions. Confirm the exact Quickshell path separately:

command -v cargo make pw-record hyprctl wl-copy wl-paste systemctl
test -x /usr/bin/qs
qsb_path=$(command -v qsb || command -v qsb6 || printf '%s' /usr/lib/qt6/bin/qsb)
test -x "$qsb_path"
"$qsb_path" --help | grep -F -- --qt6

The Makefile discovers qsb, qsb6, or /usr/lib/qt6/bin/qsb. For another Qt installation, pass QSB=/path/to/qsb to make; the selected tool must support --qt6.

Required only for selected configurations

Dependency	When required
/usr/bin/voxtype	Default local-cli provider, or fallback_to_local = true after a Qwen failure
OpenCC executable opencc	simplified-chinese or traditional-chinese, because final text is converted with t2s/s2t
Alibaba API credential and network access	Qwen realtime and Qwen final-pass ASR
OpenAI-compatible API credential and network access	LLM refinement
xclip and xdotool	Reliable XWayland clipboard output/paste

The backend path is deliberately /usr/bin/voxtype; do not replace it with the voice-input executable.

Optional feature dependencies

• Fcitx5 and fcitx5-remote: temporary ASCII-mode management during output. Missing fcitx5-remote is tolerated.
• Kitty with remote control, the kitty CLI, and GNU timeout: focused Pi/Codex discovery. See Agent Context.
• Pi: only for Pi session context. The Makefile installs the extension automatically.
• systemd-creds: writing or inspecting encrypted credentials. Local-only use can run without configured credentials.

Fresh install

The Makefile builds with Cargo's lockfile enforced. On a fresh machine, the first build downloads the locked Rust dependency set as needed:

git clone https://github.com/Saco93/voice-input.git
cd voice-input
make enable-service

make enable-service performs a release build, installs files under the current user's home, renders both service units, reloads the systemd user manager, enables the units, and restarts them. It does not require a system-wide install.

Default installed paths are:

~/.local/bin/voice-input
~/.local/share/voice-input/quickshell/
~/.local/share/voice-input/quickshell-settings/
~/.local/share/voice-input/quickshell/shaders/wavy-halo.frag.qsb
~/.local/share/voice-input/fonts/NotoSansSC-Variable.ttf
~/.local/share/voice-input/fonts/OFL-NotoSansSC.txt
~/.local/share/voice-input/config.toml
~/.local/share/voice-input/voice-input.service
~/.local/share/voice-input/voice-input-hud.service
~/.local/share/voice-input/omarchy-hyprland-snippet.conf
~/.local/share/voice-input/omarchy-waybar-snippet.jsonc
~/.config/voice-input/config.toml
~/.config/systemd/user/voice-input.service
~/.config/systemd/user/voice-input-hud.service
~/.pi/agent/extensions/voice-input-session-registry.ts

The HUD and Settings load the bundled Noto Sans SC variable font and retain Qt's system-font fallback if it cannot be loaded. The font is distributed under the included SIL Open Font License.

The installer preserves an existing Voice Input config. It can import a compatible older Voxtype config and encrypted credential blobs when the expected files exist; review imported settings before relying on them.

Ensure ~/.local/bin is in the graphical session's PATH, because the installed Hyprland and Waybar snippets invoke voice-input by name:

export PATH="$HOME/.local/bin:$PATH"

Persist that setting through your shell/session environment rather than relying on a one-terminal export.

Install without enabling services

make install
systemctl --user daemon-reload

Use this when you want to inspect or edit the generated units first. Start later with:

systemctl --user enable --now voice-input.service voice-input-hud.service

First configuration

The public sample starts with provider = "local-cli", /usr/bin/voxtype, LLM disabled, agent context disabled, final pass disabled, and pre-roll disabled.

Choose a stable provider interactively:

voice-input setup model

The model setup wizard intentionally does not offer the experimental Qwen-Audio-3 provider. To try Audio3, open Settings, select Qwen-Audio-3 (experimental), and separately acknowledge the experimental-provider warning before saving. It is neither enabled nor treated as a stable default automatically.

Open the on-demand Quickshell Settings window with:

voice-input settings

The command activates an existing instance through non-secret Quickshell IPC when possible; otherwise it starts /usr/bin/qs --daemonize --no-duplicate --path ~/.local/share/voice-input/quickshell-settings. Settings requires Quickshell 0.3 or newer and is not a systemd service.

Leaving a credential replacement field blank preserves the encrypted credential. Save sends any entered key only through inherited stdin to the Rust backend, which passes it through stdin to systemd-creds. Rust validates the complete configuration, writes the directory/file with 0700/0600 permissions using atomic replacement, and can restart voice-input.service. If restart fails after persistence succeeds, Settings reports that restart failure separately.

After manual config edits, restart the daemon:

systemctl --user restart voice-input.service

See Configuration for all fields and Security and Privacy for credential precedence.

Desktop integration

Source the installed Hyprland snippet from your Hyprland configuration:

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

The shipped snippet assigns F8 to cancel, F9 to toggle, and F10 to discard and restart. It leaves Omarchy's stock Super+Ctrl+X Voxtype shortcut unchanged and also includes optional HUD movement bindings. Restart/reload Hyprland after adding it. If you use hold mode, generate a binding that pairs record start with record stop:

voice-input setup hyprland

For Waybar, inspect the installed snippet:

voice-input setup waybar

See Desktop Integration before merging it into an existing JSONC file.

Verify

systemctl --user status voice-input.service voice-input-hud.service
voice-input status
voice-input diagnostics
voice-input record toggle

voice-input diagnostics [--format text|json] is the safe, bounded support report; unlike extended status output, it excludes normal transcript text and private endpoint/model values. Stop the test recording with the same toggle. Use voice-input record cancel if you do not want any recognized text emitted.

For Qwen realtime, confirm the Alibaba credential and then restart the daemon before testing. For the experimental Audio3 provider, a prerecorded 16 kHz mono PCM16 WAV can test either remote API without starting the daemon or delivering text to another application:

voice-input asr stream-test --file sample.wav  # WebSocket streaming
voice-input asr test --file sample.wav         # Native full-audio request

Both commands require Audio3 to be selected and explicitly acknowledged in the active configuration. They upload the WAV to the resolved Regional route or exact Custom endpoint and may incur Alibaba API charges.

For LLM refinement:

voice-input llm test

The command requires LLM refinement, a model, and a credential to be configured.

Update or remove

To update from source, fetch the new revision and reinstall. Cargo downloads any newly locked dependencies as needed:

git pull --ff-only
make enable-service

An update replaces the installed binary, HUD and Settings assets, bundled font, compiled .qsb, generated user units, Hyprland/Waybar snippets, shared sample files, and Pi session-registry extension. It preserves an existing user config.toml and encrypted credential store. The installer also deletes obsolete installed hud.py and settings.py files from older releases; HUD and Settings now require Quickshell.

After updating, close and reopen Settings, reload Pi so it loads the replaced extension, and reload Hyprland so it reads the replaced sourced snippet. voice-input setup waybar only prints the newly installed fragment: if you previously copied that fragment into a Waybar JSONC file, merge the new version again and restart Waybar.

Disable both units with:

make disable-service

That target stops/disables services but does not delete installed files, configuration, or credentials. Remove those manually only after deciding what to retain.

Next: Configuration · Desktop Integration · Troubleshooting