405 lines
18 KiB
Markdown
405 lines
18 KiB
Markdown
<div align="center">
|
|
|
|
<img src="https://voculinux.com/brand/voculinux-mark-circle.svg" width="50" height="50" alt="Voculinux">
|
|
|
|
# Voculinux
|
|
|
|
**Voice dictation for Linux**
|
|
|
|
[](#void-linux-signed-xbps-repo)
|
|
[](https://www.python.org/downloads/)
|
|
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
[](#privacy-and-security)
|
|
[](#features)
|
|
[](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.19.1)
|
|
|
|
[Website](https://voculinux.com) · [Install](#install) · [Docs](#documentation) · [Releases](https://git.bongbetic.com/xavierk/voculinux/releases) · [Issues](https://git.bongbetic.com/xavierk/voculinux/issues)
|
|
|
|
</div>
|
|
|
|
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. 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).
|
|
|
|
## 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 gateway from Settings (not on-device)
|
|
- **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)
|
|
- **Packaging**: signed Void Linux xbps repository (glibc, x86_64). No other channel is published for Voculinux
|
|
|
|
## Screenshots
|
|
|
|
Voculinux in action. Full gallery on the [website screenshots page](https://voculinux.com/screenshots/).
|
|
|
|
### Product
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="50%">
|
|
<img src="web/public/screenshots/00-transcription.png" alt="Transcription in Action" width="350"><br>
|
|
<em>Real-time voice-to-text transcription</em>
|
|
</td>
|
|
<td align="center" width="50%">
|
|
<img src="web/public/screenshots/02-system-tray.png" alt="System Tray" width="350"><br>
|
|
<em>System tray with listening indicator</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/05-about-view.png" alt="About View" width="350"><br>
|
|
<em>About & Updates in Settings</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/03-log-viewer.png" alt="Log Viewer" width="350"><br>
|
|
<em>Log viewer for debugging</em>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
### Settings
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="33%">
|
|
<img src="web/public/screenshots/settings-speech-engine.png" alt="Speech Engine settings" width="260"><br>
|
|
<em>Speech Engine</em>
|
|
</td>
|
|
<td align="center" width="33%">
|
|
<img src="web/public/screenshots/settings-recognition.png" alt="Recognition settings" width="260"><br>
|
|
<em>Recognition</em>
|
|
</td>
|
|
<td align="center" width="33%">
|
|
<img src="web/public/screenshots/settings-audio.png" alt="Audio settings" width="260"><br>
|
|
<em>Audio</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/settings-performance.png" alt="Performance settings" width="260"><br>
|
|
<em>Performance</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/settings-general.png" alt="General settings" width="260"><br>
|
|
<em>General</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/settings-advanced.png" alt="Advanced tuning and settings" width="260"><br>
|
|
<em>Advanced</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/06-dictation-overlay-listening.png" alt="Dictation overlay listening" width="96"><br>
|
|
<em>Floating overlay while listening (green)</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="web/public/screenshots/07-dictation-overlay-processing.png" alt="Dictation overlay processing" width="96"><br>
|
|
<em>Floating overlay while processing (amber)</em>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
## Install
|
|
|
|
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)
|
|
|
|
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
|
|
```
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
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
|
|
`FINGERPRINT` file attached to the release). Do not add `-y` to the first
|
|
sync: it would accept an unknown key without asking.
|
|
|
|
### Speech engines
|
|
|
|
| Engine | When to use |
|
|
|--------|-------------|
|
|
| **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 |
|
|
| **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 # start the tray app; it also appears in your application menu
|
|
voculinux --toggle # start or stop dictation from a keybind or script
|
|
```
|
|
|
|
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).
|
|
|
|
Quit and relaunch Voculinux after an upgrade so the running tray uses the new version.
|
|
|
|
### Leftover launchers from an earlier install
|
|
|
|
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)
|
|
|
|
```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. The published package targets Void Linux (glibc, x86_64) |
|
|
| **Python** | 3.11 or newer |
|
|
| **Display** | X11 or Wayland |
|
|
| **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
|
|
|
|
1. **Push-to-talk (default on new installs):** hold Right Alt (Option on Mac-layout keyboards) and speak
|
|
2. Speak into the microphone
|
|
3. **Release** to stop, or switch to **Toggle mode** in Settings (double-tap a key to start/stop)
|
|
|
|
Existing configs keep their saved shortcut.
|
|
|
|
### Voice commands
|
|
|
|
English phrases always work. With a non-English recognition language, matching
|
|
punctuation / line-break phrases in that language are also recognized
|
|
(Italian *virgola* / *punto*, French *virgule* / *point*, etc.).
|
|
|
|
| Command | Action |
|
|
|---------|--------|
|
|
| "new line" | Line break |
|
|
| "period" / "full stop" / "dot" | `.` |
|
|
| "comma" | `,` |
|
|
| "question mark" | `?` |
|
|
| "exclamation mark" | `!` |
|
|
| "delete that" | Delete last sentence |
|
|
| "capitalize" | Capitalize next word |
|
|
|
|
### CLI
|
|
|
|
```bash
|
|
voculinux --help
|
|
voculinux --version
|
|
voculinux --debug
|
|
voculinux --engine whisper_cpp # default
|
|
voculinux --engine whisper
|
|
voculinux --engine faster_whisper
|
|
voculinux --engine vosk
|
|
voculinux --engine parakeet
|
|
voculinux --engine remote_api
|
|
voculinux --model medium
|
|
voculinux --model medium.en-q5_0 # exact whisper.cpp variant
|
|
voculinux --model large-v3-turbo
|
|
voculinux --wayland
|
|
voculinux --start-minimized
|
|
```
|
|
|
|
### Autostart
|
|
|
|
**Start on Login** creates an XDG autostart desktop entry (`~/.config/autostart/`). It does not install a systemd unit. Enable from the first-run dialog, tray menu, or Settings.
|
|
|
|
### Configuration
|
|
|
|
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. The xbps package does not pull it in; add `onnxruntime` from your own Python environment.
|
|
|
|
## Documentation
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [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 |
|
|
| [Changelog](CHANGELOG.md) | Release history pointers |
|
|
| [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 |
|
|
| [Contributing](CONTRIBUTING.md) | Dev setup, style, PR process |
|
|
| [Security](SECURITY.md) | Supported versions and vulnerability reporting |
|
|
| [Docs index](docs/README.md) | Full documentation map |
|
|
|
|
## Privacy and security
|
|
|
|
- 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
|
|
|
|
Report vulnerabilities privately per [SECURITY.md](SECURITY.md).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
git clone https://git.bongbetic.com/xavierk/voculinux.git
|
|
cd voculinux
|
|
./install.sh --dev
|
|
source venv/bin/activate
|
|
pytest
|
|
voculinux --debug
|
|
```
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for the two-venv layout, `just` recipes, and PR guidelines.
|
|
|
|
## Roadmap
|
|
|
|
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
|
|
|
|
## Origin
|
|
|
|
Voculinux is inspired by Vocalinux by VocaHQ: https://github.com/VocaHQ/vocalinux
|
|
|
|
It is an independent project 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 [open issues](https://git.bongbetic.com/xavierk/voculinux/issues).
|
|
|
|
- [Report a bug](https://git.bongbetic.com/xavierk/voculinux/issues/new)
|
|
- [Request a feature](https://git.bongbetic.com/xavierk/voculinux/issues/new)
|
|
|
|
## Repository
|
|
|
|
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)).
|
|
|
|
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.
|
|
|
|
### Optional Orukeet model
|
|
|
|
With the Parakeet engine installed, Settings → Speech Model → Parakeet also
|
|
offers `orukeet-v0.1.0`. It uses the existing local sherpa-onnx recognizer for
|
|
25 European languages; the recommended Parakeet model and default whisper.cpp
|
|
engine stay unchanged.
|
|
|
|
The download comes from a pinned revision of
|
|
[oruk/orukeet on Hugging Face](https://huggingface.co/oruk/orukeet). Voculinux
|
|
checks every file against its bundled SHA-256 pins and checks the publisher's
|
|
release manifest against those same pins. The manifest download participates
|
|
in Hugging Face's normal model-download accounting. Cached recognition works
|
|
offline and does not send audio or usage events. The model occupies about
|
|
641 MiB; its CC BY-SA 4.0 weights license and NVIDIA attribution are included.
|
|
|
|
### Optional Underdog Bark 3.0 models
|
|
|
|
Settings → Speech Model → Parakeet also offers two builds of
|
|
[Underdog Bark 3.0](https://huggingface.co/ConwayResearch/Underdog-Bark-3.0), an
|
|
English fine-tune of Parakeet TDT 0.6B v3 (CC BY 4.0): `bark-3.0` (int8, 653 MiB)
|
|
and `bark-3.0-int4` (4-bit, 379 MiB, about half the memory, slower). Both come
|
|
from a pinned revision of
|
|
[velddev/Underdog-Bark-3.0-sherpa-onnx](https://huggingface.co/velddev/Underdog-Bark-3.0-sherpa-onnx),
|
|
an unofficial sherpa-onnx conversion not made or endorsed by Conway Research.
|
|
They run on the existing sherpa-onnx recognizer, every file is checked against
|
|
its bundled SHA-256 pin, and the downloads include the license and attribution
|
|
notice.
|
|
Choose one for English dictation of conversational speech, `bark-3.0-int4` when
|
|
memory is tight; for read or multilingual speech keep `v3-european`.
|