c9ea6c7de7
* feat(flatpak): publish a signed self-hosted OSTree remote on releases (#785) release.yml gains publish-flatpak-remote: it imports the per-arch .flatpak bundles into an OSTree repo, signs commits and the summary with a provisioned GPG key, regenerates static deltas and the vocahq.flatpakrepo/index page, and pushes to VocaHQ/vocalinux-flatpak served by GitHub Pages — the Homebrew-tap analogue, so installs auto-update via flatpak update instead of per-release downloads. The job is secret-gated like publish-aur (FLATPAK_GPG_PRIVATE_KEY + FLATPAK_REPO_TOKEN) and skips itself while unconfigured. Prior repo objects are pulled back in from gh-pages so clients get incremental deltas. The manifest now declares branch: stable and the flatpakrepo declares DefaultBranch=stable + RuntimeRepo for the Flathub GNOME runtime. Docs: new docs/FLATPAK_REMOTE.md (one-time setup, rotation, verification); README, docs/INSTALL.md, packaging/flatpak/README.md and the release notes now lead with the remote and keep release bundles as the no-auto-update fallback. tests/test_release_integrity.py pins the job's shape. Closes #785 * fix(flatpak-remote): publish a .flatpakref and gate the remote to stable tags - needs build-and-release so the remote cannot lead the GitHub Release - stable tags only: prereleases must not reach `flatpak update` - probe gh-pages before the empty-repo fallback: a transient checkout failure no longer discards remote history - publish com.vocalinux.Vocalinux.flatpakref (RuntimeRepo lives there, not on .flatpakrepo) plus vocahq.gpg, so clean installs resolve the GNOME runtime and key rotation works via remote-modify --gpg-import - gate the release-notes remote instructions on the publish actually running; the bundle path stays primary otherwise - document rotation via remote-modify --gpg-import / remote-delete --force and the explicit Flathub setup step --------- Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
11 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) or GitHub .snap |
| 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
The source installer uses committed, hash-verified Python dependency exports, including its pip and source-build tools. GTK/PyGObject still comes from your distribution, and the venv retains access to system packages. A missing export or unavailable pinned package causes that installation step to fail; the existing optional-engine and VAD fallbacks still apply.
Remote installs run the installer from the selected release tag. Older tags therefore retain their original dependency-install behavior; downloading a new bootstrap script does not change an older release's pins.
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 AppImage floor. The installer and PyPI package still require a distro that ships Python 3.11+, so they are not a workaround for Debian 11 or Ubuntu 20.04.
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
Install and auto-update via the self-hosted VocaHQ remote (flatpak update picks up each release):
flatpak install https://vocahq.github.io/vocalinux-flatpak/com.vocalinux.Vocalinux.flatpakref
The .flatpakref adds the vocahq remote and resolves the GNOME runtime through Flathub. Manually instead:
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --if-not-exists vocahq https://vocahq.github.io/vocalinux-flatpak/vocahq.flatpakrepo
flatpak install vocahq com.vocalinux.Vocalinux
Or sideload a GitHub Release bundle (Vocalinux-<version>-x86_64.flatpak or -aarch64.flatpak) after the Flathub GNOME runtime is present — bundles do not auto-update:
flatpak install --user ./Vocalinux-<version>-x86_64.flatpak
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 attach vocalinux_<version>_amd64.snap to the GitHub Release and try Snap Store edge and candidate when credentials are set. stable is still a manual promote after QA.
Store install, once Canonical lists the revision:
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:hardware-observe # list keyboards (/proc/bus/input/devices)
sudo snap connect vocalinux:uinput # native Wayland typing (ydotool)
v0.17.0 ships ydotool and the uinput plug. That plug is super-privileged, so the Store held 0.17.0 for human review (allow-installation). Until a 0.17.0+ revision is listed, snap info vocalinux still shows v0.16.2 (rev 7) on edge. That revision has no uinput plug; sudo snap connect vocalinux:uinput fails.
Sideload the GitHub .snap (amd64) while the Store is waiting:
sudo snap install --dangerous ./vocalinux_0.17.0_amd64.snap
sudo snap connect vocalinux:audio-record
sudo snap connect vocalinux:raw-input
sudo snap connect vocalinux:hardware-observe
sudo snap connect vocalinux:uinput
--dangerous is required because this file is not a Store revision. It will not refresh from the Store. After Canonical grants uinput, switch to sudo snap install vocalinux --edge (or snap refresh).
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 |