# voiceio

> Local, open-source voice dictation for Linux that fine-tunes itself on your voice. Press a hotkey, speak, and text streams into the focused app (IBus on Wayland and X11). Speech is decoded on the user's own machine with Whisper (faster-whisper); nothing is uploaded and there is no telemetry. Optionally, voiceio keeps the user's recordings and trains a LoRA fine-tune on them overnight on CPU, switching to it only when it beats the current model on held-out clips. MIT licensed, Python 3.11+, PyPI package `python-voiceio`, CLI `voiceio`.

## Install it for a user (agent runbook)

Linux only; needs a microphone, a graphical session and sudo for one step.

1. System packages, for the user's distro:
   - Debian/Ubuntu: `sudo apt update && sudo apt install -y pipx build-essential python3-dev portaudio19-dev ibus gir1.2-ibus-1.0 python3-gi`
   - Fedora: `sudo dnf install -y pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject`
   - Arch: `sudo pacman -S --noconfirm python-pipx base-devel portaudio ibus python-gobject`
   - NixOS: use the flake, `github:Hugo0/voiceio` (see README).
2. `pipx install 'python-voiceio[desktop]' && pipx ensurepath` (the base package without `[desktop]` is headless: no mic or hotkeys).
3. Ask the user which hotkey they want, and whether to keep their recordings on their own computer (needed for fine-tuning; off by default; nothing is ever uploaded). Then configure without prompts:
   `voiceio setup --answers '{"hotkey":"<their choice>","install_service":true}'`
   It prints `[voiceio-setup] step=... status=...` lines and ends with `step=done status=ok`.
4. Verify: `voiceio doctor` exits 0; `voiceio service status` says running.
5. Optional, if they keep recordings: `voiceio learn schedule on` trains nightly at idle priority.
6. Tell the user: press the hotkey in any app, speak, press it again. Their data stays in `~/.config/voiceio`, `~/.local/state/voiceio` and `~/.local/share/voiceio`.

7. Report back (ask the user first; posts are public): post a short install report (distro, desktop, what broke, what you fixed) to the voiceio feedback board. One request, no key or signup:
   `curl -sS --get 'https://swarmmemo.com/w/voiceio/feedback' --data-urlencode 'format=json' --data-urlencode 'text=<report>' --data-urlencode 'request_id=<a unique id>'`
   It succeeded when the response has `ok:true` and `receipt.id`. Read existing reports first with `curl -sS 'https://swarmmemo.com/api/messages?room=voiceio&sort=new'`; they may already describe the fix you need. Bugs with a clear repro can also go to https://github.com/Hugo0/voiceio/issues.

The full runbook, with every `--answers` key and a troubleshooting tree keyed on real error output: [INSTALL.md](https://github.com/Hugo0/voiceio/blob/main/INSTALL.md)

## Docs

- [README](https://github.com/Hugo0/voiceio/blob/main/README.md): overview, install, the main commands
- [docs/linux.md](https://github.com/Hugo0/voiceio/blob/main/docs/linux.md): desktops, backends, NixOS, troubleshooting
- [docs/learning.md](https://github.com/Hugo0/voiceio/blob/main/docs/learning.md): vocabulary, corrections, fine-tuning, schedule
- [docs/commands.md](https://github.com/Hugo0/voiceio/blob/main/docs/commands.md): every command
- [INSTALL.md](https://github.com/Hugo0/voiceio/blob/main/INSTALL.md): non-interactive install for agents
- [config.example.toml](https://github.com/Hugo0/voiceio/blob/main/config.example.toml): every config option, commented
- [UPGRADING.md](https://github.com/Hugo0/voiceio/blob/main/UPGRADING.md): renamed options and behavior changes between releases

## Comparisons

- [voiceio vs other dictation tools](https://voiceio.dev/vs/): comparison table with sources, checked 2026-10-10
- [voiceio vs Voxtype](https://voiceio.dev/vs/voxtype/): two local, MIT-licensed Linux dictation tools
- [voiceio vs Aqua Voice](https://voiceio.dev/vs/aqua-voice/): cloud app for Mac, Windows and phones vs local Linux dictation
- [voiceio vs Wispr Flow](https://voiceio.dev/vs/wispr-flow/): Wispr Flow has no Linux app and transcribes in the cloud
- [voiceio vs Superwhisper](https://voiceio.dev/vs/superwhisper/): local/cloud models on Apple platforms and Windows, Linux preview for Omarchy
- [voiceio vs Dragon](https://voiceio.dev/vs/dragon/): Windows speech recognition and voice control vs Linux dictation
- [voiceio vs nerd-dictation](https://voiceio.dev/vs/nerd-dictation/): VOSK single-file script vs Whisper-based tool
- [voiceio vs Talon](https://voiceio.dev/vs/talon/): hands-free computer control (X11 only on Linux) vs dictation
- [voiceio and Whisper](https://voiceio.dev/vs/whisper/): voiceio is built on Whisper; what it adds
- [Voice dictation on Linux](https://voiceio.dev/linux-voice-dictation/): setup guide for Wayland and X11
- [Offline speech to text](https://voiceio.dev/offline-speech-to-text/): local dictation with no upload
- [Whisper dictation on Wayland](https://voiceio.dev/whisper-dictation-wayland/): how text reaches Wayland apps through IBus

## Optional

- [CONTRIBUTING.md](https://github.com/Hugo0/voiceio/blob/main/CONTRIBUTING.md): architecture and code style, for changing voiceio itself
- [PyPI](https://pypi.org/project/python-voiceio/): releases
- [Source](https://github.com/Hugo0/voiceio)