From 91708fdf4a3562ff153a51bdccc6870500a44195 Mon Sep 17 00:00:00 2001 From: Xavier Karma Date: Fri, 6 Nov 2026 21:25:42 +0530 Subject: [PATCH] docs: publish Void xbps as the only install channel Install, update and support docs now name the signed Void xbps repository as the one published channel and the fork's own host for source, issues and releases. AUR, AppImage, .deb/.rpm, Flatpak, Snap, Nix, PyPI and the upstream install script are no longer offered. The one upstream credit line is kept in the README and CONTRIBUTING. --- CONTRIBUTING.md | 34 ++- README.md | 252 +++++----------------- SECURITY.md | 18 +- SUPPORT.md | 13 +- docs/DISTRO_COMPATIBILITY.md | 211 ++++--------------- docs/INSTALL.md | 392 ++++++++++++----------------------- docs/TROUBLESHOOTING.md | 138 ++++++------ docs/UPDATE.md | 190 ++++++----------- 8 files changed, 391 insertions(+), 857 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64f195c..6d856e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,17 +8,17 @@ Participation is covered by our [Code of Conduct](CODE_OF_CONDUCT.md). Be respec ## Ways to contribute -- **Report bugs** - [Open an issue](https://github.com/VocaHQ/vocalinux/issues/new?template=bug_report.md) -- **Suggest features** - [Feature request](https://github.com/VocaHQ/vocalinux/issues/new?template=feature_request.md) or [Discussions](https://github.com/VocaHQ/vocalinux/discussions) +- **Report bugs** - [Open an issue](https://git.bongbetic.com/xavierk/voculinux/issues/new) +- **Suggest features** - [Open an issue](https://git.bongbetic.com/xavierk/voculinux/issues/new) with the capability you want - **Improve documentation** - Fixes and clarity are always useful -- **Fix bugs or add features** - Check [open issues](https://github.com/VocaHQ/vocalinux/issues), especially [`good first issue`](https://github.com/VocaHQ/vocalinux/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +- **Fix bugs or add features** - Check [open issues](https://git.bongbetic.com/xavierk/voculinux/issues) ## Development setup ### Automated (recommended) ```bash -git clone https://github.com/YOUR-USERNAME/voculinux.git +git clone https://git.bongbetic.com/YOUR-USERNAME/voculinux.git cd voculinux ./install.sh --dev ``` @@ -30,7 +30,9 @@ tools, and runs the test suite. See [The two environments](#the-two-environments 1. Fork and clone the repository. -2. Install system dependencies (examples): +2. Install system dependencies (examples). Voculinux is published only as a + Void Linux xbps package; the distro examples below are for building from a + source checkout: **Ubuntu 24.04+:** ```bash @@ -117,10 +119,6 @@ The repository uses two virtual environments on purpose. Do not merge them: an activated venv and rebuilds one created by the wrong interpreter. It uses `/usr/bin/python3` unless overridden, e.g. `SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh`. -`just appimage` bundles its own Python/PyGObject in the pinned Ubuntu Docker image. -For GI failures, check `Checking bundled PyGObject after linuxdeploy` and the smoke -test's path diagnostics; installing `python3-gobject` on the host won't fix the bundle. - ## Making changes ### Branch naming @@ -163,9 +161,9 @@ voculinux/ ├── resources/ # Icons and sounds ├── docs/ ├── install.d/ # Installer modules, including generated package data -├── packaging/ # AppImage, AUR, Flatpak +├── packaging/ # Packaging inputs; Void xbps is the published channel ├── scripts/ # Maintenance tools and distro package-map source -├── snap/ # Snap recipe +├── snap/ # Snap recipe (not published for Voculinux) └── web/ # Marketing site (Next.js) ``` @@ -274,16 +272,12 @@ Maintainers follow [docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md) (version f ## Community - [SUPPORT.md](SUPPORT.md) - where to get help -- [Discord](https://discord.gg/t6muquAJbm) - fastest place to talk with maintainers and other contributors -- [GitHub Discussions](https://github.com/VocaHQ/vocalinux/discussions) -- [GitHub Issues](https://github.com/VocaHQ/vocalinux/issues) -- [@vocahq on X](https://x.com/vocahq) +- [Issues](https://git.bongbetic.com/xavierk/voculinux/issues) ## License Contributions are licensed under the [GNU Affero General Public License v3.0](LICENSE) -(AGPL-3.0), matching the other [VocaHQ](https://github.com/VocaHQ) distribution -projects ([VocaMac](https://github.com/VocaHQ/vocamac), -[VocaPhone](https://github.com/VocaHQ/vocaphone), -[VocaGateway](https://github.com/VocaHQ/vocagateway)). By opening a pull request, you -agree that your contribution may be distributed under that license. +(AGPL-3.0). By opening a pull request, you agree that your contribution may be +distributed under that license. + +Voculinux is a hard fork of Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux diff --git a/README.md b/README.md index 43e75ff..8a71a22 100644 --- a/README.md +++ b/README.md @@ -6,51 +6,33 @@ **Voice dictation for Linux** -[![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04+-E95420?logo=ubuntu&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) -[![Debian](https://img.shields.io/badge/Debian-12+-A81D33?logo=debian&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) -[![Fedora](https://img.shields.io/badge/Fedora-42+-51A2DA?logo=fedora&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) -[![Arch](https://img.shields.io/badge/Arch-rolling-1793D1?logo=archlinux&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) -[![openSUSE](https://img.shields.io/badge/openSUSE-Tumbleweed-73BA25?logo=opensuse&logoColor=white)](docs/DISTRO_COMPATIBILITY.md) - -[![Privacy: on-device](https://img.shields.io/badge/privacy-on--device-success)](https://github.com/VocaHQ/vocalinux#privacy-and-security) -[![X11 & Wayland](https://img.shields.io/badge/display-X11%20%7C%20Wayland-lightgrey)](https://github.com/VocaHQ/vocalinux#features) -[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) +[![Void Linux](https://img.shields.io/badge/Void%20Linux-glibc%20x86__64-478061)](#void-linux-signed-xbps-repo) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) -[![GitHub release](https://img.shields.io/github/v/release/VocaHQ/vocalinux)](https://github.com/VocaHQ/vocalinux/releases) +[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) +[![Privacy: on-device](https://img.shields.io/badge/privacy-on--device-success)](#privacy-and-security) +[![X11 & Wayland](https://img.shields.io/badge/display-X11%20%7C%20Wayland-lightgrey)](#features) +[![Release](https://img.shields.io/badge/release-v0.18.5-478061)](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.18.5) -[![AppImage](https://img.shields.io/badge/AppImage-x86__64%20%7C%20aarch64-2C5BB4)](https://github.com/VocaHQ/vocalinux/releases/latest) -[![.deb](https://img.shields.io/badge/.deb-Debian%20%7C%20Ubuntu-A81D33?logo=debian&logoColor=white)](https://github.com/VocaHQ/vocalinux/releases/latest) -[![.rpm](https://img.shields.io/badge/.rpm-Fedora-EE0000?logo=fedora&logoColor=white)](https://github.com/VocaHQ/vocalinux/releases/latest) -[![Flatpak](https://img.shields.io/badge/Flatpak-vocahq%20remote-4A90D9?logo=flatpak&logoColor=white)](#flatpak-any-distro) -[![Snap](https://img.shields.io/badge/Snap-edge-82BEA0?logo=snapcraft&logoColor=white)](https://snapcraft.io/voculinux) -[![AUR](https://img.shields.io/aur/version/voculinux)](https://aur.archlinux.org/packages/voculinux) -[![PyPI](https://img.shields.io/pypi/v/voculinux)](https://pypi.org/project/voculinux/) -[![Nix flake](https://img.shields.io/badge/Nix-flake-5277C3?logo=nixos&logoColor=white)](packaging/nix/README.md) - -[![Discord](https://img.shields.io/discord/1538633755877580810?logo=discord&logoColor=white&label=Discord)](https://discord.gg/t6muquAJbm) -[![VocaHQ](https://img.shields.io/badge/VocaHQ-vocahq.com-1a7f4e)](https://vocahq.com) -[![Follow on X](https://img.shields.io/badge/Follow%20%40vocahq-000000?style=flat&logo=x&logoColor=white)](https://x.com/vocahq) - -[Website](https://voculinux.com) · [Install](#install) · [Docs](#documentation) · [Releases](https://github.com/VocaHQ/vocalinux/releases) +[Website](https://voculinux.com) · [Install](#install) · [Docs](#documentation) · [Releases](https://git.bongbetic.com/xavierk/voculinux/releases) · [Issues](https://git.bongbetic.com/xavierk/voculinux/issues) Voculinux turns speech into typed text in whatever app has focus. It is a free, AGPL-3.0-licensed desktop app for X11 and Wayland. After you download a model, local engines (whisper.cpp by default, plus OpenAI Whisper, Faster Whisper, VOSK, and Parakeet) run speech-to-text on your machine. An optional remote HTTP API is off unless you configure it. -No Voca account is required. Models download once. After that, speech-to-text stays on your machine. +No account is required. Models download once. After that, speech-to-text stays on your machine. -**Current release:** [v0.18.5](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.5). Patch: a stop that races a recording start can no longer leave the mic recording forever, keyboards stay alive through suspend and the GNOME lock screen, Ctrl+mouse-wheel zoom works again, Dictation Pad and Settings stop travelling workspaces together, paste-injection copies are marked sensitive for clipboard history on wl-clipboard 2.2+, and `install.sh` gains an upgrade mode that keeps your existing configuration. Details: [docs/UPDATE.md](docs/UPDATE.md). +**Current release:** [v0.18.5](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.18.5). Patch: a stop that races a recording start can no longer leave the mic recording forever, keyboards stay alive through suspend and the GNOME lock screen, Ctrl+mouse-wheel zoom works again, Dictation Pad and Settings stop travelling workspaces together, and paste-injection copies are marked sensitive for clipboard history on wl-clipboard 2.2+. Details: [docs/UPDATE.md](docs/UPDATE.md). ## Features - **On-device after model download**: Local engines; speech-to-text stays on your machine - **X11 and Wayland**: Text injection via xdotool, IBus, wtype, ydotool, or clipboard fallback -- **Several engines**: whisper.cpp (default), OpenAI Whisper, Faster Whisper, VOSK, Parakeet, plus optional remote HTTP API or local VocaGateway from Settings (not on-device) +- **Several engines**: whisper.cpp (default), OpenAI Whisper, Faster Whisper, VOSK, Parakeet, plus optional remote HTTP API or local gateway from Settings (not on-device) - **GPU acceleration**: Vulkan for AMD, Intel, and NVIDIA with whisper.cpp - **Toggle or push-to-talk**: New installs default to hold Right Alt; existing configs keep their shortcut - **System tray + settings**: Searchable sidebar, Speech Model simple setup with Advanced as an island, status icons, audio feedback - **Start on login**: XDG autostart (desktop session, not a systemd service) -- **Packaging**: install script, `.deb` / `.rpm`, AppImage, AUR, PyPI, Snap (`--edge`), Flatpak (release bundles and local build; not on Flathub), Nix flake +- **Packaging**: signed Void Linux xbps repository (glibc, x86_64). No other channel is published for Voculinux ## Screenshots @@ -126,115 +108,9 @@ Voculinux in action. Full gallery on the [website screenshots page](https://vocu ## Install -### Recommended (interactive installer) - -```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh -``` - -Prefer to review the script first: open `/tmp/vl.sh` before running it, or clone the repo and run `./install.sh` locally. - -The installer detects hardware, recommends an engine, downloads a default model (~74MB for whisper.cpp tiny), installs neural VAD when ONNX Runtime is available, and sets up desktop integration. Typical install time with whisper.cpp is about 1-2 minutes. - -| Engine | When to use | -|--------|-------------| -| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA | -| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA | -| **Faster Whisper** | CPU-friendly Whisper via CTranslate2 / INT8 | -| **VOSK** | Low RAM / minimal footprint | -| **Parakeet** | CPU; NVIDIA NeMo ASR via sherpa-onnx; 25 European languages | -| **Remote API** | Offload to a server you configure | - -Non-interactive options: - -```bash -bash /tmp/vl.sh --auto # whisper.cpp defaults -bash /tmp/vl.sh --auto --engine=whisper # OpenAI Whisper -bash /tmp/vl.sh --auto --engine=faster_whisper # Faster Whisper (CPU) -bash /tmp/vl.sh --auto --engine=vosk # VOSK only -bash /tmp/vl.sh --auto --engine=parakeet # Parakeet (CPU) -``` - -For a specific release tag, see [GitHub Releases](https://github.com/VocaHQ/vocalinux/releases) or `./install.sh --tag=v0.18.5`. - -### Arch Linux (AUR) - -```bash -yay -S voculinux -``` - -See [docs/AUR.md](docs/AUR.md). - -### AppImage - -Download the `x86_64` or `aarch64` AppImage from [Releases](https://github.com/VocaHQ/vocalinux/releases), mark it executable, and run it. Built against glibc 2.35 (Debian 12+, Ubuntu 22.04+, Fedora 36+, Arch, Tumbleweed). Host text-injection tools (`xdotool` on X11; `wtype` / `ydotool` / clipboard tools on Wayland) are still required. Current AppImages rebuild whisper.cpp with Vulkan and use the host GPU driver. Prefer the installer when you want system deps, a CUDA build, and models set up automatically. - -### Distro packages (.deb / .rpm) - -Download the `.deb` (Debian 12+, Ubuntu 24.04+) or `.rpm` (Fedora) matching your CPU from [Releases](https://github.com/VocaHQ/vocalinux/releases) and install with `sudo apt install ./voculinux_*.deb` or `sudo dnf install ./voculinux-*.rpm`. Thin packages: Python and GTK come from the distro. No auto-update; CPU whisper.cpp. Details in [docs/INSTALL.md](docs/INSTALL.md). - -### Flatpak (any distro) - -Install and auto-update via the self-hosted VocaHQ remote (`flatpak update` picks up each release): - -```bash -flatpak install https://vocahq.github.io/voculinux-flatpak/com.voculinux.Voculinux.flatpakref -``` - -The `.flatpakref` adds the `vocahq` remote and resolves the GNOME runtime through Flathub. Manually instead: - -```bash -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/voculinux-flatpak/vocahq.flatpakrepo -flatpak install vocahq com.voculinux.Voculinux -``` - -Or sideload a GitHub Release bundle (`Voculinux--x86_64.flatpak` or `-aarch64.flatpak`) after the Flathub GNOME runtime is present — bundles do not auto-update: - -```bash -flatpak install --user ./Voculinux--x86_64.flatpak -``` - -Local build: - -```bash -flatpak install flathub org.gnome.Platform//50 org.gnome.Sdk//50 -flatpak-builder --user --install --force-clean build-dir \ - packaging/flatpak/com.voculinux.Voculinux.yml -flatpak run com.voculinux.Voculinux -``` - -Ships whisper.cpp with Vulkan. It is **not on Flathub** (submission [flathub#9368](https://github.com/flathub/flathub/pull/9368) closed 2026-07-23 on policy grounds). Details: [packaging/flatpak/README.md](packaging/flatpak/README.md). - -### Snap (Ubuntu Snap Store) - -Listing: [snapcraft.io/voculinux](https://snapcraft.io/voculinux). `stable` is promoted from `candidate` after QA. Tagged releases also attach `voculinux__amd64.snap` on GitHub. - -```bash -sudo snap install voculinux --edge -sudo snap connect voculinux:audio-record # if mic is not auto-connected -sudo snap connect voculinux:raw-input # global keyboard shortcuts (evdev) -sudo snap connect voculinux:hardware-observe # list keyboards (/proc/bus/input/devices) -``` - -Native Wayland typing uses the RemoteDesktop portal: the compositor asks once on first dictation, nothing to connect. The recipe ships **no `uinput` plug** and no ydotool; the Store denied the super-privileged grant, which held the 0.17.0+ revisions and left **v0.16.2 (rev 7)** on edge. On KDE Plasma, KWin's portal can mistype letter case ([KDE bug 489021](https://bugs.kde.org/show_bug.cgi?id=489021)); set Virtual Keyboard to "IBus Wayland" so dictation types correctly. - -GitHub `.snap` files through v0.18.2 declare `uinput`, so KDE users who want ydotool can sideload that build and connect the plug manually: - -```bash -sudo snap install --dangerous ./voculinux_0.18.2_amd64.snap -sudo snap connect voculinux:uinput # only in the v0.18.x sideload; the recipe no longer ships it -``` - -### Nix / NixOS (flake) - -```bash -nix run github:VocaHQ/vocalinux # try it -nix profile install github:VocaHQ/vocalinux -``` - -The flake also ships `nixosModules.voculinux` and `homeManagerModules.voculinux` for declarative installs (`programs.voculinux.enable = true`). The bundled pywhispercpp builds with Vulkan GPU inference. Details: [packaging/nix/README.md](packaging/nix/README.md). +Voculinux is published only as a signed Void Linux xbps repository. Other +channels (AUR, AppImage, `.deb` / `.rpm`, Flatpak, Snap, Nix, PyPI and the +upstream install script) are not published for Voculinux. ### Void Linux (signed xbps repo) @@ -269,42 +145,50 @@ sync and asks nothing. If xbps still shows a fingerprint prompt, answer `FINGERPRINT` file attached to the release). Do not add `-y` to the first sync: it would accept an unknown key without asking. -### From source +### Speech engines -```bash -git clone https://github.com/VocaHQ/vocalinux.git -cd voculinux -./install.sh -# or pick the engine up front -./install.sh --engine=whisper_cpp -./install.sh --engine=vosk -./install.sh --engine=parakeet --auto -``` +| Engine | When to use | +|--------|-------------| +| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA | +| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA | +| **Faster Whisper** | CPU-friendly Whisper via CTranslate2 / INT8 | +| **VOSK** | Low RAM / minimal footprint | +| **Parakeet** | CPU; NVIDIA NeMo ASR via sherpa-onnx; 25 European languages | +| **Remote API** | Offload to a server you configure | + +The xbps package does not include the optional engines (Faster Whisper, Whisper, +VOSK, Parakeet) or the Silero VAD runtime (`onnxruntime`). Add them from your own +Python environment, as the package's install message describes. Models download +on first run. ### After installation ```bash -voculinux # if ~/.local/bin is on PATH -# or -~/.local/share/voculinux/venv/bin/voculinux +voculinux # from the xbps package, on your PATH ``` You can also launch Voculinux from your application menu. -### Nightly builds +### From a source checkout (developers) -Daily builds from `main` appear on [Releases](https://github.com/VocaHQ/vocalinux/releases). Use the latest stable or beta release for production; nightlies are untested. +```bash +git clone https://git.bongbetic.com/xavierk/voculinux.git +cd voculinux +./install.sh --dev +``` + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the two-venv layout and the dev workflow. ## Requirements | | | |--|--| -| **OS** | Linux (Ubuntu 24.04+, Debian 12+, Fedora 42+, Arch, openSUSE Tumbleweed) | +| **OS** | Linux. The published package targets Void Linux (glibc, x86_64) | | **Python** | 3.11 or newer | | **Display** | X11 or Wayland | | **Hardware** | Microphone; GPU optional (Vulkan) | -The distro must ship Python 3.11+ because Voculinux uses distro PyGObject (`python3-gi`). Ubuntu 22.04 (Python 3.10) and Debian 11 (3.9) are below that floor. Distribution notes: [docs/DISTRO_COMPATIBILITY.md](docs/DISTRO_COMPATIBILITY.md). +Python 3.11+ is required, with PyGObject from the system (`python3-gi` or the Void `python3-gobject` package). Ubuntu 22.04 (Python 3.10) and Debian 11 (3.9) are below that floor. Source-checkout distribution notes: [docs/DISTRO_COMPATIBILITY.md](docs/DISTRO_COMPATIBILITY.md). ## Usage @@ -359,14 +243,13 @@ voculinux --start-minimized Stored at `~/.config/voculinux/config.json`. Prefer the Settings dialog for day-to-day changes. **Settings → Speech Model** starts with a simple setup; expand **Advanced** for engine, size, and specialization. Set `post_processing.script_path` to an executable to transform each transcription result (stdin → stdout) before it is injected; leave empty to disable. -Neural VAD (Silero) is used when `onnxruntime` is available; install via `pip install "voculinux[vad]"` for manual/PyPI installs. The installer attempts this automatically. +Neural VAD (Silero) is used when `onnxruntime` is available. The xbps package does not pull it in; add `onnxruntime` from your own Python environment. ## Documentation | Document | Description | |----------|-------------| -| [Installation](docs/INSTALL.md) | Installer, AppImage, AUR, Flatpak, Snap, Nix flake, running | -| [Manual / PyPI install](docs/INSTALL_MANUAL.md) | Package lists and pip workflows | +| [Installation](docs/INSTALL.md) | Void xbps repository and running | | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common failures | | [User guide](docs/USER_GUIDE.md) | Dictation, engines, models, tips | | [Update guide](docs/UPDATE.md) | Upgrade steps and release notes | @@ -374,7 +257,6 @@ Neural VAD (Silero) is used when `onnxruntime` is available; install via `pip in | [Support](SUPPORT.md) | Where to get help | | [Distribution compatibility](docs/DISTRO_COMPATIBILITY.md) | Distro matrix and session notes | | [Remote HTTP API](docs/HTTP_REMOTE.md) | Offload transcription to a server | -| [Local VocaGateway (optional)](docs/GATEWAY_EMBED.md) | Start a local gateway from Settings; not on-device | | [Contributing](CONTRIBUTING.md) | Dev setup, style, PR process | | [Security](SECURITY.md) | Supported versions and vulnerability reporting | | [Docs index](docs/README.md) | Full documentation map | @@ -390,7 +272,7 @@ Report vulnerabilities privately per [SECURITY.md](SECURITY.md). ## Development ```bash -git clone https://github.com/VocaHQ/vocalinux.git +git clone https://git.bongbetic.com/xavierk/voculinux.git cd voculinux ./install.sh --dev source venv/bin/activate @@ -402,69 +284,41 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the two-venv layout, `just` recipes, ## Roadmap -Shipped: graphical settings, multi-language support, whisper.cpp default, Vulkan GPU, Wayland/IBus, Flatpak packaging, AppImage, `.deb` / `.rpm` packages, in-app update checker, Parakeet and Faster Whisper engines, Snap recipe. +Shipped: graphical settings, multi-language support, whisper.cpp default, Vulkan GPU, Wayland/IBus, in-app update checker, Parakeet and Faster Whisper engines, Void Linux xbps packaging. Planned: - [ ] Application-specific voice commands - [ ] User-customizable voice command map -- [ ] Flathub publication (not currently listed; see #167) -## Voca ecosystem +## Origin -Voculinux is part of [VocaHQ](https://vocahq.com). On-device speech-to-text first, one app per platform. Optional [VocaGateway](https://vocagateway.vocahq.com) is self-hosted and not on-device. +Voculinux is a hard fork of Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux -| Platform | Project | Website | GitHub | -|----------|---------|---------|--------| -| Linux | **Voculinux** | [voculinux.com](https://voculinux.com) | [VocaHQ/vocalinux](https://github.com/VocaHQ/vocalinux) | -| macOS | **VocaMac** | [vocamac.com](https://vocamac.com) | [VocaHQ/vocamac](https://github.com/VocaHQ/vocamac) | -| Windows | **VocaWin** | [vocawin.com](https://vocawin.com) | [VocaHQ/vocawin](https://github.com/VocaHQ/vocawin) | -| Phone | **VocaPhone** | [vocaphone.vocahq.com](https://vocaphone.vocahq.com) | [VocaHQ/vocaphone](https://github.com/VocaHQ/vocaphone) | -| Gateway | **VocaGateway** | [vocagateway.vocahq.com](https://vocagateway.vocahq.com) | [VocaHQ/vocagateway](https://github.com/VocaHQ/vocagateway) | - -Talk to us: [Discord](https://discord.gg/t6muquAJbm) · [X @vocahq](https://x.com/vocahq) · [hello@vocahq.com](mailto:hello@vocahq.com) +Voculinux is that project's fork for Void Linux. Its source, issues and releases +live on the fork's own host. ## Contributing -Bug reports, docs, and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [good first issues](https://github.com/VocaHQ/vocalinux/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). +Bug reports, docs, and code are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](https://git.bongbetic.com/xavierk/voculinux/issues). -- [Report a bug](https://github.com/VocaHQ/vocalinux/issues/new?template=bug_report.md) -- [Request a feature](https://github.com/VocaHQ/vocalinux/issues/new?template=feature_request.md) -- [Discussions](https://github.com/VocaHQ/vocalinux/discussions) +- [Report a bug](https://git.bongbetic.com/xavierk/voculinux/issues/new) +- [Request a feature](https://git.bongbetic.com/xavierk/voculinux/issues/new) -### Contributors +## Repository -Thanks to everyone who has contributed code, docs, or fixes: - - - Voculinux contributors - - -## Repository mirrors - -GitHub is the primary forge for issues, PRs, CI, and releases. - -| Role | URL | -|------|-----| -| Primary | https://github.com/VocaHQ/vocalinux | -| Read-only mirror (Codeberg) | https://codeberg.org/jatinkrmalik/voculinux | - -Open issues and pull requests on GitHub only. +The source, issues, pull requests, and releases live at https://git.bongbetic.com/xavierk/voculinux. Open issues and +pull requests there. ## License This project is licensed under the **GNU Affero General Public License v3.0** -([AGPL-3.0](LICENSE)), aligning with the other [VocaHQ](https://github.com/VocaHQ) -distribution projects. +([AGPL-3.0](LICENSE)). You may use, study, modify, and redistribute the software under AGPL-3.0. If you run a modified version as a network service, AGPL also requires that you make the corresponding source available. -## Star Chart - -[![Star History Chart](https://api.star-history.com/chart?repos=VocaHQ/vocalinux&type=date&legend=top-left&sealed_token=ZWyQQLhSORoR4mKf6UXMGFSCBXRxM_yEZgc8MFCH_ysBjaFUm_OCH-bI3TD7OivczEzm-ADRIpF9xCWFOMHvBPW95eQBxzfRMpNksChz7rN_eiqL7AIMDw)](https://www.star-history.com/?type=date&repos=VocaHQ%2Fvocalinux) - ### Optional Orukeet model With the Parakeet engine installed, Settings → Speech Model → Parakeet also diff --git a/SECURITY.md b/SECURITY.md index 74e4ba1..a4c6cb4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -18,7 +18,7 @@ Upgrade to the latest release for security and reliability fixes. See [docs/UPDA Do not open a public GitHub issue for security vulnerabilities. -**Preferred:** email the maintainer at **jatinkrmalik@gmail.com** with subject: +Email the maintainer at **xavier@bongbetic.com** with subject: `Voculinux Security Vulnerability Report` @@ -31,14 +31,12 @@ Include: You should receive acknowledgment within 48 hours. We will assess severity, share an expected timeline, coordinate disclosure, and credit you in release notes if you want credit. -If email is unavailable, use [GitHub private vulnerability reporting](https://github.com/VocaHQ/vocalinux/security/advisories/new) when enabled for the repository. - ## Privacy design Voculinux is built for local-first dictation: - Local engines process audio on-device after you download a model -- No Voca account is required for local engines +- No account is required for local engines - No usage telemetry in the installed application - Models download once and stay in local cache - Downloads are checked against pinned checksums before install @@ -73,17 +71,17 @@ When the user enables **Remote API**, audio is uploaded to the configured server ## Keeping installs current +On Void Linux, update through the signed xbps repository: + ```bash -# Re-run the official installer (preserves config and models) -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +sudo xbps-install -Su voculinux ``` -Or follow [docs/UPDATE.md](docs/UPDATE.md) for source, AUR, AppImage, Snap, and Flatpak paths. +Source checkouts and other paths are in [docs/UPDATE.md](docs/UPDATE.md). ## Contact | Topic | Contact | |-------|---------| -| Security | jatinkrmalik@gmail.com | -| General bugs | https://github.com/VocaHQ/vocalinux/issues | +| Security | xavier@bongbetic.com | +| General bugs | https://git.bongbetic.com/xavierk/voculinux/issues | diff --git a/SUPPORT.md b/SUPPORT.md index dd37969..cb200e4 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -6,8 +6,7 @@ Where to get help with Voculinux. | Topic | Doc | |-------|-----| -| Install | [docs/INSTALL.md](docs/INSTALL.md) | -| Manual / PyPI install | [docs/INSTALL_MANUAL.md](docs/INSTALL_MANUAL.md) | +| Install (Void Linux xbps) | [docs/INSTALL.md](docs/INSTALL.md) | | Troubleshooting | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | | Day-to-day use | [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | | Upgrading | [docs/UPDATE.md](docs/UPDATE.md) | @@ -20,12 +19,10 @@ Where to get help with Voculinux. | Channel | Use for | |---------|---------| -| [Discord](https://discord.gg/t6muquAJbm) | Fastest place to talk with maintainers | -| [GitHub Discussions](https://github.com/VocaHQ/vocalinux/discussions) | Questions, setup help, ideas | -| [Bug report](https://github.com/VocaHQ/vocalinux/issues/new?template=bug_report.md) | Something is broken | -| [Feature request](https://github.com/VocaHQ/vocalinux/issues/new?template=feature_request.md) | New capability proposals | +| [Issues](https://git.bongbetic.com/xavierk/voculinux/issues) | Bug reports, feature ideas, and questions | +| [New issue](https://git.bongbetic.com/xavierk/voculinux/issues/new) | Something is broken or a new capability to propose | -When filing a bug, include OS/distro, `voculinux --version`, install method, display server (X11/Wayland), engine, and a `voculinux --debug` snippet. +When filing a bug, include OS/distro, `voculinux --version`, install method (the Void xbps package or a source checkout), display server (X11/Wayland), engine, and a `voculinux --debug` snippet. ## Security @@ -37,4 +34,4 @@ Code and docs: [CONTRIBUTING.md](CONTRIBUTING.md). Community standards: [CODE_OF ## Maintainer contact -General product questions are best on Discussions or Discord so others can find the answer. Security only: see [SECURITY.md](SECURITY.md). +Post general questions as issues so others can find the answer. Security only: see [SECURITY.md](SECURITY.md). diff --git a/docs/DISTRO_COMPATIBILITY.md b/docs/DISTRO_COMPATIBILITY.md index 227714b..6376f45 100644 --- a/docs/DISTRO_COMPATIBILITY.md +++ b/docs/DISTRO_COMPATIBILITY.md @@ -2,11 +2,16 @@ How Voculinux behaves across distributions, what is tested, and what to install manually when needed. -For install steps, prefer [INSTALL.md](INSTALL.md). Flatpak packaging (useful on immutable or non-standard layouts): [packaging/flatpak/README.md](../packaging/flatpak/README.md). Snap Store listing: [snapcraft.io/voculinux](https://snapcraft.io/voculinux) (`--edge`; pack/upload steps in [INSTALL.md](INSTALL.md)). Flatpak is not on Flathub: submission [flathub#9368](https://github.com/flathub/flathub/pull/9368) closed 2026-07-23 on policy grounds; channel tracked in [#167](https://github.com/VocaHQ/vocalinux/issues/167). +**The published package targets Void Linux (glibc, x86_64).** It is the only Voculinux package +this project publishes: a signed xbps repository, registered as described in +[INSTALL.md](INSTALL.md#void-linux-signed-xbps-repo). The distribution tables below describe +source-checkout builds with `install.sh`, for developers. They are not published packages. + +For install steps, prefer [INSTALL.md](INSTALL.md). ## Cross-distro behavior -The installer and launch wrappers handle most path differences. +For source checkouts, the installer and launch wrappers handle most path differences. ### GI_TYPELIB_PATH detection @@ -24,18 +29,19 @@ The installer uses a multi-step approach to detect the correct GI_TYPELIB_PATH: ### Wrapper Scripts -The installer creates wrapper scripts (`~/.local/bin/voculinux` and `~/.local/bin/voculinux-gui`) that: +The source installer creates wrapper scripts (`~/.local/bin/voculinux` and `~/.local/bin/voculinux-gui`) that: - Set the correct `GI_TYPELIB_PATH` environment variable - Handle input group permissions for Wayland keyboard shortcuts - Provide seamless cross-distro compatibility ### Desktop Entry -The `.desktop` entry is automatically configured with the detected `GI_TYPELIB_PATH`, ensuring the application launches correctly from the application menu regardless of distribution. +For source installs, the `.desktop` entry is automatically configured with the detected `GI_TYPELIB_PATH`, ensuring the application launches correctly from the application menu regardless of distribution. -## Officially Supported Distributions +## Officially Supported Distributions (source checkouts) -These distributions are tested and known to work well with Voculinux. A +For source-checkout builds with `install.sh`, these distributions are tested and known to +work well with Voculinux. A derivative is judged by the Python and package repositories it ships rather than by its own version number, which rarely tracks the base release. In particular, `install.sh` does not interpret a Debian-based derivative's product @@ -63,7 +69,7 @@ These distributions may work but have known limitations or are less tested: |--------------|--------|--------------| | Gentoo | ⚠️ Experimental | No package manager support, manual install required. Packages are compiled from source which takes longer. | | Alpine Linux | ⚠️ Experimental | Uses musl libc (not glibc). Some Python packages may not have pre-built wheels and may need to be compiled. | -| Void Linux | ⚠️ Experimental | Untested, manual install required. Uses xbps package manager. | +| Void Linux | ⚠️ Experimental | Source-checkout builds are untested here. The published xbps package is the supported route; see [Void Linux](#void-linux). | | Solus | ⚠️ Experimental | Untested, manual install required. Uses eopkg package manager. | | Mageia | ⚠️ Experimental | Untested, uses dnf/urpmi package managers. | @@ -78,11 +84,11 @@ These distributions are known to be incompatible: ## Requirements by Distribution -These are baseline commands for manual installations. The exact inventory used +These are baseline commands for source-checkout builds. The exact inventory used by `install.sh`, including package alternatives and conditional dependencies, lives in [`scripts/distro-package-map.yaml`](../scripts/distro-package-map.yaml). -For the complete manual setup sequence, including native build prerequisites, -use [INSTALL_MANUAL.md](INSTALL_MANUAL.md#system-packages-by-distribution). +For the complete developer setup sequence, including native build prerequisites, +see [CONTRIBUTING.md](../CONTRIBUTING.md#manual-setup). ### Ubuntu/Debian-based ```bash @@ -121,24 +127,22 @@ sudo systemctl enable --now ydotoold ``` **Scoped source builds.** If you need to force `pywhispercpp` to rebuild from source, use the -package-scoped flag to avoid compiling unrelated deps like NumPy from source (which takes a very -long time and can fail): +installer's flag. It rebuilds the whisper.cpp bindings and leaves the rest of the venv alone, +so unrelated dependencies such as NumPy are not compiled from source: ```bash -source ~/.local/share/voculinux/venv/bin/activate -PYWHISPERCPP_CLEAN=1 pip install --force-reinstall --no-binary=pywhispercpp pywhispercpp -deactivate +./install.sh --auto --rebuild-whispercpp ``` **Verifying libwhisper.so resolution.** If Voculinux starts with `libwhisper.so.1: cannot open shared object file`, check for unresolved symbols: ```bash -ldd $(find ~/.local/share/voculinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found' +ldd $(find venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found' ``` If any libraries are listed, re-run the installer with `--rebuild-whispercpp` or switch to -the VOSK engine (`--engine=vosk`) as a fully-packaged alternative. +the VOSK engine (`--engine=vosk`) as an alternative. ### Fedora/RHEL-based ```bash @@ -192,9 +196,16 @@ sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev \ **Note:** Alpine uses musl libc. Some Python packages may need to be compiled from source. ### Void Linux + +The published Voculinux package for Void is described in +[INSTALL.md](INSTALL.md#void-linux-signed-xbps-repo). This section covers source-checkout +builds on Void, which are experimental. Packages from the `install.sh` inventory: + ```bash -sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libayatana-appindicator \ - gobject-introspection portaudio-devel python3-devel pkg-config +sudo xbps-install -S python3-pip python3-gobject gtk+3 libayatana-appindicator \ + gobject-introspection portaudio-devel cairo-devel python3-devel pkg-config cmake \ + base-devel wget curl unzip shaderc patchelf Vulkan-Tools xclip xsel wl-clipboard \ + xdotool wtype ``` Note: `ydotool` is not packaged for Void, so the ydotool injection @@ -217,154 +228,6 @@ sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \ portaudio-devel python3-devel python3-virtualenv pkg-config ``` -## PyPI, pip, and pipx Installation - -The PyPI package is useful when you want a standard Python package install, or -when you want to manage Voculinux with `pipx`. However, **Voculinux requires -system desktop packages** that cannot be installed by pip or pipx. - -Use the official installer when possible. It installs the required system -packages, creates the virtual environment, installs Voculinux, sets up desktop -integration, and downloads the default speech model: - -```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh -``` - -### Important: Install System Packages First - -Before running `pip install voculinux`, `pip install "voculinux[vosk]"`, or -`pipx install voculinux`, you **must** install the required system packages: - -#### Ubuntu/Debian -```bash -sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ibus-1.0 gir1.2-ayatanaappindicator3-0.1 \ - libgirepository1.0-dev libcairo2-dev portaudio19-dev python3-dev \ - python3-venv pkg-config xdotool wtype wl-clipboard xclip xsel -``` - -On Ubuntu 24.04+ or Pop!_OS, install `libgirepository-2.0-dev` if -`libgirepository1.0-dev` is not available. - -#### Fedora -```bash -sudo dnf install python3-gobject gtk3 gtk3-devel ibus-devel cairo-devel libayatana-appindicator-gtk3 \ - gobject-introspection-devel portaudio-devel python3-devel \ - python3-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel -``` - -#### Arch Linux -```bash -sudo pacman -S python-gobject gtk3 ibus libayatana-appindicator gobject-introspection \ - python-cairo portaudio python-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel -``` - -#### openSUSE -```bash -PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")') - -sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 ibus typelib-1_0-IBus-1_0 \ - gcc gcc-c++ make patchelf \ - typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \ - typelib-1_0-Notify-0_7 libnotify4 \ - portaudio-devel "${PYVER}-devel" "${PYVER}-virtualenv" pkg-config xdotool wtype wl-clipboard xclip xsel -``` - -### pip Installation Steps - -1. **Install system packages** (see above for your distribution) - -2. **Create a virtual environment with system site-packages enabled**: - ```bash - python3 -m venv ~/.local/share/voculinux-pypi/venv --system-site-packages - source ~/.local/share/voculinux-pypi/venv/bin/activate - pip install --upgrade pip setuptools wheel - ``` - - `--system-site-packages` lets the venv use distro-provided GTK bindings such - as `python3-gi`, which are often more reliable than building PyGObject from - source in a venv. - -3. **Install Voculinux from PyPI**: - ```bash - pip install voculinux - # vosk engine: pip install "voculinux[vosk]" - ``` - -4. **Run Voculinux**: - ```bash - voculinux - ``` - -### pipx Installation Steps - -1. **Install system packages** (see above for your distribution) - -2. **Install pipx** (if not already installed): - ```bash - # Ubuntu/Debian - sudo apt install pipx - pipx ensurepath - - # Fedora - sudo dnf install pipx - pipx ensurepath - - # Arch Linux - sudo pacman -S pipx - pipx ensurepath - ``` - -3. **Install Voculinux**: - ```bash - pipx install voculinux - # vosk engine: pipx install "voculinux[vosk]" - ``` - -4. **Run Voculinux**: - ```bash - voculinux - ``` - -### Why System Packages Are Required - -Voculinux uses GTK3 for its GUI, AppIndicator/Ayatana for the system tray icon, -PortAudio for microphone capture, and tools such as `xdotool`, `wtype`, and clipboard utilities (`wl-clipboard`, `xclip`, `xsel`) for -text injection and layout-independent Wayland paste fallback. These are system libraries and desktop tools that must be -installed with your distribution's package manager. Python packages from PyPI -can provide Python bindings, but they do not provide the underlying GTK -typelibs, tray support, audio development libraries, or text injection binaries. - -### Troubleshooting pip/pipx Installation - -If `voculinux` fails to start: - -1. **Check for missing system packages** - The error message will indicate which packages are missing -2. **Verify GI_TYPELIB_PATH** - In rare cases, you may need to set this environment variable: - ```bash - export GI_TYPELIB_PATH=/usr/lib/x86_64-linux-gnu/girepository-1.0 - voculinux - ``` -3. **Check package metadata** - Run `pip show voculinux` or - `pipx runpip voculinux show voculinux` to confirm which version was installed. -4. **Check Python dependencies** - Run `pip check` inside the venv, or - `pipx runpip voculinux check` for pipx. - -If Voculinux reports that a speech recognition model is missing, open Settings -and download a model, or use the official installer to download the default model -during setup. - -### Recommended Alternative - -For the best experience with automatic dependency handling, use the official installer: -```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh -``` - -This installer automatically detects your distribution and installs all required system packages. - ## Text Injection Tools Voculinux requires text injection tools to work with X11 or Wayland: @@ -380,7 +243,8 @@ Voculinux requires text injection tools to work with X11 or Wayland: ### Installation by Distribution ```bash -# Ubuntu/Debian/Fedora/Arch/openSUSE +# Void/Ubuntu/Debian/Fedora/Arch/openSUSE +sudo xbps-install -S xdotool wtype wl-clipboard xclip xsel # Void sudo apt install xdotool wtype wl-clipboard xclip xsel # Ubuntu/Debian sudo dnf install xdotool wtype wl-clipboard xclip xsel # Fedora sudo pacman -S xdotool wtype wl-clipboard xclip xsel # Arch @@ -425,12 +289,8 @@ For unsupported or experimental distributions: ./install.sh --skip-system-deps ``` -4. **Or install from source in a virtual environment:** - ```bash - python3 -m venv venv - source venv/bin/activate - pip install -e .[whisper] - ``` +4. **Or set up a development checkout** with `./install.sh --dev`, as described in + [CONTRIBUTING.md](../CONTRIBUTING.md#development-setup). ## Desktop Environment Compatibility @@ -561,8 +421,7 @@ If you successfully get Voculinux working on an unsupported or experimental dist ## See also - [Installation guide](INSTALL.md) -- [Manual / PyPI install](INSTALL_MANUAL.md) - [Troubleshooting](TROUBLESHOOTING.md) - [User guide](USER_GUIDE.md) - [Update guide](UPDATE.md) -- [GitHub issue tracker](https://github.com/VocaHQ/vocalinux/issues) +- [Open issues](https://git.bongbetic.com/xavierk/voculinux/issues) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 2ce4ded..908b57f 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,248 +1,92 @@ # Installation guide -How to install Voculinux on Linux. Short overview: [project README](../README.md). +How to install Voculinux. Short overview: [project README](../README.md). + +Voculinux is published only as a signed Void Linux xbps repository (glibc, x86_64). +Other install channels are not published for it. Source checkouts are a developer path. | Path | When to use | |------|-------------| -| [Recommended installer](#recommended-installer) | Most users | -| [AppImage](#appimage) | Portable binary; no system package install | -| [Distro packages (.deb / .rpm)](#distro-packages-deb--rpm) | Debian 12+, Ubuntu 24.04+, Fedora | -| [AUR](#arch-linux-aur) | Arch / Manjaro | -| [Flatpak](#flatpak) | Release `.flatpak` or local build | -| [Snap](#snap-ubuntu-snap-store) | Ubuntu Snap Store (`--edge`) or GitHub `.snap` | -| [Nix](#nix--nixos) | Flake package, Home Manager, or the NixOS module | -| [From source](#from-source) | Contributors or custom trees | -| [Manual / PyPI](INSTALL_MANUAL.md) | Full control or pip-only workflows | +| [Void package](#install) | Void Linux, glibc, x86_64: the published install | +| [Source checkout](#from-a-source-checkout-developers) | Contributors and developers | +| [Update](#update) | Upgrading an existing install | | [Troubleshooting](TROUBLESHOOTING.md) | Tray, audio, injection, models | -## Recommended installer +## Install -Download, review if you like, then run: +### Void Linux (signed xbps repo) -```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +Void Linux **glibc `x86_64` only**. Each version tag publishes a signed +personal xbps repository to the project's rolling `latest` release: +binary packages (`*.x86_64.xbps`) with their signatures, the signed +repository metadata (`x86_64-repodata`), and the client key +(`FINGERPRINT` plus the fingerprint-named `.plist`). The registration URL +below always serves the newest release. + +This is a **third-party repository** — it is published by this project, +not by upstream Void Linux, and its packages are built from the +templates in `packaging/void/srcpkgs/`. Details: [packaging/void/README.md](../packaging/void/README.md). + +Repository key, RSA 4096. Pin this fingerprint: + +```text +fa:d1:00:32:ce:b1:b9:fd:73:05:05:76:75:54:37:25 ``` -Installs the latest release with **whisper.cpp** by default. For a pinned version, see [GitHub Releases](https://github.com/VocaHQ/vocalinux/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 - ```bash -./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 +# as root on the Void system: trust the key, register the repository, install +curl -fsSL -o '/var/db/xbps/keys/fa:d1:00:32:ce:b1:b9:fd:73:05:05:76:75:54:37:25.plist' \ + https://git.bongbetic.com/xavierk/voculinux/raw/branch/main/packaging/void/repository-key.plist +echo 'repository=https://git.bongbetic.com/xavierk/voculinux/releases/download/latest' > /etc/xbps.d/voculinux.conf +xbps-install -S voculinux ``` -| 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 | +The key file is named by its fingerprint, so xbps finds it on the first +sync and asks nothing. If xbps still shows a fingerprint prompt, answer +`N` unless it reads exactly the fingerprint above (it must also match the +`FINGERPRINT` file attached to the release). Do not add `-y` to the first +sync: it would accept an unknown key without asking. -Useful flags: `--tag=TAG`, `--skip-models`, `--rebuild-whispercpp`, `--no-rebuild-whispercpp`, `--venv-dir=PATH`, `--test`. +### Speech engines -`--engine=NAME` accepts `whisper_cpp` (default), `whisper`, `faster_whisper`, `vosk`, `parakeet`, `remote_api`. +| Engine | When to use | +|--------|-------------| +| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA | +| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA | +| **Faster Whisper** | CPU-friendly Whisper via CTranslate2 / INT8 | +| **VOSK** | Low RAM / minimal footprint | +| **Parakeet** | CPU; NVIDIA NeMo ASR via sherpa-onnx; 25 European languages | +| **Remote API** | Offload to a server you configure | -### What the installer does +The xbps package does not include the optional engines (Faster Whisper, Whisper, +VOSK, Parakeet) or the Silero VAD runtime (`onnxruntime`). Add them from your own +Python environment, as the package's install message describes. Models download +on first run. -1. Detects the distribution and installs system packages -2. Creates a Python venv from the system interpreter with `--system-site-packages` (for distro GTK / PyGObject) -3. Installs Voculinux and the chosen speech engine -4. Optionally installs neural VAD (`onnxruntime`) -5. Downloads a default speech model (checksum-verified) -6. Installs icons, desktop entry, and `~/.local/bin` wrappers - -## AppImage - -From [GitHub Releases](https://github.com/VocaHQ/vocalinux/releases): +### After installation ```bash -chmod +x Voculinux-*-x86_64.AppImage # or aarch64 -./Voculinux-*-x86_64.AppImage +voculinux # from the xbps package, on your PATH ``` -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. +You can also launch Voculinux from your application menu. -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. +### Wayland hotkeys need the input group -## Distro packages (.deb / .rpm) - -From [GitHub Releases](https://github.com/VocaHQ/vocalinux/releases), pick the file matching your distro and CPU: - -```bash -# Debian / Ubuntu (amd64; arm64 files are attached too) -sudo apt install ./voculinux_*_amd64.deb - -# Fedora (x86_64; aarch64 files are attached too) -sudo dnf install ./voculinux-*.x86_64.rpm -``` - -These are thin packages: Python, GTK, PyGObject and the AppIndicator typelib come from the distribution, and `apt`/`dnf` resolves them. `xdotool`, `wtype`, `ydotool`, the clipboard tools and IBus are `Recommends`, matching the optional feature set of the other paths. Only `pywhispercpp` and `pynput` are vendored inside the package — `pywhispercpp` is packaged by neither distro and `pynput` is missing on Fedora. They land under `/usr/lib/voculinux/vendor`, on `sys.path` via the `voculinux` launcher. - -The `.deb` needs a distro that ships Python 3.11+: Debian 12+ and Ubuntu 24.04+ (Ubuntu 22.04 ships 3.10). whisper.cpp runs on CPU in these packages — the PyPI wheel, not the Vulkan build the AppImage carries. There is no auto-update: a new release is a new package install. A PPA and a COPR are not published yet. - -On Wayland, the default Right Alt shortcut reads keyboard devices through evdev, so your user needs `input` group membership or the hotkey is silently disabled: +On Wayland, the default Right Alt shortcut reads keyboard devices through evdev. Your user +needs `input` group membership, or the evdev hotkey backend cannot open `/dev/input` devices: ```bash sudo usermod -aG input $USER # then log out and back in ``` -Joining `input` grants read access to every keyboard and pointer device — X11 needs none of this. The launcher re-execs through `sg input` when `/etc/group` already lists the membership but the current session has not picked it up, so an `usermod` between package install and next login applies without a reboot. The source installer does this step for you; the packages cannot. +Joining `input` gives read access to every keyboard and pointer device. X11 does not need +this step. The package does not add the group for you; its install message says the same. -## Arch Linux (AUR) +### Audio capture -```bash -yay -S voculinux -``` - -See [AUR.md](AUR.md). - -## Flatpak - -Install and auto-update via the self-hosted VocaHQ remote (`flatpak update` picks up each release): - -```bash -flatpak install https://vocahq.github.io/voculinux-flatpak/com.voculinux.Voculinux.flatpakref -``` - -The `.flatpakref` adds the `vocahq` remote and resolves the GNOME runtime through Flathub. Manually instead: - -```bash -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/voculinux-flatpak/vocahq.flatpakrepo -flatpak install vocahq com.voculinux.Voculinux -``` - -Or sideload a GitHub Release bundle (`Voculinux--x86_64.flatpak` or `-aarch64.flatpak`) after the Flathub GNOME runtime is present — bundles do not auto-update: - -```bash -flatpak install --user ./Voculinux--x86_64.flatpak -``` - -Local build (contributors): - -```bash -flatpak install flathub org.gnome.Platform//50 org.gnome.Sdk//50 -flatpak-builder --user --install --force-clean build-dir \ - packaging/flatpak/com.voculinux.Voculinux.yml -flatpak run com.voculinux.Voculinux -``` - -Whisper.cpp + Vulkan. It is **not on Flathub** (submission [flathub#9368](https://github.com/flathub/flathub/pull/9368) closed 2026-07-23 on policy grounds). Details: [packaging/flatpak/README.md](../packaging/flatpak/README.md). - -On native X11, hotkeys work without device access (GNOME X11 is the exception: -its X server hides physical keys from the X11 listener, so it also needs -`/dev/input`). On Wayland, the built-in hotkey needs `/dev/input` (`--device=input` on Flatpak 1.15.6 or newer, or -`--device=all` on older versions); otherwise enable External Activation and -bind a desktop shortcut to the D-Bus `Toggle` command in -[Running without device access](../packaging/flatpak/README.md#running-without-device-access). -Desktop shortcuts only toggle dictation, so they cannot support push-to-talk. - -## Snap (Ubuntu Snap Store) - -Listing: [snapcraft.io/voculinux](https://snapcraft.io/voculinux) (issue [#48](https://github.com/VocaHQ/vocalinux/issues/48)). Recipe: `snap/snapcraft.yaml`. Tagged `v*` releases attach `voculinux__amd64.snap` to the GitHub Release and try Snap Store `edge` and `candidate` when credentials are set. `stable` is promoted from `candidate` after QA. - -Build inputs, the PR/release artifact gate, and its verification limits are -documented in [SNAP.md](SNAP.md). - -Store install, once Canonical lists the revision: - -```bash -sudo snap install voculinux --edge -sudo snap connect voculinux:audio-record # if mic is not auto-connected -sudo snap connect voculinux:raw-input # global keyboard shortcuts (evdev) -sudo snap connect voculinux:hardware-observe # list keyboards (/proc/bus/input/devices) -``` - -Native Wayland typing uses the RemoteDesktop portal: the compositor asks once on first dictation, nothing to connect. The recipe ships **no `uinput` plug** and no ydotool; the Store denied the super-privileged grant ([the request thread](https://forum.snapcraft.io/t/53528)), which held the 0.17.0+ revisions and left **v0.16.2 (rev 7)** on edge. On KDE Plasma, KWin's portal can mistype letter case ([KDE bug 489021](https://bugs.kde.org/show_bug.cgi?id=489021)); set Virtual Keyboard to "IBus Wayland" so dictation types correctly. - -Under strict confinement the snap reaches audio through the PulseAudio/PipeWire server, not the sound card, so Settings → Audio lists the server's microphones (via `pactl`) and records from the one you pick. whisper.cpp in the snap is built without a GPU backend and runs on the CPU, and host tools such as `nvidia-smi` and `vulkaninfo` are not visible inside it. For Vulkan acceleration use the [AppImage](#appimage) or the [installer](#recommended-installer) instead. - -GitHub `.snap` files through v0.18.2 declare `uinput`, so KDE users who want ydotool can sideload that build and connect the plug manually: - -```bash -sudo snap install --dangerous ./voculinux_0.18.2_amd64.snap -sudo snap connect voculinux:audio-record -sudo snap connect voculinux:raw-input -sudo snap connect voculinux:hardware-observe -sudo snap connect voculinux:uinput # only in the v0.18.x sideload; the recipe no longer ships it -``` - -`--dangerous` is required because this file is not a Store revision and will not refresh from the Store; once the Store carries a newer revision, `sudo snap install voculinux --edge` (or `snap refresh`) replaces it. - -## Nix / NixOS - -The repo is a flake: GTK, PyGObject and the AppIndicator typelib come from nixpkgs, and `pywhispercpp` (absent from nixpkgs, same gap as Debian and Fedora) is built from its vendored PyPI sdist. The wrapped binary carries every injector and clipboard tool on PATH. - -```bash -nix run github:VocaHQ/vocalinux # try it -nix profile install github:VocaHQ/vocalinux -``` - -On NixOS, `voculinux.nixosModules.voculinux` provides `programs.voculinux.enable`, which installs the package and enables `hardware.uinput`. Add each dictating user to `input` and `uinput` for Wayland shortcuts and ydotool typing. Home Manager users get `voculinux.homeManagerModules.voculinux` with the same `programs.voculinux` options — device permissions stay on the system side. Usage snippets and scope notes: [packaging/nix/README.md](../packaging/nix/README.md). - -## From source - -```bash -git clone https://github.com/VocaHQ/vocalinux.git -cd voculinux -./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 Voculinux 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](DISTRO_COMPATIBILITY.md). - -### GPU (optional) - -whisper.cpp uses Vulkan when available (AMD, Intel, NVIDIA). Check with `vulkaninfo --summary`. - -## Running Voculinux - -```bash -voculinux # if ~/.local/bin is on PATH -~/.local/share/voculinux/venv/bin/voculinux # direct -source venv/bin/activate && voculinux # source checkout -``` - -Or launch from the application menu. +The package captures audio through PipeWire (`pw-record`, `pw-dump`) and PortAudio. +PipeWire must be running in your session. ### CLI @@ -262,22 +106,67 @@ voculinux --wayland voculinux --start-minimized ``` -## Autostart +The optional engines (`whisper`, `vosk`, `parakeet`) need their Python packages in your own +environment first; see [Speech engines](#speech-engines). -**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. +### 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. + +## From a source checkout (developers) + +Source checkouts are for development. For the two-venv layout and the dev workflow, see +[CONTRIBUTING.md](../CONTRIBUTING.md). + +```bash +git clone https://git.bongbetic.com/xavierk/voculinux.git +cd voculinux +./install.sh --dev +source venv/bin/activate +voculinux +``` + +`./install.sh --help` lists the installer flags. The installer needs Python 3.11+ and the +distribution's PyGObject. Distribution notes: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md). + +## Requirements + +| | | +|--|--| +| **OS** | Void Linux (glibc, x86_64) for the published package. Source checkouts: see [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md) | +| **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 Void package depends on Void's own Python, PyGObject and GTK 3 packages. A source +checkout needs Python 3.11+ with PyGObject from the system (`python3-gobject` on Void). +Ubuntu 22.04 (Python 3.10) and Debian 11 (Python 3.9) are below that floor. + +### GPU (optional) + +whisper.cpp uses Vulkan when available (AMD, Intel, NVIDIA). The Void build enables Vulkan +by default. Check the driver with `vulkaninfo --summary`. ## Data locations (XDG) -| Directory | Purpose | -|-----------|---------| +| Path | Purpose | +|------|---------| | `~/.config/voculinux/` | Configuration | -| `~/.local/share/voculinux/` | Data and speech models | -| `~/.local/share/applications/` | Desktop entry | -| `~/.local/share/icons/hicolor/scalable/apps/` | Icons | +| `~/.local/share/voculinux/` | Data and speech models (downloaded on first use) | +| `~/.config/autostart/` | Start on Login entry | +| `/usr/share/applications/voculinux.desktop` | Desktop entry, installed by the package | +| `/usr/share/icons/hicolor/scalable/apps/` | Icons, installed by the package | + +Source installs put the desktop entry and icons under `~/.local/share/applications/` and +`~/.local/share/icons/hicolor/scalable/apps/` instead. ## whisper.cpp (default engine) -Default engine: C++ Whisper port with Vulkan GPU support and lower install cost than the PyTorch Whisper stack. +Default engine: C++ Whisper port with Vulkan GPU support and lower install cost than the +PyTorch Whisper stack. | Size | Approx. | Use | |------|---------|-----| @@ -287,20 +176,32 @@ Default engine: C++ Whisper port with Vulkan GPU support and lower install cost | 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](USER_GUIDE.md). +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](USER_GUIDE.md). -Reuse an existing `pywhispercpp` build: - -```bash -./install.sh --auto # reuse if present -./install.sh --auto --rebuild-whispercpp # force rebuild -``` - -Switch engines in Settings → Speech Model (Advanced), or edit `~/.config/voculinux/config.json` (`engine`: `whisper_cpp` | `whisper` | `vosk` | `parakeet` | `remote_api`). +Switch engines in Settings → Speech Model (Advanced), or edit `~/.config/voculinux/config.json` +(`engine`: `whisper_cpp` | `whisper` | `vosk` | `parakeet` | `remote_api`). ## Uninstall -From a source checkout, `./uninstall.sh` removes the install and that checkout's `venv/`, `build/`, `dist/`, and Python bytecode. `--keep-config` and `--keep-data` leave `~/.config/voculinux` and `~/.local/share/voculinux` in place. +Remove the Void package: + +```bash +sudo xbps-remove voculinux +``` + +This removes the package files only. Your configuration, downloaded models and autostart +entry live in your home directory and stay until you delete them: + +```bash +rm -rf ~/.config/voculinux ~/.local/share/voculinux +rm -f ~/.config/autostart/voculinux.desktop +``` + +From a source checkout, `./uninstall.sh` removes the install and that checkout's `venv/`, +`build/`, `dist/`, and Python bytecode. `--keep-config` and `--keep-data` leave +`~/.config/voculinux` and `~/.local/share/voculinux` in place. ```bash ./uninstall.sh @@ -308,41 +209,20 @@ From a source checkout, `./uninstall.sh` removes the install and that checkout's ./uninstall.sh --keep-data ``` -The website command downloads this same script and runs it: - -```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/uninstall.sh -o /tmp/vul.sh -bash /tmp/vul.sh -``` - -That removes Voculinux from your home directory (config, data, launchers, desktop entry, icons). It does not delete `venv/`, `build/`, `dist/`, or `.pyc` files in the directory where you ran it. - -From the source checkout, the equivalent by hand: - -```bash -rm -rf venv ~/.config/voculinux ~/.local/share/voculinux -rm -f activate-voculinux.sh -rm -f ~/.local/share/applications/voculinux.desktop -rm -f ~/.local/share/icons/hicolor/scalable/apps/voculinux*.svg -gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor -``` - ## Update -See [UPDATE.md](UPDATE.md). +Packaged installs update through xbps. See [UPDATE.md](UPDATE.md). ```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +sudo xbps-install -Su voculinux ``` ## More documentation | Doc | Contents | |-----|----------| -| [INSTALL_MANUAL.md](INSTALL_MANUAL.md) | Manual install, PyPI/pipx, per-distro packages | | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common failures and fixes | -| [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md) | Support matrix | +| [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md) | Support matrix and source-checkout notes | | [USER_GUIDE.md](USER_GUIDE.md) | Day-to-day use | | [SUPPORT.md](../SUPPORT.md) | Where to get help | | [Documentation index](README.md) | Full list | diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 5b336c3..6fd3dd9 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1,6 +1,7 @@ # Troubleshooting -Common install and runtime problems. Install overview: [INSTALL.md](INSTALL.md). Support channels: [SUPPORT.md](../SUPPORT.md). +Common install and runtime problems. Install overview: [INSTALL.md](INSTALL.md). Support +channels: [SUPPORT.md](../SUPPORT.md). Always try once with debug logs: @@ -10,15 +11,19 @@ voculinux --debug ## Command not found: `voculinux` +Void package: the package puts `voculinux` on your PATH. Check the install: + ```bash -# Official install wrappers -export PATH="$HOME/.local/bin:$PATH" -voculinux +command -v voculinux # should print a path under /usr/bin +xbps-query voculinux # shows the installed package and its version +``` -# Or run the venv binary -~/.local/share/voculinux/venv/bin/voculinux +If the package is missing, install it with `sudo xbps-install -S voculinux` (see +[INSTALL.md](INSTALL.md#install)). -# Source checkout +Source checkout: + +```bash source venv/bin/activate voculinux ``` @@ -26,10 +31,12 @@ voculinux ## No audio / microphone not working 1. Check system sound settings and mute state -2. List capture devices: `arecord -l` -3. Run `voculinux --debug` and confirm the selected device -4. Reset a bad device index: set `audio.device_index` to `null` in `~/.config/voculinux/config.json` -5. Bluetooth mics: try a wired device to isolate SCO capture issues +2. Confirm PipeWire is running in your session. The package captures through PipeWire + (`pw-record`, `pw-dump`), and `pactl list short sources` should list your microphone +3. List ALSA capture devices: `arecord -l` +4. Run `voculinux --debug` and confirm the selected device +5. Reset a bad device index: set `audio.device_index` to `null` in `~/.config/voculinux/config.json` +6. Bluetooth mics: try a wired device to isolate SCO capture issues ### Microphone Stalled @@ -42,39 +49,36 @@ dictation. **Test Dictation** is a separate speech-recognition test. See [Audio input](USER_GUIDE.md#audio-input) for explicit microphone selection and **System Default** behavior. -## GTK / AppIndicator / `No module named gi` +## Tray icon missing / `No module named gi` -Recreate the venv with system site packages: +Void package: the package depends on `python3-gobject`, `gtk+3` and +`libayatana-appindicator`. Update the package, which also pulls in any missing dependency: ```bash -sudo apt install python3-gi python3-gi-cairo # Debian/Ubuntu example -# tray: gir1.2-ayatanaappindicator3-0.1 or gir1.2-appindicator3-0.1 - -deactivate 2>/dev/null || true -rm -rf venv -/usr/bin/python3 -m venv venv --system-site-packages -source venv/bin/activate -pip install -e . +sudo xbps-install -Su voculinux ``` -On GNOME, enable the AppIndicator extension if the tray icon never appears: +Source checkout: the venv must see the system PyGObject. Rebuild it with the installer: ```bash -# Debian/Ubuntu -sudo apt install gnome-shell-extension-appindicator -# Fedora -sudo dnf install gnome-shell-extension-appindicator -# Arch -sudo pacman -S gnome-shell-extension-appindicator +deactivate 2>/dev/null || true +rm -rf venv +./install.sh --dev +``` +On GNOME, the tray icon needs an AppIndicator (StatusNotifier) extension. If the icon +never appears, install an AppIndicator extension from your distribution, then enable it: + +```bash gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com # log out/in if needed ``` -Refresh icons: +Refresh icons. The package installs them under `/usr/share/icons/hicolor`; a source install +uses `~/.local/share/icons/hicolor`: ```bash -gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor +sudo gtk-update-icon-cache -f -t /usr/share/icons/hicolor voculinux --debug ``` @@ -83,36 +87,39 @@ voculinux --debug **X11:** ```bash -sudo apt install xdotool # or distro equivalent xdotool type "hello" ``` **Wayland:** ```bash -sudo apt install wtype wl-clipboard xclip xsel wtype "hello" -printf "bonjour" | xsel --clipboard --input +printf "bonjour" | wl-copy ``` -**KDE Plasma Wayland:** `wtype` may fail if the compositor does not expose a virtual keyboard to normal clients. Prefer **System Settings → Keyboard → Virtual Keyboard → IBus Wayland**, then restart Voculinux (or log out/in). +Clipboard paste uses `wl-clipboard`, `xclip` or `xsel`, whichever matches your session. -Install IBus if needed: +**Wayland hotkeys do nothing:** your user is not in the `input` group. See +[Wayland hotkeys need the input group](INSTALL.md#wayland-hotkeys-need-the-input-group). + +**KDE Plasma Wayland:** `wtype` may fail if the compositor does not expose a virtual keyboard +to normal clients. Prefer **System Settings → Keyboard → Virtual Keyboard → IBus Wayland**, +then restart Voculinux (or log out/in). The package does not depend on IBus, so install it +first: ```bash -# Ubuntu/Debian -sudo apt install ibus -# Fedora -sudo dnf install ibus -# Arch -sudo pacman -S ibus +sudo xbps-install -S ibus ``` Compositor-specific notes: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md). ## Model download fails -Models download on first use. Manual VOSK example: +Models download on first use. whisper.cpp models are managed from Settings or the +first-run download. + +VOSK is optional and is not in the package. If you install it in your own Python +environment, you can also place a model by hand. Example: ```bash mkdir -p ~/.local/share/voculinux/models @@ -122,19 +129,23 @@ unzip vosk-model-small-en-us-0.15.zip ``` More VOSK models: https://alphacephei.com/vosk/models -whisper.cpp models are managed from Settings or first-run download. ## `libwhisper.so` / pywhispercpp load errors +Void package: the package provides pywhispercpp. Import it directly to see the real error: + ```bash -# Unresolved libs -ldd $(find ~/.local/share/voculinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found' +python3 -c "import pywhispercpp.model" +``` -# Rebuild whisper.cpp bindings via installer +If that fails, update the package (`sudo xbps-install -Su voculinux`) and run +`voculinux --debug` again. + +Source checkout: look for unresolved libraries in the venv's bindings, then rebuild them: + +```bash +ldd $(find venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found' ./install.sh --auto --rebuild-whispercpp - -# Or switch to VOSK temporarily -voculinux --engine vosk ``` ## Old process still running after update @@ -149,27 +160,36 @@ voculinux ## Clean reinstall +Void package. Your configuration and models in your home directory are kept: + ```bash -./uninstall.sh --keep-config --keep-data -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +sudo xbps-remove voculinux +sudo xbps-install -S voculinux ``` -## Distro PyGObject not importable in the venv +Source checkout: -The distro `python3-gi` / `python3-gobject` package is installed, but `venv/` was built by a different Python than the one it targets. Current `install.sh` ignores an activated virtualenv and rebuilds a mismatched `venv/`. Otherwise: +```bash +./uninstall.sh --keep-config --keep-data +./install.sh --dev +``` + +## Source checkout: PyGObject not importable in the venv + +The distribution's PyGObject package is installed, but `venv/` was built by a different +Python than the one it targets. Current `install.sh` ignores an activated virtualenv and +rebuilds a mismatched `venv/`. Otherwise: ```bash deactivate 2>/dev/null || true rm -rf venv -./install.sh +./install.sh --dev ``` -On systems with several system interpreters: `SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh`. +On systems with several system interpreters: `SYSTEM_PYTHON=/usr/bin/python3.12 ./install.sh --dev`. ## Still stuck - [SUPPORT.md](../SUPPORT.md) -- [GitHub Issues](https://github.com/VocaHQ/vocalinux/issues) -- [Discussions](https://github.com/VocaHQ/vocalinux/discussions) -- [Discord](https://discord.gg/t6muquAJbm) +- [Open issues](https://git.bongbetic.com/xavierk/voculinux/issues) +- [Report a bug](https://git.bongbetic.com/xavierk/voculinux/issues/new) diff --git a/docs/UPDATE.md b/docs/UPDATE.md index cf310bc..5cd79fe 100644 --- a/docs/UPDATE.md +++ b/docs/UPDATE.md @@ -4,30 +4,23 @@ How to upgrade an existing install, plus release notes for the current series. ## Quick update -Voculinux checks its own release server, the Gitea repository at `git.bongbetic.com/xavierk/voculinux`, in the background about every six hours (and shortly after startup). Upstream VocaHQ is never queried. When a newer build is on your selected channel, the tray menu gains an **Update Available...** entry and Settings -> About shows a green **New** badge; open that page for release notes and download links. Updates are not installed automatically. Re-run the installer (or your package manager) as below. - -A package-managed install (the Void `voculinux` package) makes no update check at all. Its updates arrive with `sudo xbps-install -Su`, and Settings -> About says so. - -### Official installer +Void package installs (the signed xbps repository registered in [INSTALL.md](INSTALL.md)): ```bash -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +sudo xbps-install -Su voculinux ``` -The installer detects a running instance, updates in place, preserves configuration and models, and pulls new dependencies (including neural VAD when available). +A package-managed install makes no release check of its own, and Settings → About says so. +Updates arrive through xbps only. -On an existing install (a virtual environment plus `~/.config/voculinux/config.json`), the installer reports the saved configuration and defaults to **Upgrade (keep current settings)**: the configured engine stays selected, `config.json` is never rewritten, the virtual environment is reused, downloaded models are kept, and pywhispercpp is rebuilt only when this release pins a new version or GPU support is missing. Pick the interactive or automatic modes instead if you want to reconfigure the install. +Source checkouts (developers) check this project's own release server, the Gitea repository at +`git.bongbetic.com/xavierk/voculinux`, in the background about every six hours and shortly +after startup. When a newer build is on your selected channel, the tray menu gains an +**Update Available...** entry and Settings → About shows a **New** badge; open that page for +release notes and download links. Updates are not installed automatically. Re-run the +installer as below. -For a scripted, non-interactive upgrade: - -```bash -bash /tmp/vl.sh --upgrade -``` - -`--upgrade` on a machine with no existing install falls back to a normal automatic installation. - -### Installed from source +### Source checkout ```bash cd voculinux @@ -44,15 +37,20 @@ git pull origin main ./install.sh ``` -### Other install methods +On an existing install (a virtual environment plus `~/.config/voculinux/config.json`), +`./install.sh` reports the saved configuration and defaults to **Upgrade (keep current +settings)**: the configured engine stays selected, `config.json` is never rewritten, the +virtual environment is reused, downloaded models are kept, and pywhispercpp is rebuilt only +when this release pins a new version or GPU support is missing. Pick the interactive or +automatic modes instead if you want to reconfigure the install. -| Method | Upgrade | -|--------|---------| -| AUR | `yay -S voculinux` (or your AUR helper) | -| AppImage | Download the new file from [Releases](https://github.com/VocaHQ/vocalinux/releases) | -| Snap | Store: `sudo snap refresh voculinux` (`--edge` until stable is promoted). The recipe ships no `uinput` plug (the Store denied the grant); Wayland typing uses the RemoteDesktop portal. The GitHub `voculinux_0.18.2_amd64.snap` still declares `uinput` for KDE users who want ydotool (`sudo snap install --dangerous`, then `sudo snap connect voculinux:uinput`). | -| Flatpak (release bundle) | Install the new `.flatpak` from Releases; bundles do not auto-update | -| PyPI | Reinstall in the same venv after system packages are current | +For a scripted, non-interactive upgrade: + +```bash +./install.sh --upgrade +``` + +`--upgrade` on a machine with no existing install falls back to a normal automatic installation. ### Check your version @@ -64,21 +62,22 @@ python3 -c "import vocalinux; print(vocalinux.version.__version__)" ### Update problems -Clean reinstall (keeps config and models by default): +Clean reinstall (keeps config and models by default). Void package: ```bash -# Source checkout -./uninstall.sh --keep-config --keep-data - -# Curl install (safe to run from any directory) -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/uninstall.sh -o /tmp/vul.sh -bash /tmp/vul.sh --keep-config --keep-data - -curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh -bash /tmp/vl.sh +sudo xbps-remove voculinux +sudo xbps-install -S voculinux ``` -If an old process is stuck, stop via the tray or the PID in the instance lock file (do not use `pkill -f voculinux`; it can kill unrelated processes): +Source checkout: + +```bash +./uninstall.sh --keep-config --keep-data +./install.sh +``` + +If an old process is stuck, stop via the tray or the PID in the instance lock file (do not use +`pkill -f voculinux`; it can kill unrelated processes): ```bash kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/voculinux/instance.lock")" @@ -104,20 +103,16 @@ Missing system packages: see [INSTALL.md](INSTALL.md) or [DISTRO_COMPATIBILITY.m | **Keyboards survive suspend and lock** | The evdev forwarder releases its EVIOCGRAB when forwarding cannot run, so keyboards no longer go dead at the GNOME lock screen after a suspend/resume (#1025; fixes #1021 reported by @iholder101) | | **Dialogs stay on their own workspace** | Dictation Pad, Settings and other standalone windows no longer bind to other windows on Wayland, so opening Settings no longer summons or minimizes the Dictation Pad with it (#1024; fixes #984 reported by @hopsayer) | | **Ctrl+mouse-wheel zoom works** | Ctrl key events pass through for applications again, so holding Ctrl and scrolling zooms in Firefox and elsewhere even with a double-tap Ctrl shortcut configured (#967 by @loject; fixes #950 reported by @loject) | -| **Upgrade mode in the installer** | `install.sh` on an existing install offers and defaults to an upgrade that keeps your configuration and models, and `bash /tmp/vl.sh --upgrade` runs it non-interactively (#1026; fixes #1009 reported by @plaffitt) | +| **Upgrade mode in the installer** | `./install.sh` on an existing install offers and defaults to an upgrade that keeps your configuration and models, and `./install.sh --upgrade` runs it non-interactively (#1026; fixes #1009 reported by @plaffitt) | ### Also in v0.18.5 - Paste-injection copies are marked sensitive (`wl-copy --sensitive`) on wl-clipboard 2.2+, so clipboard managers that honor the hint, such as Klipper or cliphist, keep dictated text out of their history; the xclip/xsel path and older wl-copy have no such hint (#956 by @Nosion) -- AUR source publication is gated on attested release sdists: the recipe is prepared only from the canonical sdist whose checksum and build provenance verify against this repository's release workflow (#1020 by @sesav) - The tray prefers libayatana-appindicator-glib when it is available (#1019; fixes #1013 reported by @jo-so) -- The Snap package lists PulseAudio microphones and explains that its whisper.cpp build is CPU-only (#1018; fixes #1011 reported by @cmcclung-ANGENG) - The Wayland fallback overlay stays alive when the dock closes it, covering the leftover case from 0.18.4 (#1017; fixes #1010 reported by @lavoie005) -- uv pins are aligned across CI and the release workflows (#1016 by @sesav), release build tooling is pinned with a reproducible-wheel gate (#945 by @sesav), the supported uv range is widened with Fedora/AppImage build hardening (#952 by @sesav), and Dependabot bumps cover pip and GitHub Actions plus flagged vulnerable dependencies (#1014, #1015, #1008 by @Mr-Sunglasses) +- uv pins are aligned across CI and the release workflows (#1016 by @sesav), release build tooling is pinned with a reproducible-wheel gate (#945 by @sesav), the supported uv range is widened with Fedora build hardening (#952 by @sesav), and Dependabot bumps cover pip and GitHub Actions plus flagged vulnerable dependencies (#1014, #1015, #1008 by @Mr-Sunglasses) -AppImage, Flatpak, and Snap still ship whisper.cpp only. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.5). +See the [full changelog](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.18.5). --- @@ -139,8 +134,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. ### Also in v0.18.4 - Keyboards whose evdev node also reports pointer axes, such as the Logitech K860, are monitored again without being grabbed, so `right_alt` and other hotkeys fire (#978 by @ikarius; fixes #953 reported by @dherdt) -- The Flatpak bundles onnxruntime, so Silero VAD works there instead of falling back to amplitude VAD (#1002; fixes #969 reported by @samodadela) -- The Flatpak uses the X11 hotkey listener on native X11 sessions, so it no longer needs `--device=all` there (#997; fixes #971 reported by @samodadela) - RemoteDesktop portal requests each get a unique handle token, which fixes the missing GNOME consent dialog and the 15 second timeout (#996; fixes #993 reported by @hal2100) - XWayland apps that are not connected to IBus, such as SoftMaker TextMaker, receive text through xdotool (#1003; fixes #972 reported by @kdseattlewa) - On GNOME Wayland the dictation overlay is mapped at startup, so the first recording no longer steals focus from the app you are typing into (#998; fixes #992 reported by @lavoie005) @@ -148,15 +141,11 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. - Update checks follow the build channel, so stable installs only hear about stable releases, and Settings can turn them off (#999; fixes #977 reported by @hopsayer) - Faster Settings, typing and dictation, plus mypy as a CI gate (#968) -AppImage, Flatpak, and Snap still ship whisper.cpp only. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.4). - --- ## What's New in v0.18.3 -0.18.3 is a **patch** on the stable line. Default engine is still whisper.cpp. This one is all fixes: "new line" and "new paragraph" finally insert real line breaks, hotkeys come back on GNOME Shell X11, packaged builds stop crashing on older CPUs, and the Snap package can publish again now that the denied `uinput` plug is gone. +0.18.3 is a **patch** on the stable line. Default engine is still whisper.cpp. This one is all fixes: "new line" and "new paragraph" finally insert real line breaks, hotkeys come back on GNOME Shell X11, and release builds stop crashing on older CPUs. ### 0.18.3 highlights @@ -165,51 +154,36 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. | **Real line breaks** | "new line" and "new paragraph" insert an actual newline standalone or mid-utterance, and the stray punctuation they used to leave behind is gone (#958, #962; fixes #955 reported by @rastarr) | | **GNOME X11 hotkeys** | Push-to-talk and toggle shortcuts work on gnome-shell X11 sessions again; the app now prefers the evdev backend there (#963; fixes #954 reported by @jepst) | | **Layout restore on quit** | Quitting no longer collapses a multi-layout keyboard map (us,de staying us,de) because the IBus engine restore is skipped when a real engine is already active (#963) | -| **Older CPUs unblocked** | Snap, Flatpak, AppImage and the .deb/.rpm builds now compile the bundled pywhispercpp at the true x86-64 baseline, ending the SIGILL crash on pre-Haswell processors (#959; fixes #957 reported by @bucketsofmail) | -| **Snap can publish** | The `uinput` plug the Snap Store denied is removed, so new revisions clear automatic review again; Wayland typing uses the RemoteDesktop portal (#960) | +| **Older CPUs unblocked** | Release builds now compile the bundled pywhispercpp at the true x86-64 baseline, ending the SIGILL crash on pre-Haswell processors (#959; fixes #957 reported by @bucketsofmail) | ### Also in v0.18.3 -- The Flatpak remote publish warns on the release run when its secrets are not configured, instead of skipping silently for tags (#961; fixes #951 reported by @andreacasini) -- README gains a badge row for every install format plus a Nix flake section (#949) - Transcribe File's modal model-download dialog now closes itself once TinyDiarize lands, releasing its grab so the transcript's Copy and Save As buttons are clickable (#965; found during release e2e testing) -AppImage, Flatpak, and Snap still ship whisper.cpp only. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.3). - --- ## What's New in v0.18.2 -0.18.2 is a **patch** on the stable line. Default engine is still whisper.cpp. The headline is a livelier dictation overlay plus a round of fixes: the overlay orb now reacts to live microphone level, Nix users get a flake package with NixOS and Home Manager modules and Vulkan GPU inference, and the dictation shortcut can no longer strand a key when you are typing while the app starts. +0.18.2 is a **patch** on the stable line. Default engine is still whisper.cpp. The headline is a livelier dictation overlay plus a round of fixes: the overlay orb now reacts to live microphone level, and the dictation shortcut can no longer strand a key when you are typing while the app starts. ### 0.18.2 highlights | Feature | Description | |---------|-------------| | **Live mic orb** | Dictation overlay orb pulses and ripples with your real audio level instead of sitting static (#940) | -| **Nix packaging** | Flake package plus NixOS and Home Manager modules (#936), and Vulkan GPU inference for pywhispercpp on Nix (#942) | | **Safer startup grab** | A keyboard with a held key or queued key events is left ungrabbed at startup, so typing during launch cannot stick a key on the desktop (#941) | -| **Older CPU fix** | Bundled pywhispercpp builds no longer use -march=native, so AppImage and Flatpak stop crashing on CPUs without the build host's instruction set (#939) | -| **Piped installer** | `curl \| bash` keeps the script on stdin and prompts via /dev/tty, so interactive prompts work mid-pipe (#935) | +| **Older CPU fix** | Bundled pywhispercpp builds no longer use -march=native, so release builds stop crashing on CPUs without the build host's instruction set (#939) | ### Also in v0.18.2 - Installer package map covers cairo headers on openSUSE, Void, Solus and Alpine (#937) - evdev monitors remapper virtual keyboards ungrabbed so remappers like keyd keep working (#932) -- The install section on voculinux.com showcases the .deb, .rpm, Snap, Flatpak and AUR packages (#929) -- The remote `curl | bash` install path is gated end to end in CI (#898) - -AppImage, Flatpak, and Snap still ship whisper.cpp only. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.2). --- ## What's New in v0.18.1 -0.18.1 is a **patch** on the stable line. Default engine is still whisper.cpp. This one is a reliability release: most of it is fixes, and the new features are plumbing you will notice only when you need it. Settings gains a Proxy page so model downloads and update checks work behind SOCKS5 and HTTP proxies, and an opt-in switch that persists transcripts to disk so a failed injection stops meaning a lost sentence. Releases now attach native .deb and .rpm packages, and the tray menu drops Start on Login and About (both already lived in Settings). +0.18.1 is a **patch** on the stable line. Default engine is still whisper.cpp. This one is a reliability release: most of it is fixes, and the new features are plumbing you will notice only when you need it. Settings gains a Proxy page so model downloads and update checks work behind SOCKS5 and HTTP proxies, and an opt-in switch that persists transcripts to disk so a failed injection stops meaning a lost sentence. The tray menu drops Start on Login and About (both already lived in Settings). ### 0.18.1 highlights @@ -217,7 +191,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. |---------|-------------| | **Proxy settings** | New Settings -> Proxy page: off, system, or manual SOCKS5/HTTP CONNECT with optional auth; covers every model download and the update checker (#909, fixes #655) | | **Transcript persistence** | Opt-in JSONL history on disk; a transcript survives restarts and failed injections (#907, fixes #758) | -| **Native packages** | Thin .deb and .rpm for Debian/Ubuntu and Fedora, x86_64 and aarch64, attached to the GitHub Release (#913, step 1 of #600) | | **Slimmer tray menu** | Start on Login and About removed from the tray; both already live in Settings (#905, fixes #654) | | **Staged model picker** | Speech Model Advanced pickers no longer start a download per click; changes stage until you confirm Download (#908, fixes #894) | | **Wayland pad fix** | Dictation Pad no longer ghosts away after sitting idle under a Wayland compositor (#912, fixes #896) | @@ -231,12 +204,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. - Test Dictation transcription readout moved above its controls in the sidebar footer (#904, fixes #677 reported by @hopsayer) - `uninstall.sh` no longer deletes files in the directory you ran it from (#901, fixes #897 reported by @SilverChatte) - Settings > Advanced Initial Prompt accepts typed input again (clicks were being stolen by the enclosing row), and transcript and log saves no longer write a doubled `.txt.txt` name (#927) -- Packaging: `.deb` declares `python3-socks` and `.rpm` declares `python3-pysocks` for SOCKS5 proxy support (#920) -- CI: snap attach uses `--repo`, checksums still publish when an asset attach fails, the Vulkan pywhispercpp build is reused across runs, and the remote `curl | bash` install path is gated end to end (#899, #903, #906) - -AppImage, Flatpak, and Snap still ship whisper.cpp only. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.1). --- @@ -273,22 +240,16 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. - Settings: scrollable category list, Dictation Tone grayed while sound effects are off, Test Dictation textbox artifact and missing transcription fixed, speech-model follow-ups (#886, #877, #853, #836, fixes #678, #849, #847, #720, #834) - Update checker falls back when GitHub API rate-limits instead of erroring (#846, fixes #845 reported by @lmstud) - Audio: stop passing an explicit index when zero devices enumerate; View Logs closes via the titlebar X (#891, #892) -- Snap gains `hardware-observe` so hotkeys can read input devices (#858, fixes #857 reported by @RhysU) - Installer installs hash-pinned dependencies and build tools, and is split into sourced modules with a generated distro package map (#856, #862, #872 by @sesav) -- AUR `voculinux-bin` ships the AppImage with per-arch digests; releases publish a signed self-hosted Flatpak OSTree remote; a snap-promote workflow gates stable promotion (#879, #875, #881, fixes #817, #785, #783) -- VocaGateway can run locally from Settings → Advanced (podman-first) (#774) +- The local gateway can run from Settings → Advanced (podman-first) (#774) - Dependency advisories cleared and workflow tokens scoped to repository reads (#869, #865, #866 by @Mr-Sunglasses, #870) - Settings dialog consolidated: guard flags and widget construction in one place each (#878, fixes #793) -AppImage, Flatpak, and Snap still ship whisper.cpp plus the same engine matrix as 0.17. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18.0). - --- ## What's New in v0.17.0 -0.17.0 is a **minor** on the stable line. Default engine is still whisper.cpp. This release adds two optional local engines (Faster Whisper and Parakeet), a simpler Speech Model page, Snap packaging with native Wayland typing, and Flatpak bundles built by the release workflow. It also fixes XWayland/layout paste, a KDE xdotool crash, push-to-talk tray redraw, clipped start/stop cues, HDA analog mics that abort when opened below native channel count, native GTK installs that ignored OS dark/light, and English-only models that hid every other language. +0.17.0 is a **minor** on the stable line. Default engine is still whisper.cpp. This release adds two optional local engines (Faster Whisper and Parakeet) and a simpler Speech Model page. It also fixes XWayland/layout paste, a KDE xdotool crash, push-to-talk tray redraw, clipped start/stop cues, HDA analog mics that abort when opened below native channel count, native GTK installs that ignored OS dark/light, and English-only models that hid every other language. ### 0.17 series highlights @@ -301,8 +262,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. | **Searchable open picker** | Language list filters while open (#798) | | **Localized punctuation commands** | it/fr/de/es/pt/nl/pl/ru; English phrases still work (#642) | | **Bare F-keys** | F1–F24 are valid push-to-talk shortcuts (#815) | -| **Snap** | Store listing, ydotool + `uinput` for native Wayland. The Store later denied the `uinput` grant, so the plug was dropped and Wayland typing moved to the RemoteDesktop portal (#519, #823, #822) | -| **Flatpak on the tag** | Workflow attaches `.flatpak` assets and checksums them (#786) | ### Also in v0.17.0 @@ -314,27 +273,23 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.18. - Applying an already-downloaded model no longer freezes Settings (#790) - Selected language picks the whisper.cpp variant (English → `.en`). Picking another language, or auto-detect, switches off `.en` / `.en-q*` instead of hiding the rest of the list (#795, #780, #826) - Speech Model labels are nouns (Language, Other languages, Speed vs accuracy). Unused downloads is a sibling expander of Advanced, not nested inside it (#826) -- About family grid includes VocaWin (#826) - Push-to-talk tray icon turns red on every hold (#809) - Sink-wake no longer clips start/stop cues (#804) - Open 3-8 channel HDA analog mics at native layout instead of forcing 2ch/48kHz, so PortAudio no longer aborts after read() (`free(): corrupted unsorted chunks`); capture is downmixed to mono for engines (#829, fixes #813) -- Native GTK installs (AUR / install.sh) follow OS dark/light via the appearance portal then gsettings; skipped when `GTK_THEME` is set so AppImage and user overrides stay in charge (#830, fixes #816) +- Native GTK installs (`install.sh`) follow OS dark/light via the appearance portal then gsettings; skipped when `GTK_THEME` is set so user overrides stay in charge (#830, fixes #816) - Parakeet keeps recognizing after a decode error (#803) -- Flatpak/AUR deps derived from `uv.lock` (#819) - Hash-pinned exports for VOSK, Parakeet, and Faster Whisper extras so `install.sh` no longer installs those unpinned; extras are version-capped (#828) - `just verify-release` checks the published GitHub Release (#791) - Distro matrix runs `install.sh` (#810) - `install.sh` Faster Whisper box is CPU CTranslate2 / INT8, not NVIDIA CUDA. The whisper.cpp GPU step does not install the CUDA toolkit; Vulkan is first, CUDA only if a toolkit is already on the machine (#826) -AppImage, Flatpak and Snap remain whisper.cpp only. Faster Whisper and Parakeet are optional extras on `install.sh` / source installs. - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.17.0). +Faster Whisper and Parakeet are optional extras on `install.sh` / source installs. They are not part of the Void package. --- ## What's New in v0.16.2 -0.16.2 is a **stability patch** on the 0.16 series. The feature set is the same as 0.16.x. This release fixes KDE leftover IBus so dictation types into real apps, Wayland and IBus keyboard shortcuts through wtype/ydotool, real BackSpace for "delete that", Fedora/Arch installer glslc packages, nightly version stamping, and release integrity pins. CI now gates AUR PKGBUILD builds and the distros the docs promise. +0.16.2 is a **stability patch** on the 0.16 series. The feature set is the same as 0.16.x. This release fixes KDE leftover IBus so dictation types into real apps, Wayland and IBus keyboard shortcuts through wtype/ydotool, real BackSpace for "delete that", Fedora/Arch installer glslc packages, nightly version stamping, and release integrity pins. CI now gates the distros the docs promise. ### 0.16 series highlights @@ -344,32 +299,28 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.17. | **Right Alt PTT default** | New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648) | | **Searchable languages** | Type to filter the Speech Model language list (#672) | | **Delete unused models** | Remove leftover downloaded speech models from Settings (#671) | -| **AGPL-3.0** | License aligned with other VocaHQ projects (#660) | +| **AGPL-3.0** | License is AGPL-3.0 (#660) | | **Family mic icons** | App icon, tray states, and site favicons use the shared Voca family mic (#704) | | **Tone picker** | Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708) | | **Installer** | Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706) | ### Bug fixes in v0.16.2 -- **KDE inject**: skip leftover IBus when it is not the session IM so dictation types into Kate, browsers, and terminals (#753 by @jatinkrmalik, fixes #752 by @justTravis) +- **KDE inject**: skip leftover IBus when it is not the session IM so dictation types into Kate, browsers, and terminals (#753, fixes #752 by @justTravis) - **Wayland shortcuts**: wtype and ydotool deliver real chords instead of refusing or silently doing nothing (#715 by @eiseleb47) - **IBus shortcuts**: route X11_IBUS through xdotool and WAYLAND_IBUS through wtype/ydotool (#716 by @eiseleb47) - **Delete that**: send real BackSpace key events instead of U+0008 text (#714 by @eiseleb47) -- **Installer**: Fedora and Arch need glslc/shaderc packages, not glslang (#763 by @jatinkrmalik, see #604) +- **Installer**: Fedora and Arch need glslc/shaderc packages, not glslang (#763, see #604) - **Nightly**: stamp `version.py` before `python -m build` so wheel metadata matches the filename (#762 by @sesav) - **Release integrity**: checksums, signatures, and pinned builders for release artifacts (#759 by @sesav, epic #701 phase 5) -- **CI**: gate AUR PKGBUILD builds on every PR (#772 by @sesav) - **CI / docs**: test the distros the docs promise and fix docs drift (#773 by @sesav) -- **Site**: VocaGateway family card is Beta; README logo, badges, and privacy copy (#765 by @jatinkrmalik, #764) -- **Snap**: v0.16.2 `latest/edge` (rev 7) has no `uinput` plug. `sudo snap connect voculinux:uinput` errors with `snap "voculinux" has no plug named "uinput"`. Dictation only reaches XWayland apps. (v0.17.0+ added the plug, but the Store denied it, so later revisions drop it again and type via the RemoteDesktop portal.) (#823) - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.2). +- **Site**: the gateway card is Beta; README logo, badges, and privacy copy (#765, #764) --- ## What's New in v0.16.1 -0.16.1 is a **stability patch** on the 0.16 series. The feature set is the same as 0.16.x. This release fixes wrong-model startup, leftover tray state after toggle stop, paste into terminals, GNOME XWayland layout after inject, and AppImages that needed a glibc newer than Debian 12. The installer now requires Python 3.11 and verifies model downloads. +0.16.1 is a **stability patch** on the 0.16 series. The feature set is the same as 0.16.x. This release fixes wrong-model startup, leftover tray state after toggle stop, paste into terminals, and GNOME XWayland layout after inject. The installer now requires Python 3.11 and verifies model downloads. ### 0.16 series highlights @@ -379,7 +330,7 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. | **Right Alt PTT default** | New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648) | | **Searchable languages** | Type to filter the Speech Model language list (#672) | | **Delete unused models** | Remove leftover downloaded speech models from Settings (#671) | -| **AGPL-3.0** | License aligned with other VocaHQ projects (#660) | +| **AGPL-3.0** | License is AGPL-3.0 (#660) | | **Family mic icons** | App icon, tray states, and site favicons use the shared Voca family mic (#704) | | **Tone picker** | Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708) | | **Installer** | Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706) | @@ -396,13 +347,9 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. - **IBus**: sync the XWayland layout from GNOME after scoped inject (#742) - **Installer**: survive a release without a checksum manifest; stop inventing GPUs (#736 by @sesav) - **Installer**: leftover engine repair, just `--no-sync`, ggml verify from #713 (#732) -- **AppImage**: build against a glibc floor Debian 12 can run; boot tests on six distros (#743, #744 by @sesav) - **Installer**: Python 3.11 floor, uv tooling, verified model downloads (epic #701 phases 2.5 and 5) (#713 by @sesav) - **Settings / About**: even dropdowns, quieter About, family platform marks (#754) -- **AUR**: `python -m build --no-isolation` works with Arch extra setuptools 84 (was capped at `<82`, AUR comment by simona). Skip `context_params` on AUR pywhispercpp 1.4.x so startup no longer dies with `whisper_full_params` (AUR comments by avocadoboat, Masalababa; GitHub #625) -- **Docs**: canonical VocaHQ Discord invite; VocaWin is unsigned beta; screenshots page says v0.16; README family/on-device copy (#749, #733, #735, #737) - -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.1). +- **Docs**: screenshots page says v0.16; README family/on-device copy (#749, #733, #735, #737) --- @@ -418,7 +365,7 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. | **Right Alt PTT default** | New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648) | | **Searchable languages** | Type to filter the Speech Model language list (#672) | | **Delete unused models** | Remove leftover downloaded speech models from Settings (#671) | -| **AGPL-3.0** | License aligned with other VocaHQ projects (#660) | +| **AGPL-3.0** | License is AGPL-3.0 (#660) | | **Family mic icons** | App icon, tray states, and site favicons use the shared Voca family mic (#704) | | **Tone picker** | Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708) | | **Installer** | Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706) | @@ -433,7 +380,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. - **Disable missing-tray warning**: Settings toggle for desktops that false-positive the tray check (#628, fixes #620) - **Family mic icons**: App icon, tray states, and site favicons use the shared Voca family mic instead of the old Linux rounded-rect (#704) - **Family dictation tone picker**: Settings → Audio dropdown (Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off) plus Preview. New installs and unknown saved names default to Voca. A saved catalog id, including Off, is left alone. Enable remains the master mute; Off skips start/stop only (#707) -- **About page**: Settings → About groups this app, VocaHQ family sites, and talk-to-us (GitHub issues, Discord, X, email) (#718) ### Bug Fixes @@ -444,7 +390,6 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. - **Tray / Settings**: Prefer Ayatana AppIndicator on KDE (#621); reuse Settings/Logs windows (#669, fixes #653); separate Close from Test Dictation (#670, fixes #651) - **Settings**: Test Dictation no longer reports no speech when recognition never started (missing model / auto-pause / live engine out of sync) (#702) - **Clipboard**: Restore after ydotool clipboard-paste (#588); text-only reads and safer overlapping restore (#646) -- **AppImage**: Ship transitive GI typelibs for non-Debian hosts (also hotfixed onto the v0.15.0 AppImages on 2026-08-03) (#637); pin pywhispercpp to the version `install.sh` declares so a newer PyPI wheel cannot break the Vulkan rebuild (#718) - **Installer**: Distro python3-gi is required; pip no longer builds PyGObject from sdist. Unset `XDG_SESSION_TYPE` / `XDG_CURRENT_DESKTOP` no longer crash under `set -u` (#706) - **Installer / downloads / tests**: Gate `util-linux-extra` to Ubuntu 24.04+ (#635, fixes #526); report failed model downloads (#690); stop the suite from overwriting real `config.json` (#694) @@ -453,27 +398,16 @@ See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16. - Website screenshot refresh for v0.15 (#630) - Prefer Ayatana AppIndicator in Fedora/Arch packaging hints (#638) - CUDA device 0 note for dual NVIDIA (#644) -- Discord and VocaHQ README shields; VocaHQ URL migration; VocaGateway rename (#695, #696, #697) -- Discord invite and X handle point at VocaHQ (#722) +- README badges; gateway rename (#695, #696, #697) - voculinux.com restyled to the Voca family workbench; Open Graph card uses the flat Tux (#728, #729) -- Website copy drops the stale 100% offline claim and marks VocaWin as alpha on the site (#717) -- Codeberg mirror tag force-push (#633) +- Website copy drops the stale 100% offline claim (#717) - Installer hardening, Justfile in place of Makefile, and uv lockfiles with pinned build inputs. Epic #701 remains open (#700, #705 by @sesav) -See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.0). - --- ## Older releases -Notes for v0.15.0 and earlier live on GitHub Releases: - -- [v0.15.0](https://github.com/VocaHQ/vocalinux/releases/tag/v0.15.0) -- [v0.14.2](https://github.com/VocaHQ/vocalinux/releases/tag/v0.14.2) -- [v0.14.1](https://github.com/VocaHQ/vocalinux/releases/tag/v0.14.1) -- [v0.14.0-beta](https://github.com/VocaHQ/vocalinux/releases/tag/v0.14.0-beta) - -Full history: https://github.com/VocaHQ/vocalinux/releases +Release notes for v0.15.0 and earlier are not included in this document. --- @@ -483,6 +417,4 @@ Full history: https://github.com/VocaHQ/vocalinux/releases - [Troubleshooting](TROUBLESHOOTING.md) - [User guide](USER_GUIDE.md) - [Support](../SUPPORT.md) -- [Report issues](https://github.com/VocaHQ/vocalinux/issues) -- [Discussions](https://github.com/VocaHQ/vocalinux/discussions) -- [Discord](https://discord.gg/t6muquAJbm) +- [Report issues](https://git.bongbetic.com/xavierk/voculinux/issues)