python-voiceio 0.3.13__tar.gz → 0.4.1__tar.gz

{python_voiceio-0.3.13/python_voiceio.egg-info → python_voiceio-0.4.1}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.3.13
-Summary: Speak → text, locally, instantly.
+Version: 0.4.1
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hugo0/voiceio
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
-Keywords: voice,speech-to-text,whisper,linux,windows,dictation,wayland,ibus
+Keywords: voice,speech-to-text,whisper,linux,dictation,wayland,ibus
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.11
@@ -42,6 +40,10 @@ Requires-Dist: edge-tts>=6.1.0; extra == "tts-cloud"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
+Provides-Extra: linux
+Requires-Dist: pystray>=0.19; extra == "linux"
+Requires-Dist: Pillow>=10.0; extra == "linux"
+Requires-Dist: piper-tts>=1.2.0; extra == "linux"
 Dynamic: license-file
 
 # voiceio
@@ -61,15 +63,24 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+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](https://github.com/SYSTRAN/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](#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](CLAUDE.md).
+
+> **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](#experimental-platforms).
+
 ## Quick start
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install pipx ibus gir1.2-ibus-1.0 python3-gi python3-dev portaudio19-dev
+# 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
@@ -80,11 +91,14 @@ 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](INSTALL.md) — a terse,
+copy-pasteable runbook (`voiceio setup --defaults` / `--answers '{json}'`, no TTY needed).
+
 <details>
 <summary><strong>Fedora</strong></summary>
 
 ```bash
-sudo dnf install pipx ibus python3-gobject python3-devel portaudio-devel
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject
 pipx install python-voiceio
 voiceio setup
 ```
@@ -94,36 +108,17 @@ voiceio setup
 <summary><strong>Arch Linux</strong></summary>
 
 ```bash
-sudo pacman -S python-pipx ibus python-gobject portaudio
-# Note: Arch includes Python headers by default with the python package
+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
 ```
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
-
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -152,7 +147,35 @@ 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](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+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](https://github.com/SYSTRAN/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.
+
+```mermaid
+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
 
@@ -202,7 +225,7 @@ voiceio uninstall        Remove all system integrations
 `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`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -224,12 +247,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -237,11 +260,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 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.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -275,7 +309,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.13 → python_voiceio-0.4.1}/README.md

@@ -15,15 +15,24 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+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](https://github.com/SYSTRAN/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](#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](CLAUDE.md).
+
+> **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](#experimental-platforms).
+
 ## Quick start
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install pipx ibus gir1.2-ibus-1.0 python3-gi python3-dev portaudio19-dev
+# 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
@@ -34,11 +43,14 @@ 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](INSTALL.md) — a terse,
+copy-pasteable runbook (`voiceio setup --defaults` / `--answers '{json}'`, no TTY needed).
+
 <details>
 <summary><strong>Fedora</strong></summary>
 
 ```bash
-sudo dnf install pipx ibus python3-gobject python3-devel portaudio-devel
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject
 pipx install python-voiceio
 voiceio setup
 ```
@@ -48,36 +60,17 @@ voiceio setup
 <summary><strong>Arch Linux</strong></summary>
 
 ```bash
-sudo pacman -S python-pipx ibus python-gobject portaudio
-# Note: Arch includes Python headers by default with the python package
+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
 ```
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
-
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -106,7 +99,35 @@ 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](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+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](https://github.com/SYSTRAN/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.
+
+```mermaid
+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
 
@@ -156,7 +177,7 @@ voiceio uninstall        Remove all system integrations
 `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`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -178,12 +199,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -191,11 +212,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 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.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -229,7 +261,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.13 → python_voiceio-0.4.1}/pyproject.toml

@@ -4,20 +4,18 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "0.3.13"
-description = "Speak → text, locally, instantly."
+version = "0.4.1"
+description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
 authors = [{ name = "Hugo Montenegro" }]
-keywords = ["voice", "speech-to-text", "whisper", "linux", "windows", "dictation", "wayland", "ibus"]
+keywords = ["voice", "speech-to-text", "whisper", "linux", "dictation", "wayland", "ibus"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: X11 Applications",
     "Intended Audience :: End Users/Desktop",
     "Operating System :: POSIX :: Linux",
-    "Operating System :: Microsoft :: Windows",
-    "Operating System :: MacOS",
     "Programming Language :: Python :: 3",
     "Topic :: Multimedia :: Sound/Audio :: Speech",
 ]
@@ -39,6 +37,10 @@ tray = ["pystray>=0.19", "Pillow>=10.0"]
 tts = ["piper-tts>=1.2.0"]
 tts-cloud = ["edge-tts>=6.1.0"]
 dev = ["pytest>=7.0", "pytest-mock"]
+# Convenience bundle for a full Linux install (tray icon + local TTS). The core
+# Linux deps (evdev, sounddevice) are already unconditional; system packages
+# (IBus, PortAudio, a C toolchain) are installed separately — see README.
+linux = ["pystray>=0.19", "Pillow>=10.0", "piper-tts>=1.2.0"]
 
 [project.urls]
 Homepage = "https://github.com/Hugo0/voiceio"

{python_voiceio-0.3.13 → python_voiceio-0.4.1/python_voiceio.egg-info}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.3.13
-Summary: Speak → text, locally, instantly.
+Version: 0.4.1
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hugo0/voiceio
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
-Keywords: voice,speech-to-text,whisper,linux,windows,dictation,wayland,ibus
+Keywords: voice,speech-to-text,whisper,linux,dictation,wayland,ibus
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.11
@@ -42,6 +40,10 @@ Requires-Dist: edge-tts>=6.1.0; extra == "tts-cloud"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
+Provides-Extra: linux
+Requires-Dist: pystray>=0.19; extra == "linux"
+Requires-Dist: Pillow>=10.0; extra == "linux"
+Requires-Dist: piper-tts>=1.2.0; extra == "linux"
 Dynamic: license-file
 
 # voiceio
@@ -61,15 +63,24 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+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](https://github.com/SYSTRAN/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](#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](CLAUDE.md).
+
+> **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](#experimental-platforms).
+
 ## Quick start
 
 ```bash
-# 1. Install system dependencies (Ubuntu/Debian)
-sudo apt install pipx ibus gir1.2-ibus-1.0 python3-gi python3-dev portaudio19-dev
+# 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
@@ -80,11 +91,14 @@ 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](INSTALL.md) — a terse,
+copy-pasteable runbook (`voiceio setup --defaults` / `--answers '{json}'`, no TTY needed).
+
 <details>
 <summary><strong>Fedora</strong></summary>
 
 ```bash
-sudo dnf install pipx ibus python3-gobject python3-devel portaudio-devel
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject
 pipx install python-voiceio
 voiceio setup
 ```
@@ -94,36 +108,17 @@ voiceio setup
 <summary><strong>Arch Linux</strong></summary>
 
 ```bash
-sudo pacman -S python-pipx ibus python-gobject portaudio
-# Note: Arch includes Python headers by default with the python package
+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
 ```
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
-
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -152,7 +147,35 @@ 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](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+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](https://github.com/SYSTRAN/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.
+
+```mermaid
+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
 
@@ -202,7 +225,7 @@ voiceio uninstall        Remove all system integrations
 `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`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -224,12 +247,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -237,11 +260,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 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.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -275,7 +309,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence