Installation

voxctrl is a Tauri desktop app that runs on Linux (Wayland + X11) and Windows 10/11. The recommended install on Linux is the AppImage — a single portable binary with all runtime dependencies bundled.

System Requirements

Linux

For Pocket-TTS voice cloning, you'll also need a free HuggingFace account with the kyutai/pocket-tts model license accepted, and an access token — see Voice output.

Windows

Windows 10 (1903+) or Windows 11. WebView2 runtime is pre-installed on Windows 11; on Windows 10 it downloads automatically on first run.

GPU Acceleration

Option A: AppImage (recommended, Linux)

Download the latest AppImage from GitHub Releases.

Quick run

chmod +x VoxCtrl.AppImage
./VoxCtrl-x86_64.AppImage

System install (desktop entry, udev rules, input group)

VoxCtrl supports two ways to set up system integration:

• CLI mode: run the AppImage with the --install flag in a terminal — it prompts for your password via sudo:

  ./VoxCtrl-x86_64.AppImage --install

• GUI mode: launch the AppImage normally. If hardware permissions are missing, a diagnostics window appears automatically with a Setup System Integration button that prompts for your password via pkexec.

The installer:

• Copies the app icon to ~/.local/share/icons/hicolor/128x128/apps/voxctrl.png
• Registers a .desktop launcher in ~/.local/share/applications/voxctrl.desktop
• Creates udev rules at /etc/udev/rules.d/99-voxctrl.rules for /dev/input access (required for global hotkeys)
• Adds the current user to the input group

Option B: Windows

Download the Windows installer from GitHub Releases and run it. WebView2 is pre-installed on Windows 11; on Windows 10 (1903+) it auto-downloads on first run.

Global hotkeys on Windows use Win32 hooks — no special permissions required.

Option C: Build from source

Prerequisites: Rust (stable), Node.js 20+, npm.

git clone https://github.com/jrufer/voxctrl.git
cd voxctrl
npm install
npm run tauri build

The build output is a release binary + AppImage (Linux) or .exe/.msi (Windows).

For development with hot-reload: npm run tauri dev

First Run

On first launch, voxctrl creates ~/.config/voxctrl/ with default config files and opens the Settings window.

1. Download a model — Settings → Engine → choose a size → click Download. Recommendation: small (~466 MB) for good speed/accuracy; large-v3 (default, ~3 GB) for maximum accuracy. large-v3-turbo (~1.6 GB) trades a little accuracy for roughly double the speed.
2. Check your hotkey — a default binding (Super + Space, hold gesture → inject to focused window) is created automatically. Verify in Settings → Hotkeys.
3. Test dictation — open any text editor, click into the text area, hold Super + Space, speak, release.

Optional Setup

TTS (Piper / Pocket-TTS voices)

Go to Settings → TTS, enable TTS, select a voice, click Download. Piper voices are stored at ~/.local/share/voxctrl/piper-voices/. Pocket-TTS is a pure-Rust voice-cloning engine — its model weights are downloaded once to the HuggingFace cache (~/.cache/huggingface/hub/) and require a HuggingFace account with the kyutai/pocket-tts license accepted plus an access token, set via Settings → TTS → Pocket-TTS or the HF_TOKEN environment variable. Espeak-ng is always available as a lightweight fallback.

MCP Server (Claude Desktop / Cursor)

Enable in Settings → Engine → MCP Server. Then add to ~/.config/claude/claude_desktop_config.json:

{"mcpServers":{"voxctrl":{"command":"socat","args":["STDIO","UNIX-CONNECT:/tmp/voxctrl-mcp.sock"]}}}

LLM post-processing (OpenAI-compatible API)

Point voxctrl at any OpenAI-compatible API server for grammar/style rewriting. For a fully local setup with Ollama: install Ollama, pull a model (ollama pull llama3.2), then enable in Settings → OpenAI API — the default URL (http://localhost:11434) already points at a local Ollama instance. To use a remote provider instead, set the API URL to its base URL and provide an API key.

Permissions setup (Linux)

Global hotkeys

voxctrl uses evdev to listen for global keyboard events. Your user must be in the input group:

sudo usermod -aG input $USER
# Log out and back in

# Verify:
groups $USER | grep input

Wayland text injection

For Wayland sessions, install wtype:

# Ubuntu/Debian
sudo apt install wtype

# Arch
sudo pacman -S wtype

# Fedora
sudo dnf install wtype

X11 text injection

For X11 sessions, install xdotool:

# Ubuntu/Debian
sudo apt install xdotool

# Arch
sudo pacman -S xdotool

Troubleshooting

Hotkeys not working

• Check you are in the input group: groups | grep input
• Log out and back in after being added to the group
• On some distros, the udev rule path differs — the built-in installer handles this automatically

No audio devices found

• Run arecord -l to verify your mic is recognized by ALSA
• Check if PulseAudio/PipeWire is running: pactl info
• Try setting audio.input_device_index manually to a specific device index in config.json

Text not injecting on Wayland

• Verify wtype is installed: which wtype
• Some applications block synthetic input — clipboard fallback always works: use delivery = "clipboard"

Whisper outputs wrong language

• Set engine.language to your BCP-47 language code (e.g. "de", "fr", "es") in config.json
• Use a larger model for better non-English accuracy

AppImage won't launch

• Install FUSE: sudo apt install fuse libfuse2
• Or extract and run directly: ./VoxCtrl.AppImage --appimage-extract && squashfs-root/AppRun

Crash logs

If the application crashes or fails to start, check ~/.local/share/voxctrl/startup_errors.log. This file logs system configuration details and errors only — it never records transcribed speech or LLM prompts. Attach it when opening GitHub issues.