voculinux/README.md

<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](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/)
[![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.19.0-478061)](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.19.0)

[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.

**Current release:** [v0.19.0](https://git.bongbetic.com/xavierk/voculinux/releases/tag/v0.19.0). 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
- **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 &amp; 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
```

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 |
| **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                 # from the xbps package, on your PATH
```

You can also launch Voculinux from your application menu.

### 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) |

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

### 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 Voca 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
python -m vocalinux.main --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 a hard fork of 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.

## 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`.