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, available as /usr/bin/qs	Primary HUD service

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

• Python 3, PyGObject, GTK4, and libadwaita: graphical voice-input settings.
• 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.
• GTK4 layer shell and Python GTK bindings: legacy assets/hud.py fallback when running the daemon without the external Quickshell HUD. This is not the standard two-service path.
• systemd-creds: writing or inspecting encrypted credentials. Local-only use can run without configured credentials.

Fresh install

The Makefile deliberately builds Cargo in offline mode. On a fresh machine, fetch the locked Rust dependency set once before invoking it:

git clone https://github.com/Saco93/voice-input.git
cd voice-input
cargo fetch --locked
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/
~/.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 optional GTK settings UI:

voice-input settings

Settings encrypts non-empty Alibaba and LLM keys with systemd-creds into the per-user encrypted credential store, writes the TOML as mode 0600, and restarts voice-input.service. Leaving a password field blank preserves an existing encrypted credential.

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 uses toggle mode with Super+Ctrl+X and 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, fetch its locked dependencies, and reinstall:

git pull --ff-only
cargo fetch --locked
make enable-service

Reload Pi after an update so it loads the replaced session-registry extension.

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