GETTING STARTED / QUICKSTART

Quickstart

From zero to your first voice transcription in under five minutes. Runs on Linux (Wayland + X11) and Windows 10/11.

1. Install

Linux: Download the AppImage from GitHub Releases, make it executable, and run it:

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

To set up the desktop entry and text-injection helpers (wtype/xdotool), run the built-in installer:

./VoxCtrl-x86_64.AppImage --install

You can also launch the AppImage normally — if a helper package is missing, a setup window appears automatically with a one-click button that prompts for your password via pkexec.

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

2. Permissions (Linux)

None required for hotkeys. voxctrl registers global shortcuts through your desktop's XDG GlobalShortcuts portal — your desktop owns the key grab, and voxctrl never reads your keyboard. No udev rule, no input group, no logout. See Hotkeys & gestures for the evdev fallback path used only on compositors without a portal. On Windows, no special permissions are required either — hotkeys use Win32 hooks.

3. Download a model

On first launch, voxctrl opens the Settings window. Go to Settings → Engine and download a Whisper model. Recommendations:

Models are stored in ~/.local/share/voxctrl/models/. The default inference backend is whisper.cpp, automatically selecting CUDA (NVIDIA, requires a CUDA-enabled build), Vulkan (AMD/Intel/NVIDIA), or CPU at startup. A Moonshine backend is also available — switch via Settings → Engine.

4. Speak

Click into any text field. Hold Super+Space. Speak. Release. Your transcript appears.

ⓘ If a model isn't downloaded yet, voxctrl automatically switches to the Engine tab on startup and shows a warning prompting you to pick and download one.

Next

next →Installation