installation

Installation & Setup

System Requirements

Linux

• OS: Any modern Linux distro (Ubuntu 20.04+, Fedora 36+, Arch, etc.)
• Display: X11 or Wayland
• Audio: PulseAudio or PipeWire (ALSA fallback supported)
• Required packages: libwebkit2gtk-4.1, libayatana-appindicator3 or libappindicator3
• Optional: wtype (Wayland injection), xdotool (X11 injection)
• For Pocket-TTS: a HuggingFace account with the kyutai/pocket-tts license accepted and an access token (see Pocket-TTS below)

Windows

• OS: Windows 10 (1903+) or Windows 11
• Runtime: WebView2 (pre-installed on Win11; auto-downloadable on Win10)

---

Installing the AppImage (Linux)

The recommended distribution format is an AppImage — a single portable executable with all dependencies bundled.

# Download the latest AppImage
curl -LO https://github.com/jrufer/voxctrl/releases/latest/download/VoxCtrl.AppImage

# Make executable
chmod +x VoxCtrl.AppImage

# Run normally
./VoxCtrl-x86_64.AppImage

# Or run the built-in installer for desktop integration and hardware permissions:
./VoxCtrl-x86_64.AppImage --install

Setup Methods

VoxCtrl supports two ways to perform system configuration (udev rules, input group, desktop shortcut, and high-res icon):

1. CLI Mode: Run ./VoxCtrl-x86_64.AppImage --install in a terminal. It will prompt for your administrator password via sudo and configure everything.
2. GUI Mode: Launch the AppImage normally. If hardware permissions are missing, a diagnostics window will automatically appear. Click the 🔧 Setup System Integration button; it will securely prompt for your password via pkexec and configure everything in the background.

The built-in installer:

1. Copies the application icon to ~/.local/share/icons/hicolor/128x128/apps/voxctrl.png
2. Registers a .desktop launcher file in ~/.local/share/applications/voxctrl.desktop linking to the active AppImage path
3. Establishes hardware udev rules (/etc/udev/rules.d/99-voxctrl.rules) to grant hotkey device permissions
4. Adds your active user account to the system input group

Note: After running the installer, you must log out and log back in (or reboot) for the new input group permissions to take effect. Until then, global hotkeys will not work.

Robust Container / Sandbox Support: VoxCtrl employs intelligent diagnostic checks that support legacy rule files (99-voxctrl.rules, 99-voxctl.rules, or 99-voxctr.rules) and dynamically fallback to checking the system's NSS group database (/etc/group) if the current container process session fails to refresh its active group token, ensuring that the warning screen does not show up repeatedly on every launch.

---

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

---

First Run

On first launch, VoxCtrl will:

1. Create ~/.config/voxctrl/ with default config.json, targets.toml, and bindings.toml
2. Create ~/.local/share/voxctrl/ for model and voice storage
3. Open the Settings window

Download a Whisper Model

Before you can dictate, you need a speech recognition model:

1. Go to Settings → Engine
2. Choose a model size (recommendation: small for a good speed/accuracy balance; the default is large-v3 for maximum accuracy)
3. Click "Download" and wait for completion (~142 MB for base, ~466 MB for small, ~3 GB for large-v3)

Configure a Hotkey

A default binding (Super + Space, hold gesture → inject to focused window) is created automatically. Verify it in Settings → Hotkeys, or change the key combo if it conflicts with your desktop environment.

Test Dictation

1. Open any text editor
2. Click into the text area
3. Hold Super + Space and speak
4. Release to transcribe

---

Optional Setup

GPU Acceleration

Vulkan (AMD / Intel / NVIDIA): Set engine.whisper_cpp.device = "vulkan" in config, or choose "Vulkan" in Settings → Engine. Install driver support if needed:

# Ubuntu
sudo apt install vulkan-tools libvulkan1

# Arch
sudo pacman -S vulkan-icd-loader

NVIDIA CUDA: CUDA acceleration requires a CUDA-enabled build of VoxCtrl — it is not available in the standard pre-built AppImage. You must compile from source with:

npm run tauri build -- --features cuda

Once running a CUDA build, set engine.whisper_cpp.device = "auto" (or "cuda") and VoxCtrl will use the GPU automatically. The "CUDA (NVIDIA)" option in Settings → Engine is only shown when the binary was compiled with CUDA support.

LLM Post-Processing (OpenAI-compatible API)

If you want LLM grammar correction, point VoxCtrl at any OpenAI-compatible API server. For a fully local setup using Ollama:

1. Install Ollama
2. Pull a model: ollama pull llama3.2
3. 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.

Pocket-TTS

Pocket-TTS is a pure-Rust voice-cloning TTS engine (no system packages required) but its model weights live in a gated HuggingFace repository:

1. Create a free HuggingFace account if you don't have one.
2. Visit kyutai/pocket-tts and accept the model license.
3. Create an access token at huggingface.co/settings/tokens (read access is sufficient).
4. Paste the token into Settings → TTS → Pocket-TTS → HuggingFace Token, or set it via the HF_TOKEN environment variable before launching VoxCtrl.
5. Pick a voice and click Download in Settings → TTS. The model weights, tokenizer, and the selected voice's reference clip are downloaded once and cached locally under ~/.cache/huggingface/hub/.

MCP Server (Claude Desktop / Cursor)

1. Enable in Settings → Engine → MCP Server
2. Configure your MCP client to connect to /tmp/voxctrl-mcp.sock

---

Uninstalling

scripts/uninstall.sh reverts everything VoxCtrl's setup and runtime create — the udev rule, your input group membership, the menu launcher and icon, ~/.config/voxctrl/, ~/.local/share/voxctrl/ (Whisper models, Piper engine and voices), the WebKit profile dirs, and the Pocket-TTS entries in the HuggingFace cache — returning the system to its pre-VoxCtrl state:

# From a clone of this repository:
./scripts/uninstall.sh              # interactive
./scripts/uninstall.sh --yes        # no prompts (keeps the .AppImage file)

# Or without cloning:
curl -fsSL https://raw.githubusercontent.com/JRufer/VoxCtrl/master/scripts/uninstall.sh | bash -s -- --yes

Optional flags: --remove-appimage also deletes the .AppImage file itself; --remove-packages also removes the host packages the installer added (wtype, xdotool, wl-clipboard, xclip, portaudio, espeak-ng) — opt-in because other software may use them. Log out and back in afterwards for the input group removal to take effect.

---

Building from Source

See Development Guide.

---

Troubleshooting

Hotkeys not working

• Check you are in the input group: groups | grep input
• Log out and back in after adding to group
• On some distros, the udev rule path differs — check the built-in installer logic for details

Permissions screen keeps reappearing (fresh Arch / CachyOS installs)

The startup permissions screen reappears on every launch until global hotkeys actually work in your session:

1. Click Setup System Integration and enter your password. This writes the udev rule and adds you to the input group first; the optional host package installation runs afterwards and is allowed to fail (stale pacman mirrors on a freshly installed system are common — run sudo pacman -Syu later to fix them).
2. Log out and log back in (or reboot). Group membership only applies to new login sessions; until then the screen shows a "Relogin Required" notice.

Hotkey records but no text is typed (and no overlay)

• Download a Whisper model first: Settings → Engine → Download. On a fresh install no model is present; VoxCtrl now shows a notification when you press a dictation hotkey without one.
• The default "Dictate (Hold)" gesture requires the combo to be held ~200ms before recording starts — a very quick tap is ignored by design.
• If a "no microphone audio is arriving" notification appears, pick a working input device in Settings → Audio.

TTS engines refuse to play

• Piper: download a voice in Settings → TTS first — this also installs the standalone Piper engine into ~/.local/share/voxctrl/piper/.
• eSpeak-NG: requires the system package (sudo pacman -S espeak-ng / sudo apt install espeak-ng).
• Pocket-TTS: requires a one-time model download (and a HuggingFace token — see above).
• Failures now surface directly in Settings → TTS next to the Test button.

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 (integer, not null)

Text not injecting on Wayland

• Verify wtype is installed: which wtype
• Some applications block synthetic input (e.g. terminals with certain settings)
• Clipboard fallback always works — use delivery = "clipboard" as a workaround

Whisper outputs wrong language

• Set engine.language to your language code (e.g. "de", "fr", "es")
• 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

Debugging & Crash Logs

If the application crashes, fails to launch, or encounters hardware/model errors, you can check the local startup and error log file:

• Location: ~/.local/share/voxctrl/startup_errors.log
• Privacy: To protect your privacy, this file never records or contains any transcribed speech text or LLM prompts. It only logs system configurations (models loaded, input devices, sample rates) and application/compiler errors.
• Submitting Reports: Please attach this log file when opening issues or submitting crash reports on GitHub to help us diagnose the problem.