python-voiceio 1.4.0__tar.gz → 1.6.0__tar.gz

python_voiceio-1.6.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: python-voiceio
+Version: 1.6.0
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
+Author: Hugo Montenegro
+License-Expression: MIT
+Project-URL: Homepage, https://voiceio.dev/
+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,dictation,wayland,ibus
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: onnxruntime>=1.16.0
+Requires-Dist: wordfreq>=3.0
+Provides-Extra: desktop
+Requires-Dist: sounddevice>=0.4.6; extra == "desktop"
+Requires-Dist: evdev>=1.6.0; sys_platform == "linux" and extra == "desktop"
+Requires-Dist: pynput>=1.7.6; extra == "desktop"
+Requires-Dist: pystray>=0.19; extra == "desktop"
+Requires-Dist: Pillow>=10.0; extra == "desktop"
+Provides-Extra: linux
+Requires-Dist: sounddevice>=0.4.6; extra == "linux"
+Requires-Dist: evdev>=1.6.0; sys_platform == "linux" and extra == "linux"
+Requires-Dist: pynput>=1.7.6; extra == "linux"
+Requires-Dist: pystray>=0.19; extra == "linux"
+Requires-Dist: Pillow>=10.0; extra == "linux"
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.9; extra == "server"
+Provides-Extra: tts
+Requires-Dist: piper-tts>=1.3.0; extra == "tts"
+Requires-Dist: edge-tts>=6.1.0; extra == "tts"
+Provides-Extra: train
+Requires-Dist: torch>=2.2; extra == "train"
+Requires-Dist: transformers>=4.40; extra == "train"
+Requires-Dist: peft>=0.10; extra == "train"
+Provides-Extra: sherpa
+Requires-Dist: sherpa-onnx>=1.12; extra == "sherpa"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff<0.18,>=0.15; extra == "dev"
+Dynamic: license-file
+
+# voiceio
+
+[![CI](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml/badge.svg)](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![Python](https://img.shields.io/pypi/pyversions/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Voice dictation for Linux that learns you.** Local, private, open source, and it fine-tunes itself on your own voice.
+
+[![voiceio: dictation that learns you](https://voiceio.dev/og.png)](https://voiceio.dev)
+
+**[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
+
+- **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
+- **Runs on your machine.** Whisper decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
+
+## Install
+
+**With a coding agent.** Paste this into Claude Code, Codex or any agent with a shell:
+
+```text
+Install voiceio on this machine following https://voiceio.dev/llms.txt. Ask me which hotkey I want and whether to keep my recordings on this computer so voiceio can learn my voice. Finish with voiceio doctor and fix whatever it reports.
+```
+
+**By hand:**
+
+```bash
+sudo apt install pipx build-essential python3-dev portaudio19-dev ibus gir1.2-ibus-1.0 python3-gi   # Debian/Ubuntu
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject   # Fedora
+sudo pacman -S python-pipx base-devel portaudio ibus python-gobject                                   # Arch
+
+pipx install 'python-voiceio[desktop]'
+voiceio setup        # model, hotkey, autostart
+```
+
+Then press your hotkey, speak, and press it again. `voiceio doctor` shows what works and `voiceio doctor --fix` repairs what it can. NixOS, other extras and installing from source: [docs/linux.md](docs/linux.md). Agent runbook: [INSTALL.md](INSTALL.md).
+
+## Make it yours
+
+```bash
+voiceio vocab add Kalshi              # a name, recognized from the next dictation
+voiceio corrections add kalchi Kalshi # fix whatever still comes out wrong
+voiceio learn schedule on             # learn from your recordings while the machine is idle
+voiceio learn status                  # what it learned and how each model scores
+```
+
+Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+
+## Configure
+
+Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.
+
+## Docs
+
+| | |
+|---|---|
+| [Learning your voice](docs/learning.md) | Vocabulary, corrections, labeling, fine-tuning, evaluation, schedule |
+| [Choosing a model](docs/models.md) | Whisper sizes, Parakeet, whisper.cpp servers, licenses |
+| [Commands](docs/commands.md) | Every `voiceio` command |
+| [Your data](docs/data.md) | What is stored where, and what is off by default |
+| [Phone dictation](docs/phone.md) | Run voiceio headless on a home server |
+| [Linux support and troubleshooting](docs/linux.md) | Desktops, backends, NixOS, fixes |
+| [Comparisons](https://voiceio.dev/vs/) | voiceio vs Voxtype, Wispr Flow, Superwhisper, Dragon and others |
+
+## Roadmap
+
+- **Unbounded vocabulary**: a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
+- **GPU on AMD and Intel**: let setup run a Vulkan whisper.cpp server for you.
+- **Typing without IBus on GNOME and KDE**: a libei backend.
+- **Distro packages**: AUR, .deb and .rpm.
+- **One model everywhere**: sync your fine-tune across your machines.
+
+## Contributing
+
+Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
+
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- Ideas borrowed with thanks: modifier release, paste keys and media pausing from [Voxtype](https://github.com/peteonrails/voxtype); the landing page's look from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
+## License
+
+MIT. Model weights are not part of voiceio and carry their own licenses (see [docs/models.md](docs/models.md)).

python_voiceio-1.6.0/README.md

@@ -0,0 +1,85 @@
+# voiceio
+
+[![CI](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml/badge.svg)](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![Python](https://img.shields.io/pypi/pyversions/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Voice dictation for Linux that learns you.** Local, private, open source, and it fine-tunes itself on your own voice.
+
+[![voiceio: dictation that learns you](https://voiceio.dev/og.png)](https://voiceio.dev)
+
+**[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
+
+- **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
+- **Runs on your machine.** Whisper decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
+
+## Install
+
+**With a coding agent.** Paste this into Claude Code, Codex or any agent with a shell:
+
+```text
+Install voiceio on this machine following https://voiceio.dev/llms.txt. Ask me which hotkey I want and whether to keep my recordings on this computer so voiceio can learn my voice. Finish with voiceio doctor and fix whatever it reports.
+```
+
+**By hand:**
+
+```bash
+sudo apt install pipx build-essential python3-dev portaudio19-dev ibus gir1.2-ibus-1.0 python3-gi   # Debian/Ubuntu
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject   # Fedora
+sudo pacman -S python-pipx base-devel portaudio ibus python-gobject                                   # Arch
+
+pipx install 'python-voiceio[desktop]'
+voiceio setup        # model, hotkey, autostart
+```
+
+Then press your hotkey, speak, and press it again. `voiceio doctor` shows what works and `voiceio doctor --fix` repairs what it can. NixOS, other extras and installing from source: [docs/linux.md](docs/linux.md). Agent runbook: [INSTALL.md](INSTALL.md).
+
+## Make it yours
+
+```bash
+voiceio vocab add Kalshi              # a name, recognized from the next dictation
+voiceio corrections add kalchi Kalshi # fix whatever still comes out wrong
+voiceio learn schedule on             # learn from your recordings while the machine is idle
+voiceio learn status                  # what it learned and how each model scores
+```
+
+Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+
+## Configure
+
+Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.
+
+## Docs
+
+| | |
+|---|---|
+| [Learning your voice](docs/learning.md) | Vocabulary, corrections, labeling, fine-tuning, evaluation, schedule |
+| [Choosing a model](docs/models.md) | Whisper sizes, Parakeet, whisper.cpp servers, licenses |
+| [Commands](docs/commands.md) | Every `voiceio` command |
+| [Your data](docs/data.md) | What is stored where, and what is off by default |
+| [Phone dictation](docs/phone.md) | Run voiceio headless on a home server |
+| [Linux support and troubleshooting](docs/linux.md) | Desktops, backends, NixOS, fixes |
+| [Comparisons](https://voiceio.dev/vs/) | voiceio vs Voxtype, Wispr Flow, Superwhisper, Dragon and others |
+
+## Roadmap
+
+- **Unbounded vocabulary**: a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
+- **GPU on AMD and Intel**: let setup run a Vulkan whisper.cpp server for you.
+- **Typing without IBus on GNOME and KDE**: a libei backend.
+- **Distro packages**: AUR, .deb and .rpm.
+- **One model everywhere**: sync your fine-tune across your machines.
+
+## Contributing
+
+Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
+
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- Ideas borrowed with thanks: modifier release, paste keys and media pausing from [Voxtype](https://github.com/peteonrails/voxtype); the landing page's look from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
+## License
+
+MIT. Model weights are not part of voiceio and carry their own licenses (see [docs/models.md](docs/models.md)).

{python_voiceio-1.4.0 → python_voiceio-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "1.4.0"
+version = "1.6.0"
 description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"

python_voiceio-1.6.0/python_voiceio.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: python-voiceio
+Version: 1.6.0
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
+Author: Hugo Montenegro
+License-Expression: MIT
+Project-URL: Homepage, https://voiceio.dev/
+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,dictation,wayland,ibus
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: onnxruntime>=1.16.0
+Requires-Dist: wordfreq>=3.0
+Provides-Extra: desktop
+Requires-Dist: sounddevice>=0.4.6; extra == "desktop"
+Requires-Dist: evdev>=1.6.0; sys_platform == "linux" and extra == "desktop"
+Requires-Dist: pynput>=1.7.6; extra == "desktop"
+Requires-Dist: pystray>=0.19; extra == "desktop"
+Requires-Dist: Pillow>=10.0; extra == "desktop"
+Provides-Extra: linux
+Requires-Dist: sounddevice>=0.4.6; extra == "linux"
+Requires-Dist: evdev>=1.6.0; sys_platform == "linux" and extra == "linux"
+Requires-Dist: pynput>=1.7.6; extra == "linux"
+Requires-Dist: pystray>=0.19; extra == "linux"
+Requires-Dist: Pillow>=10.0; extra == "linux"
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.9; extra == "server"
+Provides-Extra: tts
+Requires-Dist: piper-tts>=1.3.0; extra == "tts"
+Requires-Dist: edge-tts>=6.1.0; extra == "tts"
+Provides-Extra: train
+Requires-Dist: torch>=2.2; extra == "train"
+Requires-Dist: transformers>=4.40; extra == "train"
+Requires-Dist: peft>=0.10; extra == "train"
+Provides-Extra: sherpa
+Requires-Dist: sherpa-onnx>=1.12; extra == "sherpa"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff<0.18,>=0.15; extra == "dev"
+Dynamic: license-file
+
+# voiceio
+
+[![CI](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml/badge.svg)](https://github.com/Hugo0/voiceio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![Python](https://img.shields.io/pypi/pyversions/python-voiceio)](https://pypi.org/project/python-voiceio/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Voice dictation for Linux that learns you.** Local, private, open source, and it fine-tunes itself on your own voice.
+
+[![voiceio: dictation that learns you](https://voiceio.dev/og.png)](https://voiceio.dev)
+
+**[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
+
+- **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
+- **Runs on your machine.** Whisper decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
+
+## Install
+
+**With a coding agent.** Paste this into Claude Code, Codex or any agent with a shell:
+
+```text
+Install voiceio on this machine following https://voiceio.dev/llms.txt. Ask me which hotkey I want and whether to keep my recordings on this computer so voiceio can learn my voice. Finish with voiceio doctor and fix whatever it reports.
+```
+
+**By hand:**
+
+```bash
+sudo apt install pipx build-essential python3-dev portaudio19-dev ibus gir1.2-ibus-1.0 python3-gi   # Debian/Ubuntu
+sudo dnf install pipx gcc gcc-c++ make python3-devel portaudio-devel ibus ibus-libs python3-gobject   # Fedora
+sudo pacman -S python-pipx base-devel portaudio ibus python-gobject                                   # Arch
+
+pipx install 'python-voiceio[desktop]'
+voiceio setup        # model, hotkey, autostart
+```
+
+Then press your hotkey, speak, and press it again. `voiceio doctor` shows what works and `voiceio doctor --fix` repairs what it can. NixOS, other extras and installing from source: [docs/linux.md](docs/linux.md). Agent runbook: [INSTALL.md](INSTALL.md).
+
+## Make it yours
+
+```bash
+voiceio vocab add Kalshi              # a name, recognized from the next dictation
+voiceio corrections add kalchi Kalshi # fix whatever still comes out wrong
+voiceio learn schedule on             # learn from your recordings while the machine is idle
+voiceio learn status                  # what it learned and how each model scores
+```
+
+Scheduled learning runs daily or weekly at a time you pick, only on an idle machine on mains power, with a notification you can stop. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
+
+## Configure
+
+Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.
+
+## Docs
+
+| | |
+|---|---|
+| [Learning your voice](docs/learning.md) | Vocabulary, corrections, labeling, fine-tuning, evaluation, schedule |
+| [Choosing a model](docs/models.md) | Whisper sizes, Parakeet, whisper.cpp servers, licenses |
+| [Commands](docs/commands.md) | Every `voiceio` command |
+| [Your data](docs/data.md) | What is stored where, and what is off by default |
+| [Phone dictation](docs/phone.md) | Run voiceio headless on a home server |
+| [Linux support and troubleshooting](docs/linux.md) | Desktops, backends, NixOS, fixes |
+| [Comparisons](https://voiceio.dev/vs/) | voiceio vs Voxtype, Wispr Flow, Superwhisper, Dragon and others |
+
+## Roadmap
+
+- **Unbounded vocabulary**: a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
+- **GPU on AMD and Intel**: let setup run a Vulkan whisper.cpp server for you.
+- **Typing without IBus on GNOME and KDE**: a libei backend.
+- **Distro packages**: AUR, .deb and .rpm.
+- **One model everywhere**: sync your fine-tune across your machines.
+
+## Contributing
+
+Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
+
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- Ideas borrowed with thanks: modifier release, paste keys and media pausing from [Voxtype](https://github.com/peteonrails/voxtype); the landing page's look from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
+## License
+
+MIT. Model weights are not part of voiceio and carry their own licenses (see [docs/models.md](docs/models.md)).

{python_voiceio-1.4.0 → python_voiceio-1.6.0}/python_voiceio.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ tests/test_audio_source.py
 tests/test_backend_probes.py
 tests/test_cli.py
 tests/test_clipboard_read.py
+tests/test_clipboard_typer.py
 tests/test_commands.py
 tests/test_concurrency_lockdown.py
 tests/test_config.py
@@ -42,6 +43,8 @@ tests/test_learn_review.py
 tests/test_learn_targets.py
 tests/test_llm.py
 tests/test_llm_api.py
+tests/test_media.py
+tests/test_modifier_guard.py
 tests/test_numbers.py
 tests/test_pipeline.py
 tests/test_platform.py
@@ -84,6 +87,7 @@ voiceio/hints.py
 voiceio/history.py
 voiceio/llm.py
 voiceio/llm_api.py
+voiceio/media.py
 voiceio/numbers.py
 voiceio/pidlock.py
 voiceio/platform.py
@@ -189,6 +193,7 @@ voiceio/typers/collecting.py
 voiceio/typers/fcitx_bridge.py
 voiceio/typers/ibus.py
 voiceio/typers/manager.py
+voiceio/typers/modifier_guard.py
 voiceio/typers/pynput_type.py
 voiceio/typers/wtype.py
 voiceio/typers/xdotool.py

{python_voiceio-1.4.0 → python_voiceio-1.6.0}/tests/test_clipboard_read.py

@@ -171,3 +171,35 @@ def test_copy_text_wayland_falls_back_to_wl_copy():
         from voiceio.clipboard_read import copy_text
         assert copy_text("hello") is True
     assert calls == ["xclip", "wl-copy"]
+
+
+def test_read_clipboard_keeps_text_exact_and_skips_primary():
+    """Restoring needs the clipboard byte for byte, never the mouse selection."""
+    with patch("voiceio.clipboard_read.detect", return_value=_mock_platform(display_server="x11")), \
+         patch("shutil.which", return_value="/usr/bin/xclip"), \
+         patch("subprocess.run") as mock_run:
+        mock_run.return_value = MagicMock(returncode=0, stdout="  two lines\nhere\n")
+        from voiceio.clipboard_read import read_clipboard
+        assert read_clipboard() == "  two lines\nhere\n"
+        assert mock_run.call_args[0][0] == ["xclip", "-o", "-selection", "clipboard"]
+
+
+def test_read_clipboard_wayland_falls_back_to_wl_paste():
+    with patch("voiceio.clipboard_read.detect", return_value=_mock_platform(display_server="wayland")), \
+         patch("shutil.which", return_value="/usr/bin/tool"), \
+         patch("subprocess.run") as mock_run:
+        mock_run.side_effect = [
+            MagicMock(returncode=1, stdout=""),
+            MagicMock(returncode=0, stdout="wayland text"),
+        ]
+        from voiceio.clipboard_read import read_clipboard
+        assert read_clipboard() == "wayland text"
+        assert mock_run.call_args[0][0] == ["wl-paste", "--no-newline"]
+
+
+def test_read_clipboard_empty_is_none():
+    with patch("voiceio.clipboard_read.detect", return_value=_mock_platform(display_server="x11")), \
+         patch("shutil.which", return_value="/usr/bin/xclip"), \
+         patch("subprocess.run", return_value=MagicMock(returncode=0, stdout="")):
+        from voiceio.clipboard_read import read_clipboard
+        assert read_clipboard() is None

python_voiceio-1.6.0/tests/test_clipboard_typer.py

@@ -0,0 +1,204 @@
+"""Clipboard typer: configurable paste keystroke and clipboard restore."""
+from __future__ import annotations
+
+import subprocess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from voiceio import config
+from voiceio.typers import clipboard as clip_mod, typer_options
+from voiceio.typers.clipboard import ClipboardTyper, parse_paste_keys, paste_command
+
+
+@pytest.mark.parametrize("spec,expected", [
+    ("ctrl+v", (["ctrl"], "v")),
+    ("Ctrl + Shift + V", (["ctrl", "shift"], "v")),
+    ("shift+insert", (["shift"], "insert")),
+])
+def test_parse_paste_keys(spec, expected):
+    assert parse_paste_keys(spec) == expected
+
+
+@pytest.mark.parametrize("spec", ["ctrl+q", "hyper+v", "ctrl+ctrl+v", ""])
+def test_unknown_paste_keys_fall_back_to_ctrl_v(spec, caplog):
+    assert parse_paste_keys(spec) == (["ctrl"], "v")
+    assert "paste_keys" in caplog.text
+
+
+def test_paste_command_per_tool():
+    mods, key = ["ctrl", "shift"], "v"
+    assert paste_command("ydotool", mods, key) == \
+        ["ydotool", "key", "29:1", "42:1", "47:1", "47:0", "42:0", "29:0"]
+    assert paste_command("wtype", mods, key) == \
+        ["wtype", "-M", "ctrl", "-M", "shift", "-k", "v", "-m", "shift", "-m", "ctrl"]
+    assert paste_command("xdotool", mods, key) == \
+        ["xdotool", "key", "--clearmodifiers", "ctrl+shift+v"]
+    assert paste_command("xdotool", ["shift"], "insert") == \
+        ["xdotool", "key", "--clearmodifiers", "shift+Insert"]
+
+
+def _wayland_typer(monkeypatch, tool="ydotool", **kwargs) -> ClipboardTyper:
+    monkeypatch.setattr(clip_mod.sys, "platform", "linux")
+    monkeypatch.setenv("WAYLAND_DISPLAY", "wayland-0")
+    available = {"wl-copy", tool}
+    monkeypatch.setattr(clip_mod.shutil, "which",
+                        lambda name: f"/usr/bin/{name}" if name in available else None)
+    return ClipboardTyper(**kwargs)
+
+
+@pytest.mark.parametrize("tool,expected", [
+    ("ydotool", ["ydotool", "key", "29:1", "42:1", "47:1", "47:0", "42:0", "29:0"]),
+    ("wtype", ["wtype", "-M", "ctrl", "-M", "shift", "-k", "v", "-m", "shift", "-m", "ctrl"]),
+])
+def test_configured_keys_are_what_gets_pressed(monkeypatch, tool, expected):
+    typer = _wayland_typer(monkeypatch, tool, paste_keys="ctrl+shift+v")
+    with patch.object(clip_mod.subprocess, "run") as run:
+        typer.type_text("hello")
+    assert run.call_args_list[0].args[0] == ["wl-copy", "--"]
+    assert run.call_args_list[1].args[0] == expected
+
+
+def test_default_paste_is_ctrl_v(monkeypatch):
+    typer = _wayland_typer(monkeypatch)
+    with patch.object(clip_mod.subprocess, "run") as run:
+        typer.type_text("hello")
+    assert run.call_args_list[1].args[0] == ["ydotool", "key", "29:1", "47:1", "47:0", "29:0"]
+
+
+def test_failed_paste_releases_the_configured_modifiers(monkeypatch):
+    typer = _wayland_typer(monkeypatch, paste_keys="ctrl+shift+v")
+
+    def run(cmd, **kwargs):
+        if cmd[:2] == ["ydotool", "key"] and cmd[2].endswith(":1"):
+            raise subprocess.TimeoutExpired(cmd, 3)
+        return MagicMock(returncode=0)
+
+    with patch.object(clip_mod.subprocess, "run", side_effect=run) as mock_run, \
+         pytest.raises(subprocess.TimeoutExpired):
+        typer.type_text("hello")
+    assert mock_run.call_args.args[0] == ["ydotool", "key", "29:0", "42:0"]
+
+
+class FakeClipboard:
+    def __init__(self, text):
+        self.text = text
+        self.reads = 0
+        self.writes = []
+
+    def read(self):
+        self.reads += 1
+        return self.text
+
+    def copy(self, text):
+        self.writes.append(text)
+        self.text = text
+        return True
+
+
+@pytest.fixture
+def clipboard(monkeypatch):
+    board = FakeClipboard("user's own text\n")
+    monkeypatch.setattr(clip_mod.clipboard_read, "read_clipboard", board.read)
+    monkeypatch.setattr(clip_mod.clipboard_read, "copy_text", board.copy)
+    monkeypatch.setattr(clip_mod, "RESTORE_DELAY_SECS", 0.01)
+    return board
+
+
+def _copying_run(board):
+    """subprocess.run stand-in: wl-copy puts its input on the fake board."""
+    def run(cmd, input=None, **kwargs):
+        if cmd[0] == "wl-copy":
+            board.text = input.decode()
+        return MagicMock(returncode=0)
+    return run
+
+
+def _settle(typer):
+    """Wait for a scheduled restore (None: it already ran)."""
+    timer = typer._restore_timer
+    if timer is not None:
+        timer.join(timeout=2)
+
+
+def _paste(typer, board, *texts):
+    """Paste each text, then let the restore timer run."""
+    with patch.object(clip_mod.subprocess, "run", side_effect=_copying_run(board)):
+        for text in texts:
+            typer.type_text(text)
+    _settle(typer)
+
+
+def test_restores_the_users_clipboard_after_pasting(monkeypatch, clipboard):
+    typer = _wayland_typer(monkeypatch, restore_clipboard=True)
+    _paste(typer, clipboard, "dictated")
+    assert clipboard.writes == ["user's own text\n"]
+
+
+def test_streaming_burst_saves_once_and_restores_once(monkeypatch, clipboard):
+    typer = _wayland_typer(monkeypatch, restore_clipboard=True)
+    monkeypatch.setattr(clip_mod, "RESTORE_DELAY_SECS", 5)
+    with patch.object(clip_mod.subprocess, "run", side_effect=_copying_run(clipboard)):
+        typer.type_text("one ")
+        typer.type_text("two")
+    assert clipboard.reads == 1           # saved before the first paste only
+    typer._restore_timer.cancel()
+    typer._restore_saved(typer._restore_seq)
+    assert clipboard.writes == ["user's own text\n"]
+
+
+def test_superseded_restore_does_nothing(monkeypatch, clipboard):
+    typer = _wayland_typer(monkeypatch, restore_clipboard=True)
+    typer._saved, typer._pasted, typer._restore_seq = "old", "x", 2
+    clipboard.text = "x"
+    typer._restore_saved(1)
+    assert clipboard.writes == []
+
+
+def test_no_restore_over_something_copied_since(monkeypatch, clipboard):
+    typer = _wayland_typer(monkeypatch, restore_clipboard=True)
+
+    def run(cmd, input=None, **kwargs):
+        clipboard.text = "copied by the user meanwhile"
+        return MagicMock(returncode=0)
+
+    with patch.object(clip_mod.subprocess, "run", side_effect=run):
+        typer.type_text("dictated")
+    _settle(typer)
+    assert clipboard.writes == []
+
+
+def test_empty_clipboard_is_left_with_the_transcript(monkeypatch, clipboard):
+    clipboard.text = None
+    typer = _wayland_typer(monkeypatch, restore_clipboard=True)
+    _paste(typer, clipboard, "dictated")
+    assert clipboard.writes == []
+
+
+def test_restore_disabled_never_reads_the_clipboard(monkeypatch, clipboard):
+    typer = _wayland_typer(monkeypatch)
+    with patch.object(clip_mod.subprocess, "run"):
+        typer.type_text("dictated")
+    assert clipboard.reads == 0
+    assert typer._restore_timer is None
+
+
+@pytest.mark.parametrize("copy,notify,expected", [
+    ("off", False, True),
+    ("final", False, False),     # the transcript is meant to stay on the clipboard
+    ("live", False, False),
+    ("off", True, False),        # the notification says "copied to clipboard"
+])
+def test_restore_only_when_nothing_keeps_the_transcript(copy, notify, expected):
+    cfg = config.Config()
+    cfg.output.copy_to_clipboard = copy
+    cfg.feedback.notify_clipboard = notify
+    assert typer_options(cfg)["restore_clipboard"] is expected
+
+
+def test_options_reach_the_clipboard_typer(linux_wayland_gnome):
+    from voiceio.typers import create_typer_backend
+    typer = create_typer_backend("clipboard", linux_wayland_gnome,
+                                 paste_keys="shift+insert", restore_clipboard=True)
+    assert (typer._paste_mods, typer._paste_key) == (["shift"], "insert")
+    assert typer._restore_clipboard is True