xavierk/voculinux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(readme): current usage, GPU and CUDA section, single upstream credit (#56)
CI / security (push) Successful in 1m10s
Details
CI / lint (push) Successful in 22s
Details
CI / ai-review (push) Skipped
Details

Browse Source
This commit was merged in pull request #56.
This commit is contained in:
xavierk
2026-11-07 03:00:25 +00:00
parent d1a80e6ead
commit 808bd17704
2 changed files with 68 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+63 -20
View File
@@ -19,7 +19,7 @@
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 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. It is built for Void Linux, with niri and the Dank Material Shell in mind, and is inspired by an earlier project credited under [Origin](#origin).
**Current release:** [v0.19.1](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.19.1), a patch on v0.19.0 that warns when a leftover launcher from the upstream project shadows Voculinux. v0.19.0 was the first Voculinux release: a Void Linux package from the [signed xbps repository](#void-linux-signed-xbps-repo), niri and Dank Material Shell support, a model default chosen by free GPU memory, and a fix that keeps system-audio capture from ever opening the microphone. Details: [docs/UPDATE.md](docs/UPDATE.md).
@@ -28,7 +28,7 @@ No account is required. Models download once. After that, speech-to-text stays o
- **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 gateway from Settings (not on-device)
- **GPU acceleration**: Vulkan for AMD, Intel, and NVIDIA with whisper.cpp
- **GPU acceleration**: Vulkan for AMD, Intel, and NVIDIA with whisper.cpp, with a CPU fallback. CUDA is a local-build option, not part of the package; see [GPU and CUDA](#gpu-and-cuda)
- **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)
@@ -139,6 +139,13 @@ echo 'repository=https://git.bongbetic.com/xavierk/voculinux/releases/download/l
xbps-install -S voculinux
```
After that, Voculinux upgrades with the rest of the system:
```bash
sudo xbps-install -Su # upgrades Voculinux together with everything else
xbps-query -R voculinux # shows the version the repository serves
```
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
@@ -149,8 +156,8 @@ sync: it would accept an unknown key without asking.
| Engine | When to use |
|--------|-------------|
| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA |
| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA |
| **whisper.cpp** (default) | Best default; Vulkan GPU on AMD, Intel, and NVIDIA, CPU otherwise |
| **Whisper** (OpenAI) | PyTorch path; NVIDIA/CUDA with a CUDA PyTorch you install yourself |
| **Faster Whisper** | CPU-friendly Whisper via CTranslate2 / INT8 |
| **VOSK** | Low RAM / minimal footprint |
| **Parakeet** | CPU; NVIDIA NeMo ASR via sherpa-onnx; 25 European languages |
@@ -164,21 +171,32 @@ on first run.
### After installation
```bash
voculinux # from the xbps package, on your PATH
voculinux # start the tray app; it also appears in your application menu
voculinux --toggle # start or stop dictation from a keybind or script
```
You can also launch Voculinux from your application menu.
1. **First run:** the tray icon appears first, then the speech model loads in the
background. If no model is present, it downloads once (a few hundred MB to
about 1 GB, checksum-verified). The default is chosen from your free memory:
`large-v3-turbo-q8_0`, then `q5_0`, then `small` as memory gets tighter.
2. **Dictate:** focus any text field, hold **Right Alt**, speak, release. The text is
typed at the cursor.
3. **Hands-free:** switch to toggle mode in Settings, or bind `voculinux --toggle`.
4. **On niri:** copy the example keybind pack and read [docs/NIRI.md](docs/NIRI.md).
Typing goes straight to the cursor (`wtype`), with no permission prompt. The tray
needs a StatusNotifier host, which Dank Material Shell provides.
5. **Something wrong?** Run `voculinux --debug`, then see
[Troubleshooting](docs/TROUBLESHOOTING.md).
### Migrating from a previous Vocalinux install
Quit and relaunch Voculinux after an upgrade so the running tray uses the new version.
A previous Vocalinux install can leave launcher files behind. Those that point at a Python environment which no longer exists start nothing, yet they appear next to Voculinux as an old Vocalinux entry, and choosing one does nothing. Voculinux logs and shows one notice that names those files. It never deletes or changes them, so remove them yourself:
### Leftover launchers from an earlier install
```bash
rm -f ~/.local/share/applications/vocalinux.desktop # old Vocalinux menu entry
rm -f ~/.local/bin/vocalinux ~/.local/bin/vocalinux-gui # old Vocalinux wrapper scripts
```
Keep any launcher that still starts a working install. Voculinux only reports launchers that cannot start.
Launchers left by an earlier install of the upstream project can point at a Python
environment that no longer exists. They start nothing, yet they appear next to
Voculinux in the application menu. Voculinux logs and shows one notice that names
those files. It never deletes or changes them, so remove the ones it names
yourself. Keep any launcher that still starts a working install.
### From a source checkout (developers)
@@ -197,10 +215,35 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the two-venv layout and the dev workf
| **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) |
| **Hardware** | Microphone; GPU optional (Vulkan, any vendor) |
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).
## GPU and CUDA
Voculinux is not a CUDA build. The published Void package accelerates whisper.cpp
with **Vulkan**, plus CPU code paths, and it does not ship CUDA. Void has no CUDA
toolkit package, so the package cannot be built against one.
| Where | What runs | Notes |
|-------|-----------|-------|
| Published Void package, NVIDIA GPU | Vulkan | Needs the NVIDIA driver, which provides the Vulkan device. This is the supported NVIDIA path, tested on an RTX 2050 (4 GB) |
| Published Void package, AMD or Intel GPU | Vulkan | Needs the Mesa Vulkan driver. Software Vulkan devices are skipped |
| Published Void package, no usable GPU | CPU | The best instruction-set variant (AVX2 and others) is loaded at run time |
| Local rebuild of `pywhispercpp` with `GGML_CUDA=1` and a toolkit you installed by hand | CUDA | Works, but unsupported: you maintain it, and the package will not replace it on upgrade without a fresh rebuild |
| OpenAI Whisper engine (PyTorch) in your own Python environment | CUDA | Not included in the package; you install a CUDA PyTorch yourself |
| Faster Whisper engine in your own Python environment | CPU (INT8), CUDA optional | Not included in the package |
How the whisper.cpp engine decides: it uses the backends the installed
`pywhispercpp` was actually built with, not what the machine could run. When a
CUDA-built `pywhispercpp` is installed and a complete toolkit is found (`nvcc`,
the runtime header and `libcudart`, with GPU compute capability 7.0 or newer),
CUDA ranks first; otherwise the order is Vulkan, then CPU. The model size then
follows the free memory of the chosen backend, with its own thresholds (CUDA needs
somewhat more than Vulkan for the same model, per the measurements in
[docs/PERF_BASELINE_PROTOCOL.md](docs/PERF_BASELINE_PROTOCOL.md)). To see which
backend loaded, run `voculinux --debug` and read the startup log.
## Usage
### Dictation
@@ -274,7 +317,7 @@ Neural VAD (Silero) is used when `onnxruntime` is available. The xbps package do
## Privacy and security
- Local engines process audio on-device after you download a model; no Voca account required
- Local engines process audio on-device after you download a model; no account required
- Optional remote API is off by default and only used when you configure a server
- Model downloads are checked against pinned checksums
@@ -288,7 +331,7 @@ cd voculinux
./install.sh --dev
source venv/bin/activate
pytest
python -m vocalinux.main --debug
voculinux --debug
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for the two-venv layout, `just` recipes, and PR guidelines.
@@ -304,10 +347,10 @@ Planned:
## Origin
Voculinux is a hard fork of Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux
Voculinux is inspired by Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux
Voculinux is that project's fork for Void Linux. Its source, issues and releases
live on the fork's own host.
It is an independent project for Void Linux. Its source, issues and releases live
on the fork's own host.
## Contributing
tests/test_rename_sweep.py
+5 -2
View File
@@ -96,8 +96,11 @@ RETAINED_MODULE_HEADS = frozenset(
#: The one upstream credit per fork surface, matched as whole stripped lines.
CREDIT_LINE = "Voculinux is a hard fork of Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux"
README_CREDIT_LINE = (
"Voculinux is inspired by Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux"
)
FORK_SURFACE_CREDITS: dict[str, frozenset[str]] = {
"README.md": frozenset({CREDIT_LINE}),
"README.md": frozenset({README_CREDIT_LINE}),
"CONTRIBUTING.md": frozenset({CREDIT_LINE}),
"src/vocalinux/ui/settings_about.py": frozenset(
{
@@ -434,7 +437,7 @@ def test_allowlist_denies_user_facing_old_names() -> None:
def test_allowlist_keeps_the_retained_surfaces() -> None:
"""Upstream provenance, the retained package and the legacy import stay allowed."""
kept = [
("README.md", CREDIT_LINE),
("README.md", README_CREDIT_LINE),
("CONTRIBUTING.md", CREDIT_LINE),
(
"src/vocalinux/ui/settings_about.py",