Jatin K MalikandGitHub
4b6e81d441
* fix(snap): inject into native Wayland apps via ydotool Edge rev 7 only ships wtype and xdotool. GNOME rejects the virtual keyboard protocol, so the snap falls back to xdotool and types only into XWayland windows. Native GTK/Qt apps get nothing. Stage ydotool, request the uinput plug, and prefer ydotool when wtype is rejected. Distro ydotool 0.1.x still needs a writable /dev/uinput; log `snap connect vocalinux:uinput` when the Snap cannot open it. * docs(snap): v0.16.2 edge has no uinput plug The store snap (0.16.2, latest/edge rev 7) does not declare uinput. `sudo snap connect vocalinux:uinput` fails with "has no plug named uinput" and dictation only reaches XWayland apps. Spell that out in README, INSTALL, UPDATE, the website changelog, and the store copy so people do not run the 0.17 connect command against rev 7. * docs(snap): drop the unconfirmed 0.17 version from uinput notes Greptile P2: the tree is still 0.16.2 and the release process does not name the next tag. Tell people to refresh until `snap info` lists the uinput plug, instead of waiting on a version we have not cut.
9.3 KiB
Installation guide
How to install Vocalinux on Linux. Short overview: project README.
| Path | When to use |
|---|---|
| Recommended installer | Most users |
| AppImage | Portable binary; no system package install |
| AUR | Arch / Manjaro |
| Flatpak | Release .flatpak or local build |
| Snap | Ubuntu Snap Store (--edge) |
| From source | Contributors or custom trees |
| Manual / PyPI | Full control or pip-only workflows |
| Troubleshooting | Tray, audio, injection, models |
Recommended installer
Download, review if you like, then run:
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
bash /tmp/vl.sh
Installs the latest release with whisper.cpp by default. For a pinned version, see GitHub Releases or pass --tag=....
The installer:
- Installs whisper.cpp (typically ~1-2 minutes; no full PyTorch stack)
- Detects GPU / Vulkan (AMD, Intel, NVIDIA)
- Installs neural VAD when ONNX Runtime is available
- Downloads the default whisper.cpp tiny model (~74MB), verified against pinned checksums
- Sets up desktop integration and launch wrappers
Installer modes
./install.sh # Interactive (recommended)
./install.sh --auto # Defaults: whisper.cpp
./install.sh --auto --engine=whisper # OpenAI Whisper
./install.sh --auto --engine=faster_whisper # Faster Whisper (CPU)
./install.sh --auto --engine=vosk # VOSK only
./install.sh --auto --engine=parakeet # Parakeet (CPU)
./install.sh --auto --engine=remote_api # Remote HTTP API
./install.sh --dev # Editable install + test tools
./install.sh --help # Full flag list
| Engine | When to use | Typical install |
|---|---|---|
| whisper.cpp (default) | Best default; Vulkan GPU | ~1-2 min, ~74MB model |
| Whisper (OpenAI) | PyTorch / CUDA | ~5-10 min, large download |
| Faster Whisper | CPU Whisper via CTranslate2 / INT8 | Model sizes like OpenAI Whisper |
| VOSK | Low RAM / minimal | ~30 sec, ~40MB |
| Parakeet | CPU; 25 European languages | Model ~639MB |
| Remote API | User-configured HTTP server | No local model |
Useful flags: --tag=TAG, --skip-models, --rebuild-whispercpp, --no-rebuild-whispercpp, --venv-dir=PATH, --test.
--engine=NAME accepts whisper_cpp (default), whisper, faster_whisper, vosk, parakeet, remote_api.
What the installer does
- Detects the distribution and installs system packages
- Creates a Python venv from the system interpreter with
--system-site-packages(for distro GTK / PyGObject) - Installs Vocalinux and the chosen speech engine
- Optionally installs neural VAD (
onnxruntime) - Downloads a default speech model (checksum-verified)
- Installs icons, desktop entry, and
~/.local/binwrappers
AppImage
From GitHub Releases:
chmod +x Vocalinux-*-x86_64.AppImage # or aarch64
./Vocalinux-*-x86_64.AppImage
Built against glibc 2.35, so it starts on Debian 12+, Ubuntu 22.04+, Fedora 36+, Arch, and Tumbleweed. Older bases (RHEL 9, Debian 11, Ubuntu 20.04) are below that floor; use the installer or PyPI there.
Still needs host text-injection tools (xdotool on X11; wtype / ydotool / clipboard tools on Wayland). Current AppImages rebuild whisper.cpp with Vulkan and use the host GPU driver (vulkaninfo --summary). Prefer the installer when you want system deps, a CUDA build, and models set up automatically.
Arch Linux (AUR)
yay -S vocalinux
See AUR.md.
Flatpak
GitHub Releases attach Vocalinux-<version>-x86_64.flatpak and Vocalinux-<version>-aarch64.flatpak. After the Flathub GNOME runtime is present:
flatpak install --user ./Vocalinux-<version>-x86_64.flatpak
Bundles do not auto-update.
Local build (contributors):
flatpak install flathub org.gnome.Platform//50 org.gnome.Sdk//50
flatpak-builder --user --install --force-clean build-dir \
packaging/flatpak/com.vocalinux.Vocalinux.yml
flatpak run com.vocalinux.Vocalinux
Whisper.cpp + Vulkan. It is not on Flathub (submission flathub#9368 closed 2026-07-23 on policy grounds). Details: packaging/flatpak/README.md.
Snap (Ubuntu Snap Store)
Listing: snapcraft.io/vocalinux (issue #48). Recipe: snap/snapcraft.yaml. Tagged v* releases publish to Snap Store edge and candidate when credentials are set. stable is still a manual promote after QA.
sudo snap install vocalinux --edge
sudo snap connect vocalinux:audio-record # if mic is not auto-connected
sudo snap connect vocalinux:raw-input # global keyboard shortcuts (evdev)
sudo snap connect vocalinux:uinput # native Wayland typing (ydotool)
v0.16.2 edge (rev 7) has no uinput plug. sudo snap connect vocalinux:uinput fails with snap "vocalinux" has no plug named "uinput". That build only types into XWayland apps (Firefox/Chrome often work; native GNOME/GTK/Qt do not). A later store revision ships ydotool and the plug. After snap info vocalinux lists uinput, sudo snap refresh vocalinux, connect uinput, and restart Vocalinux.
From source
git clone https://github.com/VocaHQ/vocalinux.git
cd vocalinux
./install.sh
System requirements
| Requirement | Details |
|---|---|
| OS | Ubuntu 24.04+, Debian 12+, Fedora 42+, Arch, openSUSE Tumbleweed |
| Python | 3.11 or newer |
| Display | X11 or Wayland |
| Hardware | Microphone; GPU optional (Vulkan) |
| Disk | ~200MB with default whisper.cpp model |
| RAM | 4GB minimum; 8GB comfortable |
The distro must ship Python 3.11+ because Vocalinux uses distro PyGObject (python3-gi). Ubuntu 22.04 (Python 3.10) and Debian 11 (3.9) are below that floor. Distro matrix: DISTRO_COMPATIBILITY.md.
GPU (optional)
whisper.cpp uses Vulkan when available (AMD, Intel, NVIDIA). Check with vulkaninfo --summary.
Running Vocalinux
vocalinux # if ~/.local/bin is on PATH
~/.local/share/vocalinux/venv/bin/vocalinux # direct
source venv/bin/activate && vocalinux # source checkout
Or launch from the application menu.
CLI
vocalinux --help
vocalinux --version
vocalinux --debug
vocalinux --engine whisper_cpp
vocalinux --engine whisper
vocalinux --engine vosk
vocalinux --engine parakeet
vocalinux --engine remote_api
vocalinux --model tiny
vocalinux --model medium.en-q5_0
vocalinux --model large-v3-turbo
vocalinux --wayland
vocalinux --start-minimized
Autostart
Start on Login writes an XDG autostart desktop entry (~/.config/autostart/). It does not install a systemd unit. Enable from the first-run dialog, tray menu, or Settings.
Data locations (XDG)
| Directory | Purpose |
|---|---|
~/.config/vocalinux/ |
Configuration |
~/.local/share/vocalinux/ |
Data and speech models |
~/.local/share/applications/ |
Desktop entry |
~/.local/share/icons/hicolor/scalable/apps/ |
Icons |
whisper.cpp (default engine)
Default engine: C++ Whisper port with Vulkan GPU support and lower install cost than the PyTorch Whisper stack.
| Size | Approx. | Use |
|---|---|---|
| tiny | ~74MB | Fast dictation (default) |
| base | ~141MB | Balance |
| small | ~465MB | Better accuracy |
| medium | ~1.5GB | High accuracy |
| large | ~3.0GB | Best accuracy |
In Settings → Speech Model, simple setup steers language and speed/accuracy. Expand Advanced for engine, Model Size, and Specialization (multilingual, English-only, quantized, Turbo, legacy large). More detail: USER_GUIDE.md.
Reuse an existing pywhispercpp build:
./install.sh --auto # reuse if present
./install.sh --auto --rebuild-whispercpp # force rebuild
Switch engines in Settings → Speech Model (Advanced), or edit ~/.config/vocalinux/config.json (engine: whisper_cpp | whisper | vosk | parakeet | remote_api).
Uninstall
./uninstall.sh
./uninstall.sh --keep-config
./uninstall.sh --keep-data
Manual cleanup:
rm -rf venv ~/.config/vocalinux ~/.local/share/vocalinux
rm -f activate-vocalinux.sh
rm -f ~/.local/share/applications/vocalinux.desktop
rm -f ~/.local/share/icons/hicolor/scalable/apps/vocalinux*.svg
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
Update
See UPDATE.md.
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
bash /tmp/vl.sh
More documentation
| Doc | Contents |
|---|---|
| INSTALL_MANUAL.md | Manual install, PyPI/pipx, per-distro packages |
| TROUBLESHOOTING.md | Common failures and fixes |
| DISTRO_COMPATIBILITY.md | Support matrix |
| USER_GUIDE.md | Day-to-day use |
| SUPPORT.md | Where to get help |
| Documentation index | Full list |