Running in background, provides fast voice-to-text typing in any Linux app.
Using LOCAL (offline) voice processing, with optional LOCAL (offline) AI text post-processing.
Runs fine even on older CPUs. No GPU required.

Hit your hotkey shortcut -> speak -> hotkey again -> watch your words appear wherever the cursor currently is, even AI-rewritten as a poem or a C++ code.

Tested & Works on:

• Arch / Hyprland
• Omarchy 3.0
• Ubuntu 24.04 / GNOME
• Ubuntu 25.04 / Sway
• Fedora 42 / KDE
• Pop!_OS 22 / COSMIC
• Mint 22 / Cinnamon
• openSUSE / Leap 15.6

Complete the 2 steps:

1. Install VOXD
2. setup a hotkey.

Download the package for your distro and architecture from the latest release, then install with your package manager.

Latest builds: GitHub Releases (Latest)

# Update package lists and install the downloaded .deb package:
sudo apt update
sudo apt install -y ./voxd_*_amd64.deb    # or ./voxd_*_arm64.deb on ARM systems

# Update repositories and install the downloaded .rpm package:
sudo dnf update -y
sudo dnf install -y ./voxd-*-x86_64.rpm  # or the arm64 counterpart if on an ARM device

# Synchronize package databases and install the downloaded .pkg.tar.zst package:
sudo pacman -Sy
sudo pacman -U ./voxd-*-x86_64.pkg.tar.zst    # or the arm64 counterpart if on an ARM device

# Refresh repositories and install the downloaded .rpm package with dependency resolution:
sudo zypper refresh
sudo zypper install --force-resolution ./voxd-*-x86_64.rpm   # or the arm64 counterpart if on an ARM device

git clone https://github.com/jakovius/voxd.git

cd voxd && ./setup.sh

# requires sudo for packages & REBOOT (ydotool setup on Wayland systems). Launchers (GUI, Tray, Flux) are installed automatically.

Setup is non-interactive with minimal console output; a detailed setup log is saved in the repo directory (e.g. 2025-09-18-setup-log.txt).

Reboot the system!
(unless on an X11 system; on most modern systems there is Wayland, so ydotool is required for typing and needs rebooting for user setup).

a. Open your system keyboard-shortcuts panel:

• GNOME: Settings → Keyboard → "Custom Shortcuts"
• KDE / XFCE / Cinnamon: similar path.
• Hyprland / Sway: just add a keybinding in the respective config file.

b. The command to assign to the shortcut hotkey (EXACTLY as given):

bash -c 'voxd --trigger-record'

c. Click Add / Save.

First, run the app in terminal via just
voxd or voxd --setup command.
The first run will do some initial setup (voice model, LLM model for AIPP, ydotool user setup).

voxd        # CLI (interactive); 'h' shows commands inside CLI. FIRST RUN: a necessary initial setup.
voxd --rh   # directly starts hotkey-controlled continuous recording in Terminal
voxd -h     # show top-level help and quick-actions
voxd --gui  # friendly GUI window--just leave it in the background to voice-type via your hotkey
voxd --tray # sits in the tray; perfect for unobstructed dictation (hotkey-driven also)
voxd --flux # VAD (Voice Activity Detection), voice-triggered continuous dictation (in beta)

Leave VOXD running in the background -> go to any app where you want to voice-type and:

Otherwise, if in --flux (beta), just speak.

For practical reasons (always ready to type & low system footprint), it is advised to enable voxd user daemon:

• Enable: voxd --autostart true
• Disable: voxd --autostart false

This launches voxd --tray automatically after user login using systemd user services when available; otherwise it falls back to an XDG Autostart entry (~/.config/autostart/voxd-tray.desktop).

• Supported codes: ISO 639-1 (e.g., en, es, de, sv) and auto (auto-detect, not advised).
• Default: en. You can override per run or persist it.
• Change via CLI (session-only), examples:

voxd --gui  --lang auto
voxd --tray --lang es
voxd --flux --lang de
voxd --rh   --lang sv

• Persist via CLI: voxd --cfg opens the config file for editing. Set:

# ~/.config/voxd/config.yaml
language: sv  # or 'auto', 'es', etc.

• Change via GUI/Tray (persisted): Menu → Language. Saved to ~/.config/voxd/config.yaml as language.
• Model note: For non‑English languages, use a multilingual Whisper model (not *.en.bin). Install/switch via GUI “Whisper Models” or voxd-model (e.g., ggml-base.bin, small, medium, large-v3).
• Tip: auto works well, but setting the exact language can improve accuracy. If you pick a non‑English language while using an English‑only model, VOXD will warn and transcription quality may drop.

VOXD needs a Whisper GGML model file. There is one default model readily setup in the app (base.en).
Use the built-in model-manager in GUI mode or via CLI mode in Terminal to fetch any other model.
The voice models are downloaded into ~/.local/share/voxd/models/ and VOXD app will automatically have them visible.

CLI model management examples:

voxd-model list	# show models already on disk
voxd-model install tiny.en  #	download another model
voxd-model --no-check install base.en # download a model and skip SHA-1 verification
voxd-model remove tiny.en	# delete a model
voxd-model use tiny.en	# make that model the default (edits config.yaml)

Models for download (size MB):

Available in GUI and TRAY modes ("Settings"), but directly here: ~/.config/voxd/config.yaml

Your spoken words can be magically cleaned and rendered into e.g. neatly formated email, a poem, or straight away into a programing code!

VOXD can optionally post-process your transcripts using LOCAL (on-machine, llama.cpp, Ollama) or cloud LLMs (like OpenAI, Anthropic, or xAI).
For the local AIPP, llama.cpp is available out-of-the-box, with a default model.
You can also install Ollama and download a model that can be run on your machine, e.g. ollama pull gemma3:latest.
You can enable, configure, and manage prompts directly from the GUI.

In CLI mode, use --aipp argument.
In GUI or TRAY mode, all relevant settings are in: "AI Post-Processing".
Seleting provider & model - models are tied to their respective providers!
Editing Prompts - Select "Manage prompts" or "Prompts" to edit up to 4 of them.

• llama.cpp (local)
• Ollama (local)
• OpenAI
• Anthropic
• xAI

~/.local/share/voxd/llamacpp_models/

• GGUF format only (.gguf extension)
• Quantized models recommended (Q4_0, Q4_1, Q5_0, etc.)
• ❌ Not supported: PyTorch (.pth), Safetensors (.safetensors), ONNX

Step 1: Download a .gguf model from Hugging Face

# Example: Download to model directory
cd ~/.local/share/voxd/llamacpp_models/
wget https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF/resolve/main/qwen2.5-3b-instruct-q4_k_m.gguf?download=true

Step 2: Restart VOXD
VOXD automatically discovers all .gguf files in the models directory on startup and makes them available for selection.

Step 3: Select in VOXD GUI
AI Post-Processing → Provider: llamacpp_server → Model: qwen2.5-3b-instruct

Edit ~/.config/voxd/config.yaml:

# llama.cpp settings
llamacpp_server_path: "llama.cpp/build/bin/llama-server"
llamacpp_server_url: "http://localhost:8080"
llamacpp_server_timeout: 30

# Selected models per provider (automatically updated by VOXD)
aipp_selected_models:
  llamacpp_server: "qwen2.5-3b-instruct-q4_k_m"

For security reasons, be mindful where you store your API keys.
To use cloud AI providers, set the required API key(s) in your shell environment before running VOXD.
For example, add these lines to your .bashrc, .zshrc, or equivalent shell profile for convenience (change to your exact key accordingly):

# For OpenAI
export OPENAI_API_KEY="sk-..."

# For Anthropic
export ANTHROPIC_API_KEY="..."

# For xAI
export XAI_API_KEY="..."

Note:
If an API key is missing, the respective cloud-based AIPP provider will (surprise, surprise) not work.

Note: As one may expect, the app is not completely immune to very noisy environments :) especially if you are not the best speaker out there.

• List devices: python -m sounddevice (check that a device named "pulse" exists on modern systems).
• Prefer PulseAudio/PipeWire: set in ~/.config/voxd/config.yaml:

audio_prefer_pulse: true
audio_input_device: "pulse"   # or a specific device name or index

• If no pulse device:

  • Debian/Ubuntu: sudo apt install alsa-plugins pavucontrol (ensure pulseaudio or pipewire-pulse is active)
  • Fedora/openSUSE: sudo dnf install alsa-plugins-pulseaudio pavucontrol (ensure pipewire-pulseaudio is active)
  • Arch: sudo pacman -S alsa-plugins pipewire-pulse pavucontrol

• If 16 kHz fails on ALSA: VOXD will retry with the device default rate and with pulse when available.

• VOXD – © 2025 Jakov Ivkovic – MIT license (see LICENSE). Logo and brand assets: see ASSETS_LICENSE. Trademarks: see TRADEMARKS.md.
• Speech engine powered by ggml-org/whisper.cpp (MIT) and OpenAI Whisper models (MIT).
• Auto-typing/pasting powered by ReimuNotMoe/ydotool (AGPLv3).
• Transcript post-processing powered by ggml-org/llama.cpp (MIT)

If VOXD was installed via a native package:

• Ubuntu/Debian

sudo apt remove voxd

• Fedora

sudo dnf remove -y voxd

• openSUSE

sudo zypper --non-interactive remove voxd

• Arch

sudo pacman -R voxd

Note: This removes system files (e.g., under /opt/voxd and /usr/bin/voxd). User-level data (models, config, logs) remain. See "Optional runtime clean-up" below to remove those.

If you cloned this repository and ran ./setup.sh inside it, just run the uninstall.sh script in the repo folder:

# From inside the repo folder
./uninstall.sh

If voxd was installed through pipx (either directly or via the prompt at the end of setup.sh):

pipx uninstall voxd

Enjoy seamless voice-typing on Linux - and if you build something cool on top, open a PR or say hi!