Metadata-Version: 2.4
Name: voculinux
Version: 0.19.1
Summary: A seamless voice dictation system for Linux
Author-email: Jatin K Malik <jatinkrmalik@gmail.com>
Maintainer-email: Jatin K Malik <jatinkrmalik@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://git.bongbetic.com/xavierk/voculinux
Project-URL: Documentation, https://git.bongbetic.com/xavierk/voculinux/src/branch/main/docs
Project-URL: Repository, https://git.bongbetic.com/xavierk/voculinux
Project-URL: Issues, https://git.bongbetic.com/xavierk/voculinux/issues
Project-URL: Changelog, https://git.bongbetic.com/xavierk/voculinux/releases
Keywords: voice,dictation,speech,recognition,linux,accessibility,voice-typing,speech-to-text
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: GTK
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment :: Gnome
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywhispercpp<2,>=1.5.0
Requires-Dist: pynput<2,>=1.7.6
Requires-Dist: evdev<2,>=1.6.0; sys_platform == "linux"
Requires-Dist: requests>=2.28.0
Requires-Dist: PySocks<2,>=1.7.1
Requires-Dist: numpy<3,>=1.22.0
Requires-Dist: pyaudio>=0.2.13
Requires-Dist: PyGObject; sys_platform == "linux"
Requires-Dist: psutil<8,>=5.9.0
Provides-Extra: vosk
Requires-Dist: vosk<0.4,>=0.3.45; extra == "vosk"
Provides-Extra: whisper
Requires-Dist: openai-whisper>=20231117; extra == "whisper"
Requires-Dist: torch>=2.13.0; extra == "whisper"
Provides-Extra: parakeet
Requires-Dist: sherpa-onnx<2,>=1.12.0; extra == "parakeet"
Requires-Dist: sherpa-onnx-core==1.13.7; platform_machine != "armv7l" and extra == "parakeet"
Provides-Extra: faster-whisper
Requires-Dist: faster-whisper<2,>=1.0.0; extra == "faster-whisper"
Provides-Extra: vad
Requires-Dist: onnxruntime>=1.16.0; extra == "vad"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pyyaml<7,>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Dynamic: license-file

<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.1-478061)](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.

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

### Migrating from a previous Vocalinux install

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:

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

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