voiceio

 ██╗   ██╗ ██████╗ ██╗ ██████╗███████╗██╗ ██████╗
 ██║   ██║██╔═══██╗██║██╔════╝██╔════╝██║██╔═══██╗
 ██║   ██║██║   ██║██║██║     █████╗  ██║██║   ██║
 ╚██╗ ██╔╝██║   ██║██║██║     ██╔══╝  ██║██║   ██║
  ╚████╔╝ ╚██████╔╝██║╚██████╗███████╗██║╚██████╔╝
   ╚═══╝   ╚═════╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═════╝

Voice dictation for Linux. Local, yours, and it learns how you speak.

https://github.com/user-attachments/assets/9cf5d1ac-b4bb-4cf8-b775-7a66dc16b376

Open-source, sovereign voice input/output. Your speech is transcribed on your own machine, everything it learns about you stays in local files you own, and it gets better the more you use it.

• Local & sovereign — speech is transcribed on-device with faster-whisper; audio never leaves the machine. Your history, retained audio, corrections, and vocabulary all live in plain local files (JSONL / TOML / txt) you can read, edit, and delete. Zero telemetry. The one honest nuance: two optional, off-by-default features send text (never audio) to a cloud LLM you configure yourself — final-transcript polish ([postcorrect]) and the weekly correction-mining review.
• Improves with use — automatically — every utterance teaches it your words and names. See How it learns.
• Linux-first & hackable — Wayland/X11, GNOME/KDE/sway/i3, chosen automatically by chain-and-probe backends. It's plain Python you can read in an afternoon and contribute to.

Linux-first. voiceio is developed and tested daily on Linux (GNOME/Wayland). Windows and macOS ship as experimental, untested targets — the code paths exist but are unmaintained and likely broken. See Experimental platforms.

Quick start

# 1. Install system dependencies (Ubuntu/Debian). build-essential + python3-dev
#    are needed to compile evdev (no prebuilt wheel); portaudio for the mic.
sudo apt install pipx build-essential python3-dev portaudio19-dev ibus gir1.2-ibus-1.0 python3-gi

# 2. Install voiceio
pipx install python-voiceio

# 3. Run the setup wizard
voiceio setup

That's it. Press Ctrl+Alt+V (or your chosen hotkey) to start dictating.

Installing with an AI agent? Point it at INSTALL.md — a terse, copy-pasteable runbook (voiceio setup --defaults / --answers '{json}', no TTY needed).

sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject
pipx install python-voiceio
voiceio setup

sudo pacman -S python-pipx base-devel portaudio ibus python-gobject
# base-devel provides gcc/make; the python package ships headers.
pipx install python-voiceio
voiceio setup

git clone https://github.com/Hugo0/voiceio
cd voiceio
uv pip install -e ".[linux,dev]"

# Bootstrap CLI commands onto PATH (creates ~/.local/bin/voiceio)
uv run voiceio setup

You can also install with uv tool install python-voiceio or pip install python-voiceio.

How it works

hotkey → mic capture → whisper (local) → text at cursor
          pre-buffered   streaming        IBus / clipboard

Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via faster-whisper, text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals. It runs in real time on a modern CPU and ships with model tiers from tiny to large-v3.

How it learns

Most dictation tools transcribe the same way on day 100 as on day 1. voiceio adapts to you — your jargon, names, and accent — entirely from data that never leaves your machine.

flowchart LR
    subgraph live ["every utterance"]
        A["🎙️ dictate"] --> B["store audio + raw text\n+ confidence (local)"]
        A --> C["hotwords + recent context\nbias the Whisper decoder"]
        A --> D["optional LLM pass fixes\nmisheard proper nouns"]
    end
    subgraph weekly ["weekly, in the background"]
        E["mine history for recurring errors\n→ learn corrections + vocabulary\n(safety-gated, multi-vote)"] --> F["teacher model replays your audio\n→ audits what was learned"]
        F -->|"bad rule"| G["auto-retired"]
        F -->|"quality regressed"| H["whole week rolled back"]
    end
    B --> E
    F -->|"confirmed"| C

1. Capture — every utterance stores its audio, raw text, and confidence in local files.
2. Bias — your vocabulary and recent context steer the Whisper decoder (hotwords / prompt) on every recording.
3. Contextual fix — an optional LLM pass repairs misheard proper nouns using surrounding context.
4. Mine — a weekly background job scans your history for recurring errors and auto-learns corrections and vocabulary. Multi-vote adjudication and a protected-languages guard (for bilingual users) keep it safe; it never asks you to triage.
5. Audit — a teacher model (a larger Whisper) replays your retained audio to verify what was learned. Bad rules are retired automatically, and a system-level drift metric rolls back an entire week of learning if quality regressed.

Rules are always probationary, never tenured — anything that stops helping is dropped. Your only touchpoint is an occasional desktop notification telling you what was learned.

Features

• Streaming: text appears as you speak, not after you stop
• Works everywhere: IBus input method for GUI apps, clipboard for terminals
• Wayland + X11: evdev hotkeys work on both, no root required
• Pre-buffer: never miss the first syllable
• Voice commands: "new line", "comma", "scratch that", punctuation by name
• Autocorrect: LLM-powered review of recurring Whisper mistakes (voiceio correct)
• Text-to-speech: hear selected text spoken back (Piper, eSpeak, Edge TTS)
• Smart post-processing: numbers ("twenty five" → "25"), punctuation, capitalization
• Auto-healing: falls back to the next working backend if one fails
• Autostart: optional systemd service, restarts on crash
• Self-diagnosing: voiceio doctor checks everything, --fix repairs it

Models

Models download automatically on first use. Switch anytime: voiceio --model small.

Commands

voiceio                  Start the daemon
voiceio setup            Interactive setup wizard
voiceio doctor           Health check (--fix to auto-repair)
voiceio test             Test microphone + live transcription
voiceio demo             Interactive guided tour of all features
voiceio toggle           Toggle recording on a running daemon
voiceio correct          Review and fix recurring transcription errors
voiceio history          View transcription history
voiceio update           Update to latest version
voiceio service install  Autostart on login (systemd / Windows Startup)
voiceio logs             View recent logs
voiceio uninstall        Remove all system integrations

Configuration

voiceio setup handles everything interactively. To tweak later, edit the config file or override at runtime:

• Linux/macOS: ~/.config/voiceio/config.toml
• Windows: %LOCALAPPDATA%\voiceio\config\config.toml (see Experimental platforms)

voiceio --model large-v3 --language auto -v

See config.example.toml for all options.

Troubleshooting

voiceio doctor           # see what's working
voiceio doctor --fix     # auto-fix issues
voiceio logs             # check debug output

Platform support

voiceio targets Linux. That's what it's developed and tested against.

voiceio auto-detects your platform and picks the best available backends. Run voiceio doctor to see what's working on your system.

Experimental platforms

Windows and macOS code paths exist, but they are experimental, untested, and unmaintained — the maintainer only develops on Linux, so they may be broken at any given time. No parity with Linux is promised. Contributions are welcome, but please don't file bugs expecting a fix.

• Windows: pip install python-voiceio then voiceio setup (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on GitHub Releases.
• macOS: pipx install python-voiceio then voiceio setup. If it doesn't work for you, consider aquavoice.com or contribute a PR.
• Config lives at %LOCALAPPDATA%\voiceio\config\config.toml (Windows) or ~/.config/voiceio/config.toml (macOS).

Uninstall

voiceio uninstall        # removes service, IBus, shortcuts, symlinks
pipx uninstall python-voiceio   # removes the package

Roadmap

Contributions welcome! See CONTRIBUTING.md and open issues.

Now

• macOS polish (IMKit for native preedit, Accessibility API for text injection)

Soon

• Per-app context awareness (detect focused app, adapt formatting/behavior)
• File/audio transcription mode (voiceio transcribe recording.mp3)

Backlog

• Multiple engine backends (whisper.cpp for Vulkan/AMD, VOSK for low-end hardware)
• Echo cancellation (filter system audio for meeting use)
• Wake word activation ("Hey voiceio") Done
• Text-to-speech output (Piper/eSpeak/Edge TTS — completes the "io")
• LLM auto-audit dictionary (voiceio correct --auto — scan history with LLM, interactive correction)
• LLM post-processing via Ollama (grammar cleanup, spelling fixes on final pass)
• Corrections dictionary — auto-replace misheard words, "correct that" voice command
• Transcription history — searchable log of everything you've dictated
• Number-to-digit conversion ("three hundred forty two" → "342")
• VAD-based silence filtering (Silero VAD, prevents Whisper hallucinations)
• Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
• Custom vocabulary / personal dictionary (bias Whisper via initial_prompt)
• Smart punctuation & capitalization post-processing
• Windows support (experimental, untested)
• System tray icon with animated states
• Auto-stop on silence

License

MIT