Jatin K MalikandGitHub
f48bdda525
* docs: polish project documentation for a clearer public surface Rewrite the README and supporting docs for a more professional first impression: less emoji and badge noise, install-first structure, and a real documentation index. Add a Contributor Covenant, tighten SECURITY and GitHub templates, and make distro/update guides read as product docs instead of internal status notes. * docs: split install guide and add changelog plus support pages Break INSTALL.md into a short primary guide, manual/PyPI package lists, and troubleshooting. Add root CHANGELOG.md and SUPPORT.md, wire them into the docs index and README, and drop the outdated screenshot lag note now that v0.15 assets are on main. * docs: humanize PR copy and remove em dashes Strip em/en dashes from the documentation rewritten in this PR, fix mid-sentence colon fallout from that pass, and smooth a few stiff phrases so the public docs read more natural. * docs: list Faster Whisper after rebase onto main Installer and CLI already accept faster_whisper. Document it next to the other engines, drop the outdated screenshot lag note, and keep the on-device wording honest for local vs remote.
8.9 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)
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 |