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
wtype	Wayland direct typing and paste-key simulation
wl-copy, wl-paste	Wayland paste, backup, and clipboard restoration
systemd user session	Supplied daemon/HUD services; encrypted credential loading
Quickshell 0.3 or newer, available as /usr/bin/qs	Resident HUD and on-demand Settings

Verify the command-line programs rather than assuming a package name across distributions:

command -v cargo make pw-record hyprctl wtype wl-copy wl-paste systemctl qs

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/
~/.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 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 provider interactively:

voice-input setup model

Or open the on-demand Quickshell Settings window:

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 record toggle

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 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

Reload Pi after an update so it loads the replaced session-registry extension. The installer also deletes obsolete installed hud.py and settings.py files from older releases; HUD and Settings now require Quickshell.

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