python-voiceio 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

{python_voiceio-1.0.0.dist-info → python_voiceio-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.0.0
+Version: 1.2.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -140,7 +140,7 @@ uv run voiceio setup      # also links voiceio into ~/.local/bin
 
 ## Your data
 
-Everything voiceio keeps is in three directories (they follow `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_DATA_HOME`). Files are created `0600`, directories `0700`. Nothing is uploaded.
+Everything voiceio keeps is in three directories (they follow `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_DATA_HOME`). Files are created `0600`, directories `0700`. Nothing is uploaded. Recordings, decode traces and window titles are **off unless you turn them on** — `voiceio setup` asks whether to keep recordings so voiceio can learn your voice. Logs record sizes and timings, never your words.
 
 | Path | Holds | Retention |
 |---|---|---|
@@ -150,14 +150,13 @@ Everything voiceio keeps is in three directories (they follow `XDG_CONFIG_HOME`,
 | `vocab_stats.json` | Per-term usage counts used to rank the vocabulary | Rebuilt as you dictate |
 | `corrections.json` | Find/replace rules (`post grass` → `PostgreSQL`) | — |
 | `flagged.txt` | Words flagged with the "correct that" voice command, for review | — |
-| `snapshots/` | Copies of corrections + vocabulary from before 1.0's cleanup (safe to delete) | Last 8 kept |
+| `snapshots/` | Copies of corrections + vocabulary from before 1.0 (safe to delete) | — |
 | `consent.json` | Whether you allowed cloud LLM calls (text only) | — |
 | `hints.json` | Which CLI tips you have already seen | — |
 | **`~/.local/state/voiceio/`** | *What you said* | |
-| `history.jsonl` | Every committed transcript: time, raw and final text, focused-window title | `[history] enabled`, `max_entries`, `max_age_days` (0 = keep forever) |
-| `recordings/*.wav` | The audio of each utterance, for `voiceio learn` | `[data] retain_audio`, `max_audio_mb` (default 4096), `min_free_gb` (default 5) |
-| `streaming_trace.jsonl`, `postcorrect_pairs.jsonl` | Per-pass decode traces and LLM before/after pairs | `[data] capture_intermediates`; each capped at 64 MB |
-| `corrections_audit.jsonl` | When each correction rule fired (shows which rules earn their keep) | — |
+| `history.jsonl` | Every committed transcript: time, raw and final text (and the focused-window title with `[data] capture_context`) | `[history] enabled`, `max_entries`, `max_age_days` (0 = keep forever) |
+| `recordings/*.wav` | The audio of each utterance, for `voiceio learn` — **opt-in** | `[data] retain_audio` (default off), `max_audio_mb` (default 4096), `min_free_gb` (default 5) |
+| `streaming_trace.jsonl`, `postcorrect_pairs.jsonl` | Per-pass decode text and timings, LLM before/after pairs — **opt-in**, for debugging | `[data] capture_intermediates` (default off); each capped at 64 MB |
 | `voiceio.log`, `worker.log`, `ibus-engine-stderr.log` | Logs | `voiceio.log` rotates at 2 MB × 3 |
 | **`~/.local/share/voiceio/learn/`** | *Personalization corpus* (only exists once you run `voiceio learn`) | Never pruned; delete freely |
 | `labels.jsonl` | Reference transcripts from the teacher model or your review | — |
@@ -191,6 +190,7 @@ voiceio learn eval       # score the current model on your held-out clips: WER a
 voiceio learn train      # LoRA fine-tune (needs the `train` extra; decoder-only on CPU, --full on a GPU)
 voiceio learn promote <run>   # dictate with the fine-tune; `voiceio learn rollback` undoes it
 voiceio learn maintain   # later: label what's new, and once 50+ clips piled up, retrain and compare
+voiceio learn schedule on   # …or let it run `maintain` every night, and notify you when a model wins
 ```
 
 Labeling, training and offline eval run in an idle-priority cgroup, so they never slow dictation down. Everything stays on your machine unless you choose `train --remote`.
@@ -292,7 +292,7 @@ There is a best-effort pynput path for both (hotkeys and typing, no live preview
 | Hotkey does nothing on Wayland | `voiceio doctor --fix` installs the keyboard udev rule, or bind `voiceio toggle` in your compositor |
 | `sounddevice is not installed` | You installed without the desktop extra: `pipx install --force 'python-voiceio[desktop]'` |
 | evdev fails to build | Install a C toolchain and Python headers (see Quickstart), then reinstall |
-| Too slow | `voiceio doctor` shows your real stop→text; turn off cloud postcorrect, or `voiceio models use small` (or a GPU with `large-v3-turbo`) |
+| Too slow | `voiceio doctor` shows your real stop→text. Turn off cloud postcorrect; use `voiceio models use small` (or a GPU with `large-v3-turbo`); or narrow the beam of the passes you keep: on the author's 44 clips `[model] beam_size = 2` matched the default 5 (WER 4.9% vs 5.4%, vocabulary 28/32 vs 29/32) while decoding faster; greedy (`1`) lost vocabulary (26/32). Measure on yours: `voiceio learn eval --beam 2` |
 | Words come out wrong in a pattern | `voiceio learn eval --pipeline` and `voiceio corrections audit` show which stage or rule did it |
 | Start over | `voiceio uninstall`, then `voiceio setup` |
 
@@ -300,8 +300,8 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 ## Roadmap
 
-- **A landing page** — voiceio as local, open-source, private dictation that learns from you.
-- **Continuous learning** — `learn maintain` on a timer: label new dictation while idle, retrain when enough piles up, and promote only what wins on your held-out clips.
+- **A landing page** — voiceio as local, open-source, private dictation that learns from you. A draft is in [`site/index.html`](site/index.html), ready for GitHub Pages.
+- **Hands-off promotion** — `learn schedule` already retrains nightly and tells you when a model wins; next is switching to it automatically, with one-command rollback.
 - **Unbounded vocabulary** — move to a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
 - **One model everywhere** — sync your fine-tune to your phone server and laptops, peer to peer.
 

{python_voiceio-1.0.0.dist-info → python_voiceio-1.2.0.dist-info}/RECORD

@@ -1,17 +1,18 @@
-python_voiceio-1.0.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+python_voiceio-1.2.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=MpAT5hgNoHnTtG1XRD_GV_A7QrHVU6vJjGSw_8qMGA4,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=U2NuunPzwK5dnqoKOHyQaFGkThQ7wTCoPJDXWHcs1cY,31369
+voiceio/app.py,sha256=_FfrMN1MFWk8H5KciGu2niJm3fZJlNR2Ju9mP9s5brk,31798
 voiceio/audio_source.py,sha256=rR6NRtNzmZ8uqmNPxareBWTJmuBaOxIGI5QINR_l-qc,9102
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
 voiceio/clipboard_read.py,sha256=lz75CkRGh7pyvO6xvoUmxJDl-Gwie1xlXQHK70PO84I,4261
 voiceio/commands.py,sha256=Jz-txXSw32Adf8B912M8CzQIh4UMmEKRCZBPXU4bBaU,6014
-voiceio/config.py,sha256=n2-PlVu-2aB9g8M-uLhS3lqVAotglCoMyZGsWWAPe3k,18965
+voiceio/config.py,sha256=2QrttnGz0Cc7fLrlmhLA0-Nfvz1jJv9ea4kfY6icOEI,19522
 voiceio/consent.py,sha256=3stv3iZvYl_Dt4GUe-GUVOHEGi-2fOl-QqF3pDjraS4,1862
 voiceio/corrections.py,sha256=IIRViwjL9kkMy26-1dd0DtTfT0Tiedn6pmmHoaeayMQ,10047
 voiceio/demo.py,sha256=jA282e7UWDwtP1IXT2bPHH5wl6eKdBNvOJcoNDWzZlQ,8766
+voiceio/display.py,sha256=ZGBNRjuvg3chkJjduyPJs4s5ZY5vqC_mcaov94PIPzo,5313
 voiceio/feedback.py,sha256=i1Hkd_bydOOQ8p19Bz4bYougjQtozKGLjfKc5DKRDT0,5711
-voiceio/health.py,sha256=p5y3DrAhvEWUind0yB27eQg5pTkp5hmKz11a6q3LjK4,20834
+voiceio/health.py,sha256=r0nMDozuhk1nZNpCiVhmezC_7P6ElQpaBB_IomzmXF8,22166
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
 voiceio/history.py,sha256=cD3Ysa39qt6uKbrcLeRQt-FOJcYCoqie4UNsUWF7DuM,5763
 voiceio/llm.py,sha256=cO2RHM2zHxTD4r5mFFNatB-pjOSl29Wx_I00f7ywYCw,9161
@@ -25,25 +26,25 @@ voiceio/privacy.py,sha256=FqnA9jx9RCqWW-i6Dh7JcT7vzz97kbUGyQEvsHLvpqc,573
 voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
 voiceio/recorder.py,sha256=k51Py6av0YFkc1ENXsrXuFIL3G9bmsAijGq3X5r7pG4,15734
 voiceio/retention.py,sha256=TH_D29EUYyzEPl5FK0q32mpsSk0-0bx56JwAH83FBHI,6272
-voiceio/service.py,sha256=LAXWwbQfX-MHOMl3fdlYWgDv9-Vazx8QIIsKYR2O5cA,12074
-voiceio/streaming.py,sha256=ieE17_gHdadbjf3ahzbvk70ebOc7fVrs_C5ElMfdKLg,28102
+voiceio/service.py,sha256=_cTb1AQ57cF8-eW3SKvDkCP46S5yJqhty1fe_eI8zbQ,14324
+voiceio/streaming.py,sha256=hKak7ULkZbkHl5Fw0SnnZsEK3alv2s8dcuCcyBzpIQY,24700
 voiceio/suggest.py,sha256=jX4bCpnddyrteKfRBPbnUgf-Rk5145LFaSTat0_Ll2E,4836
 voiceio/tokens.py,sha256=m5tusR3zEBX7fRKaDUj4z-DSv8NcMhE-02HviAziENQ,5710
 voiceio/ui.py,sha256=pwuH3zr9kMC7TovLwJwa3E3H8J5Fbt2VF4-DDTvqboQ,461
 voiceio/vad.py,sha256=VPeefjJ0Ml5hOuRE2V6BWoBXmzawxLB7if5UP3vBKiM,6030
 voiceio/vocab_stats.py,sha256=md_85Bs0UsM-tmSZDEyQFe0C7z4UnsZ5QSV5vuZ8A5w,5408
 voiceio/vocabulary.py,sha256=i2RRYGmT81tJcYhnZ4sVuVbmZjClqFZVlNUUFa35tuY,11351
-voiceio/watchdog.py,sha256=MSDFyE3jCPDXA45iVL6JoJcF0pnH3IY_9CnU7GMLAXs,7419
+voiceio/watchdog.py,sha256=UVwcvtdXaimbUmqlfQME_ZpEGIqvP0UjlIM2OBd3Tho,7351
 voiceio/wordfreq.py,sha256=PTAoaEUX1D2Y12jjd8A9cFTqsZkDDZt6eesBBL_4toA,3151
 voiceio/cli/__init__.py,sha256=vU6THxcynHLhdMisVBPEyig_m_EF_XrU2HXi6Tq4iSE,7713
 voiceio/cli/configcmd.py,sha256=YF7t-LkwEYEGH4qcO86xehWVX0LvltqxjDFpMF5ljjA,2858
 voiceio/cli/corrections.py,sha256=OBjgiOhtWlTQpQq0HLAvk5-EfKJ7NNt-hnNBHm7obEc,4247
 voiceio/cli/doctor.py,sha256=P8bOn4xedMistlKHhNeeGxRsmogV6jBVKc-CUbo0LXs,7769
 voiceio/cli/history.py,sha256=IWyFIozX5PUwtrU17JlkNea9nP_oKLsXfkxIVHjkfD0,1516
-voiceio/cli/learn.py,sha256=qhbbW-UP83ucziKHTUhlYZ361WzMiNfMksQgl9zFrzo,22456
+voiceio/cli/learn.py,sha256=cQ3HOf0LXybRf-40QA6Jvb54gy7rpCCz_2xavPJE7wk,24859
 voiceio/cli/models.py,sha256=fye_mHbsXLY11uRC1BCDlucCHPny9ftoehAeUJPMJv0,4263
-voiceio/cli/servicecmd.py,sha256=zPGMlq8InKLCNb2r8YmYKBAGgEe4t8ha78OeAih8Eck,3135
-voiceio/cli/uninstall.py,sha256=Qxgf32Yoikv36sawWBTtfWs3aGOG1BMY-JE7pHlc4Ys,8770
+voiceio/cli/servicecmd.py,sha256=hcaQD1NL38fvkrHtId1307MIgyi2O2xBP6YvG8CTngc,4219
+voiceio/cli/uninstall.py,sha256=Vqnq6-4hjhDrxqkU_1wtXkY5BU_Tqa-TjZA0Qpf12e4,8921
 voiceio/cli/vocab.py,sha256=lxxuSukefvIHV4fFSduCQQewXY0_Bvf5sDnG4bqLWH8,4418
 voiceio/core/__init__.py,sha256=K0b4duczohS3IrIMLp9fYhfb-GeuyQaOVH_8teYGsQM,277
 voiceio/core/bias.py,sha256=butCKgKlCFKsKXGmnqK-816wNmWGtf64E6k9QJEiTnA,3892
@@ -55,7 +56,7 @@ voiceio/core/decoders/catalog.py,sha256=L4zcwgNAe5LRDVv6KvwzReA25mJuJ8nPjOWimoFP
 voiceio/core/decoders/lanes.py,sha256=lkq7ue0Pbt-rirGd72T6_i77A6uJPD4PYzD-JPLRuWk,1452
 voiceio/core/decoders/sherpa.py,sha256=ceLPEGC2E1F2OUaPz9Fe74mJYzL8yXh5iYgSyeWZr6g,4338
 voiceio/core/decoders/whispercpp.py,sha256=IJvsdSrc324FuQ1JbqXu_fWUZP64JnIWX9fOxyL_oKM,3264
-voiceio/core/decoders/faster_whisper/__init__.py,sha256=NjxBTVvNIB4yosXzCzsZKWmGBEu81I-S7OuI8Ev2YG4,13035
+voiceio/core/decoders/faster_whisper/__init__.py,sha256=yZl1-kdyqrpgRQ5GnsckP4VkCORFfqv2eloGKW1ecaU,13172
 voiceio/core/decoders/faster_whisper/worker.py,sha256=x7hIrLygVIhrkzvDKN5n2deVF4QPX4_9tRKyQSNyvOk,7905
 voiceio/data/60-voiceio-uaccess.rules,sha256=X3DvKhkevKwDzKgYaA42GmpGlWh_orr8wei3mfl_SYo,397
 voiceio/data/__init__.py,sha256=kbyKP4Jaz3Q-rGkUPnVq5zo5d3dii254q7qIDCG4vHw,59
@@ -80,7 +81,7 @@ voiceio/learn/metrics.py,sha256=b2xWUzPpNpXHn6zgS1upPbEcpW3ExH9SmSLIUzPhStQ,5174
 voiceio/learn/review.py,sha256=p11kRY-PF9YhS7aYjcYpDUJavUn8OXXz4d6S-MGfCGE,4575
 voiceio/learn/store.py,sha256=MauWhGaI2drMbiChIZOblpPS_uVAw-1sNWGyGACHYw8,12816
 voiceio/learn/teacher.py,sha256=uF4hQkrdjv012TTBRSwrhQqqAeCFNoidABcrgzSVUoI,3696
-voiceio/learn/train.py,sha256=9vOV-sGlsaYxZ3Pbnmh0gdMZ24K3TtFMHBGOAK8oCxg,17473
+voiceio/learn/train.py,sha256=zTyftCsUV6hYy9WA8ftZtqjVbYJ-C7py0EoxavXWr7I,17628
 voiceio/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 voiceio/models/silero_vad.onnx,sha256=GhU6IvRQnikqlOZ9b5uF6N6yW0mIaCt-F0xlJ52HiOM,2327524
 voiceio/server/__init__.py,sha256=ybYb7CWgyMUhB-8AKypIWyMwCg17D3iNOaWOkqUd_8s,1751
@@ -89,12 +90,12 @@ voiceio/server/app.py,sha256=pHC2mmj5VOsgE6mbW_p9kQEEALwQDOS-f8fbByBr7ig,15772
 voiceio/server/config.py,sha256=BXcLNmZMlErLvD2E7D8_5zm3xk8KqzlMq1wMNXf9L-Q,5284
 voiceio/server/runtime.py,sha256=7Cv1kJNjRtJx8LfbXAfZbfGvo5XmYyq62udp3bjdq3s,12186
 voiceio/setup/__init__.py,sha256=cXNo-LYhkoVA6pEKcnaAKEGma_A9Aiqffa3VRvV6Jm8,430
-voiceio/setup/configfile.py,sha256=2ULtbyHNflhblJ52z9MqpJTR8ZiKTpjZQS2yBbtvXDk,4716
+voiceio/setup/configfile.py,sha256=H5MCW8Uyx1qL9bI0qfKErgA5JQlc6tDlKZy9J3kg04s,4876
 voiceio/setup/extras.py,sha256=NGk_uAWl4GQAPwRfw_0nEPsPvma7ics9DnZqjoHgCUY,9685
 voiceio/setup/hotkey.py,sha256=xlDp2vWzsF73wbpvPSrwaqgjtiWnv294nzjlvHy0Ets,6473
-voiceio/setup/noninteractive.py,sha256=0I_s2_tJ9moLY7z5WM4Ao9pXB_1dyGY5Eodxvofngrs,10331
+voiceio/setup/noninteractive.py,sha256=PF5dG6aOOYxdknbRGZD32xlv_kV2Mg8BRf_TfYI5bpY,10522
 voiceio/setup/speech.py,sha256=DahGBybPzkNryLjxtCkxojrUhECBksox2RKSwGr7a9I,7688
-voiceio/setup/steps.py,sha256=JW4-lW2_bXm4jvinhL2cFDvCrXtBmrNIbVYrYbRFzfg,26134
+voiceio/setup/steps.py,sha256=IXzP4zaeZg7EUAPNFnp1VQSbEyeW8PsKNJ6hpgfDSew,27688
 voiceio/setup/system.py,sha256=Cb1BJGCgGbZFAfqrS8eXRW2AKW7jNLq82DWWg4_fdAs,6019
 voiceio/setup/ui.py,sha256=h1gmerT_8EfWftSONUn5K5Ri19elNTRP2lwFAuxsGPc,13401
 voiceio/sounds/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -119,13 +120,13 @@ voiceio/typers/clipboard.py,sha256=8MJp3fEWCe3bvagqwevd3SgVVD830--AfEY0k87dkW0,7
 voiceio/typers/collecting.py,sha256=Tsuy-2B-6poYa-5pfrLVqDlS4ThyX71pLTr2hTl-Yws,2872
 voiceio/typers/fcitx_bridge.py,sha256=GxKDEOk-tsaXDbUh6uCCC7lA6OkMFvkqHojsqrg8ZU0,2635
 voiceio/typers/ibus.py,sha256=7Fyk2Figwa95ouiOa9gN6c5XTT6mBJkh1RmKdyXN3VM,10769
-voiceio/typers/manager.py,sha256=NyWuA-lJDiZ2Ft8qiukEFhsRqJ16tHZRmWckjLIh70I,14422
+voiceio/typers/manager.py,sha256=W7u3iJ8ErDRGWqIsyXJXzeOiW1-YCupvC4MIhJSf0Zw,14423
 voiceio/typers/pynput_type.py,sha256=Rzkixn08iaIqSCZ5vRybaHpn05lkx4FiEa_OakaiM1A,1951
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=e19GvDHL9GS-jgh_hzW3PGBFPCc4IJCWsBWEzU_LqGs,5934
-python_voiceio-1.0.0.dist-info/METADATA,sha256=86SXSQf0s7DmodzBvBIrzT-HtyHg7B1jEoR7ijlehoE,20494
-python_voiceio-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_voiceio-1.0.0.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
-python_voiceio-1.0.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-1.0.0.dist-info/RECORD,,
+python_voiceio-1.2.0.dist-info/METADATA,sha256=zEVw8vdKC4meGy8FxLLwba5SoZAb3LPu5OfTYlsusYo,21153
+python_voiceio-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_voiceio-1.2.0.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
+python_voiceio-1.2.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-1.2.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.2.0"

voiceio/app.py

@@ -36,6 +36,20 @@ class _State(enum.Enum):
 
 
 class VoiceIO:
+    @property
+    def _state(self) -> _State:
+        return self.__state
+
+    @_state.setter
+    def _state(self, value: _State) -> None:
+        self.__state = value
+        try:   # best-effort: only `service restart` reads it
+            tmp = config.STATE_PATH.with_suffix(".tmp")
+            tmp.write_text(value.value)
+            tmp.replace(config.STATE_PATH)
+        except OSError:
+            pass
+
     def __init__(self, cfg: config.Config):
         self.cfg = cfg
 
@@ -82,7 +96,7 @@ class VoiceIO:
 
         print(f"Loading model '{cfg.model.name}'...", end="", flush=True)
         t0 = time.monotonic()
-        self.transcriber = build_decoder(cfg.model)
+        self.decoder = build_decoder(cfg.model)
         print(f" ready ({time.monotonic() - t0:.1f}s)")
 
         # VAD, vocabulary, commands
@@ -119,7 +133,7 @@ class VoiceIO:
         # corrections, prompt history and text pipeline (same as the server).
         from voiceio.core.engine import Engine
         self.engine = Engine.from_config(
-            cfg, decoder=self.transcriber, commands=self._command_processor,
+            cfg, decoder=self.decoder, commands=self._command_processor,
             postcorrect=self._postcorrect, llm=self._llm,
         )
         self._corrections = self.engine.corrections
@@ -189,14 +203,14 @@ class VoiceIO:
         )
         self._watchdog = Watchdog(
             cfg,
-            transcriber=self.transcriber,
+            decoder=self.decoder,
             recorder=self.recorder,
             typers=self._typers,
             ibus=self._ibus,
             session=lambda: self._session,
             is_idle=self._is_idle,
             is_recording=lambda: self._state == _State.RECORDING,
-            on_transcriber_failed=self._on_transcriber_failed,
+            on_decoder_failed=self._on_decoder_failed,
             on_hotkey=self.on_hotkey,
             shutdown=self._shutdown,
         )
@@ -302,7 +316,7 @@ class VoiceIO:
             # Attempt recovery: try to restart worker, then start recording
             log.info("Attempting recovery from error state")
             try:
-                self.transcriber.recover()
+                self.decoder.recover()
                 self._state = _State.IDLE
                 tray.set_error(False)
                 self._do_start()
@@ -313,7 +327,7 @@ class VoiceIO:
             # The generation counter ensures the old finalizer exits cleanly.
             self._do_start()
 
-    def _on_transcriber_failed(self) -> None:
+    def _on_decoder_failed(self) -> None:
         """Watchdog: the worker could not be recovered."""
         with self._hotkey_lock:
             if self._state != _State.RECORDING:
@@ -708,9 +722,10 @@ class VoiceIO:
             if self._tts_engine:
                 self._tts_engine.shutdown()
             self.recorder.close_stream()
-            self.transcriber.close()
+            self.decoder.close()
             tray.stop()
             self._ibus.shutdown()
             self._pid_fd.close()
             PID_PATH.unlink(missing_ok=True)
+            config.STATE_PATH.unlink(missing_ok=True)
         log.info("voiceio stopped")

voiceio/cli/learn.py

@@ -63,6 +63,8 @@ def register(sub: argparse._SubParsersAction) -> None:
     e.add_argument("--pipeline", action="store_true",
                    help="no decoding: score what each text stage (corrections, numbers, "
                         "cloud postcorrect…) did to past dictations")
+    e.add_argument("--beam", type=int, default=None,
+                   help="beam width of the passes you keep (default: [model] beam_size)")
     e.add_argument("--speed", type=float, default=1.0,
                    help="streaming replay speed; >1 is faster but skews latency")
     e.set_defaults(func=cmd_eval)
@@ -84,6 +86,10 @@ def register(sub: argparse._SubParsersAction) -> None:
     mt.add_argument("--epochs", type=int, default=4)
     mt.set_defaults(func=cmd_maintain)
 
+    sc = lsub.add_parser("schedule", help="Run `maintain` every night (systemd timer)")
+    sc.add_argument("state", nargs="?", choices=("on", "off"), help="omit to show")
+    sc.set_defaults(func=cmd_schedule)
+
     pr = lsub.add_parser("promote", help="Use a trained model for dictation")
     pr.add_argument("run", help="run name under learn/models (see `learn status`)")
     pr.add_argument("--force", action="store_true",
@@ -176,6 +182,8 @@ def cmd_status(args: argparse.Namespace) -> None:
         print(f"models     {', '.join(runs)}")
     active = _cfg().model.name
     print(f"active     {active}")
+    from voiceio import service
+    print(f"nightly    {'on' if service.learn_timer_enabled() else 'off (voiceio learn schedule on)'}")
     promotable = _print_scores(ds, active, runs) if ds else None
     if promotable:
         nxt = f"promote {promotable}"
@@ -328,12 +336,12 @@ def cmd_eval(args: argparse.Namespace) -> None:
     if ds is None or not ds.exists():
         raise SystemExit("no dataset — run `voiceio learn build` first")
     _run_eval(args.model, ds, limit=args.limit, streaming=args.streaming, lanes=args.lanes,
-              freeze=args.freeze, speed=args.speed)
+              freeze=args.freeze, speed=args.speed, beam=args.beam)
 
 
 def _run_eval(model: str | None, ds: Path, *, limit: int | None = None,
               streaming: bool = False, lanes: int | None = None,
-              freeze: float | None = None, speed: float = 1.0):
+              freeze: float | None = None, speed: float = 1.0, beam: int | None = None):
     """Score `model` (default: the configured one) on `ds`; print and save."""
     from voiceio.core.bias import BiasProvider
     from voiceio.core.decoders import build_decoder
@@ -342,6 +350,8 @@ def _run_eval(model: str | None, ds: Path, *, limit: int | None = None,
     cfg = _cfg()
     if model:
         cfg.model.name = model
+    if beam:
+        cfg.model.beam_size = beam
     print(f"Loading {cfg.model.name}…", flush=True)
     # Offline scoring needs one lane; streaming mirrors the live setup.
     decoder = build_decoder(cfg.model, lanes=lanes if lanes is not None else
@@ -422,6 +432,12 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     _yield_cpu()
     from voiceio.learn import evaluate
     cmd_label(argparse.Namespace(teacher=None, limit=None, relabel=False))
+    from voiceio.learn import train
+    if missing := train.missing_train_deps():
+        # Labeling alone is worth it; retraining waits for the extra. Exit 0:
+        # a nightly timer must not fail every night over an optional install.
+        print(f"labeled; fine-tuning needs {', '.join(missing)}: {train.TRAIN_HINT}")
+        return
     labels = store.load_labels()
     labeled = {c.audio for c in store.clips() if c.audio in labels}
     ds = store.latest_dataset()
@@ -438,6 +454,33 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     print(f"\n{_cfg().model.name} → {run.name} on {ds.name}:\n{table}")
     print(f"better or equal on everything — `voiceio learn promote {run.name}`" if ok
           else "not better on everything — keeping the current model")
+    if ok:   # often runs unattended at night: say so where it will be seen
+        from voiceio import feedback
+        feedback.notify("VoiceIO: a better model is ready",
+                        f"Trained on your dictation. Use it: voiceio learn promote {run.name}",
+                        urgent=True)
+
+
+def cmd_schedule(args: argparse.Namespace) -> None:
+    from voiceio import config, service
+    if args.state == "on":
+        if not config.load().data.retain_audio:
+            print("note: [data] retain_audio is off, so there is nothing new to learn from;\n"
+                  "      turn it on with: voiceio config set data.retain_audio true")
+        from voiceio.learn import train
+        if missing := train.missing_train_deps():
+            print(f"note: until {', '.join(missing)} are installed it only labels new clips;\n"
+                  f"      to also retrain: {train.TRAIN_HINT}")
+        if not service.install_learn_timer():
+            raise SystemExit("could not enable the timer (needs systemd --user)")
+        print("on: every night ~03:30, `voiceio learn maintain` labels new dictation at idle "
+              "priority, retrains once 50+ clips are new, and tells you if the result is better. "
+              "It never switches models by itself.")
+    elif args.state == "off":
+        service.uninstall_learn_timer()
+        print("off")
+    else:
+        print("on" if service.learn_timer_enabled() else "off — enable: voiceio learn schedule on")
 
 
 def _scores(result) -> dict:

voiceio/cli/servicecmd.py

@@ -10,6 +10,8 @@ def register(sub: argparse._SubParsersAction) -> None:
     p.add_argument("action", nargs="?", default="status",
                    choices=["install", "uninstall", "start", "stop", "restart",
                             "status", "logs"])
+    p.add_argument("--now", action="store_true",
+                   help="stop/restart: don't wait for a dictation in progress to finish")
     p.add_argument("-f", "--follow", action="store_true", help="logs: follow")
     p.add_argument("-n", "--lines", type=int, default=50, help="logs: line count")
     p.set_defaults(func=_cmd_service)
@@ -61,6 +63,8 @@ def _cmd_service(args: argparse.Namespace) -> None:
             sys.exit(1)
 
     elif action in ("stop", "restart"):
+        if not getattr(args, "now", False):
+            wait_until_idle()
         try:
             subprocess.run(["systemctl", "--user", action, "voiceio.service"],
                            capture_output=True, timeout=10, check=True)
@@ -79,3 +83,25 @@ def _cmd_service(args: argparse.Namespace) -> None:
             subprocess.call(cmd)
         except KeyboardInterrupt:
             pass
+
+
+def wait_until_idle(timeout: float = 300.0, poll: float = 0.25) -> bool:
+    """Wait for the daemon to finish any dictation in progress (stopping it
+    mid-recording loses what was said). True once idle or not running."""
+    import time
+
+    from voiceio.config import STATE_PATH
+    deadline, told = time.monotonic() + timeout, False
+    while time.monotonic() < deadline:
+        try:
+            state = STATE_PATH.read_text().strip()
+        except OSError:
+            return True          # not running (or pre-1.1): nothing to wait for
+        if state in ("idle", "error"):
+            return True
+        if not told:
+            print(f"Waiting for the dictation in progress to finish ({state})…", flush=True)
+            told = True
+        time.sleep(poll)
+    print("Still busy; going ahead. (--now skips the wait.)", file=sys.stderr)
+    return False

voiceio/cli/uninstall.py

@@ -101,6 +101,9 @@ def _cmd_uninstall() -> None:
         if _service.CORRECT_TIMER_PATH.exists() or _service.CORRECT_SERVICE_PATH.exists():
             _service.uninstall_correct_timer()
             removed.append(str(_service.CORRECT_TIMER_PATH))
+        if _service.LEARN_TIMER_PATH.exists():
+            _service.uninstall_learn_timer()
+            removed.append(str(_service.LEARN_TIMER_PATH))
 
         # 2. Remove IBus component and launcher
         ibus_component = home / ".local" / "share" / "ibus" / "component" / "voiceio.xml"

voiceio/config.py

@@ -34,6 +34,9 @@ HISTORY_PATH = LOG_DIR / "history.jsonl"
 RECORDINGS_DIR = LOG_DIR / "recordings"
 LOG_PATH = LOG_DIR / "voiceio.log"
 PID_PATH = LOG_DIR / "voiceio.pid"
+# The daemon's state (idle/recording/finalizing), so `voiceio service
+# restart` can wait for a dictation to finish instead of killing it.
+STATE_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio.state"
 # Intermediate pipeline data kept for debugging/profiling and future training:
 # per-pass streaming decode traces and postcorrect before/after pairs. These
 # live in their own JSONL files (not the rotating log) so they survive.
@@ -76,6 +79,9 @@ class ModelConfig:
     # "modified_beam_search" (required for hotwords).
     decoding: str = ""
     vocabulary_file: str = ""  # path to vocabulary.txt
+    # Beam width of the passes whose text you keep (freezes and the final
+    # tail); interim previews are always greedy. 1 is greedy: faster stop.
+    beam_size: int = 5
     # Other languages you dictate in: a correction rule that would rewrite a
     # real word in one of these is flagged (e.g. ["es"] protects "harina").
     protect_languages: list[str] = field(default_factory=list)
@@ -218,20 +224,23 @@ class HealthConfig:
 class DataConfig:
     """Local data retention for diagnostics and self-improvement.
 
+    Opt-in: nothing here is kept unless you turn it on (`voiceio setup` asks).
     Everything stays on disk under ~/.local/state/voiceio/ — nothing is
     uploaded. retain_audio keeps a WAV per utterance so (audio, final text)
-    pairs accumulate for later analysis or fine-tuning.
+    pairs accumulate for `voiceio learn` to fine-tune on.
     """
-    retain_audio: bool = True
+    retain_audio: bool = False
     max_audio_mb: int = 4096   # prune oldest recordings beyond this
     # Never let retention squeeze the disk: skip saving and prune harder
     # when the filesystem has less than this much free space.
     min_free_gb: float = 5.0
-    capture_context: bool = True  # best-effort active-window title
+    # Active-window title, stored with each history row and given to the
+    # cloud pass as context when that is on.
+    capture_context: bool = False
     # Per-pass streaming decode traces + postcorrect before/after pairs
     # (streaming_trace.jsonl / postcorrect_pairs.jsonl) for debugging,
     # profiling, and future fine-tuning.
-    capture_intermediates: bool = True
+    capture_intermediates: bool = False
 
 
 @dataclass

voiceio/core/decoders/faster_whisper/__init__.py

@@ -93,6 +93,8 @@ class Transcriber:
     def __init__(self, cfg: ModelConfig):
         self._cfg = cfg
         self.name = f"faster-whisper:{cfg.name}"
+        if cfg.beam_size != 5:   # scored separately from the default
+            self.name += f"@beam{cfg.beam_size}"
         if _PROMPTLESS.search(cfg.name):
             self.capabilities = Capabilities(bias=BiasMode.NONE)
         self._proc: subprocess.Popen | None = None
@@ -205,7 +207,7 @@ class Transcriber:
 
             audio = normalize_audio(audio)
             audio_b64 = base64.b64encode(audio.tobytes()).decode("ascii")
-            req = {"audio_b64": audio_b64, "options": {"beam_size": 5 if final else 1}}
+            req = {"audio_b64": audio_b64, "options": {"beam_size": self._cfg.beam_size if final else 1}}
             # Cap the combined prompt. initial_prompt (recent transcripts) and
             # `context` (streaming's frozen-text tail) are both bounded in CHARS
             # by their callers, but nothing bounded their SUM in tokens — and

voiceio/display.py

@@ -0,0 +1,150 @@
+"""What a streaming session has put on screen, and how to change it.
+
+Text reaches the focused app one of two ways. An IBus typer shows a preedit
+(an underlined preview the app can't see yet) and commits once; the session
+just replaces the preview. A keystroke typer has already typed every word it
+showed, so a revision must be applied as an edit: append when the new text
+extends what's there, and on the final pass a character-level diff that
+deletes back to the first difference and retypes the rest.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import time
+from typing import TYPE_CHECKING
+
+from voiceio.privacy import describe_transcript
+from voiceio.typers.base import StreamingTyper
+
+if TYPE_CHECKING:
+    from voiceio.typers.base import TyperBackend
+
+log = logging.getLogger(__name__)
+DELETE_SETTLE_SECS = 0.05  # delay between delete and type for ydotool reliability
+
+
+def _common_prefix_len(a: str, b: str) -> int:
+    """Length of the longest common prefix between two strings."""
+    limit = min(len(a), len(b))
+    for i in range(limit):
+        if a[i] != b[i]:
+            return i
+    return limit
+
+
+def _clean_word(w: str) -> str:
+    """Strip punctuation for fuzzy word matching."""
+    return re.sub(r'[^\w]', '', w).lower()
+
+
+def _word_match_len(old_words: list[str], new_words: list[str]) -> int:
+    """Count matching leading words, ignoring punctuation/case."""
+    count = 0
+    for o, n in zip(old_words, new_words):
+        if _clean_word(o) == _clean_word(n):
+            count += 1
+        else:
+            break
+    return count
+
+
+class TypedText:
+    """The text a session has shown through `typer`."""
+
+    def __init__(self, typer: TyperBackend):
+        self.typer = typer
+        self.text = ""
+
+    def commit_preview(self) -> None:
+        """Commit a preview that only exists as a preedit — when the final
+        pass yields nothing, so a decode timeout doesn't drop it. Keystroke
+        typers already typed it."""
+        if self.text and isinstance(self.typer, StreamingTyper):
+            log.warning("Final transcription empty; committing interim preedit text (%d chars)",
+                        len(self.text))
+            self.typer.commit_text(self.text)
+
+    def clear(self) -> None:
+        """Take back everything shown (a voice command discarded it)."""
+        if isinstance(self.typer, StreamingTyper):
+            self.typer.clear_preedit()
+        elif self.text:
+            self.typer.delete_chars(len(self.text))
+        self.text = ""
+
+    def apply(self, new_text: str, final: bool = False) -> None:
+        """Show `new_text` in place of what is on screen.
+
+        With StreamingTyper (IBus): use preedit during streaming, commit on final.
+        Without: append-only via word-level matching, char-level diff on final.
+        """
+        old = self.text
+
+        # Preedit path: trivial, just replace the preview text
+        if isinstance(self.typer, StreamingTyper):
+            if final:
+                self.typer.commit_text(new_text)
+                self.text = new_text
+                log.debug("Preedit commit: %s", describe_transcript(new_text))
+            elif new_text != old:
+                self.typer.update_preedit(new_text)
+                self.text = new_text
+                log.debug("Preedit update: %s", describe_transcript(new_text))
+            return
+
+        if new_text == old:
+            return
+
+        if final:
+            self._final_correction(new_text)
+            return
+
+        if not old:
+            # First transcription, just type it
+            self.typer.type_text(new_text)
+            self.text = new_text
+            log.debug("Initial: %s", describe_transcript(new_text))
+            return
+
+        # Short text: allow full replacement (Whisper still warming up)
+        if len(old.split()) <= 2:
+            self.typer.delete_chars(len(old))
+            time.sleep(DELETE_SETTLE_SECS)
+            self.typer.type_text(new_text)
+            self.text = new_text
+            log.debug("Replaced short text: %s", describe_transcript(new_text))
+            return
+
+        # Word-level append-only
+        old_words = old.split()
+        new_words = new_text.split()
+        matched = _word_match_len(old_words, new_words)
+
+        if matched >= len(old_words) and len(new_words) > matched:
+            new_tail = " ".join(new_words[matched:])
+            to_type = " " + new_tail
+            self.typer.type_text(to_type)
+            self.text = old + to_type
+            log.debug("Appended: %s", describe_transcript(to_type.strip()))
+        else:
+            log.debug(
+                "Skipping (matched %d/%d words)",
+                matched, len(old_words),
+            )
+
+    def _final_correction(self, new_text: str) -> None:
+        """Final pass: char-level diff to fix accumulated drift."""
+        old = self.text
+        prefix_len = _common_prefix_len(old, new_text)
+        to_delete = len(old) - prefix_len
+        to_type = new_text[prefix_len:]
+
+        if to_delete > 0:
+            log.debug("Final correction: delete %d, type %s", to_delete, describe_transcript(to_type))
+            self.typer.delete_chars(to_delete)
+            time.sleep(DELETE_SETTLE_SECS)
+        if to_type:
+            self.typer.type_text(to_type)
+
+        self.text = new_text

voiceio/health.py

@@ -217,6 +217,8 @@ def _check_features() -> FeatureGroups:
             else:
                 groups.accuracy["Vocabulary"] = "none"
 
+        groups.accuracy.update(_learning_status(cfg))
+
         if cfg.postcorrect.enabled:
             model = cfg.postcorrect.model or cfg.cloud.model
             groups.accuracy["Cloud postcorrect"] = f"on ({model}), adds up to {cfg.postcorrect.timeout_secs:g}s"
@@ -225,6 +227,30 @@ def _check_features() -> FeatureGroups:
     return groups
 
 
+def _learning_status(cfg) -> dict[str, str]:
+    """Whether voiceio is learning your voice: the model in use, whether
+    recordings are kept to learn from, and whether it retrains nightly."""
+    from pathlib import Path
+
+    from voiceio import config, service
+    from voiceio.learn.store import learn_dir
+    out: dict[str, str] = {}
+    models = learn_dir() / "models"
+    name = cfg.model.name
+    if models in Path(name).expanduser().parents:
+        out["Voice model"] = f"fine-tuned on you ({Path(name).parent.name})"
+    else:
+        out["Voice model"] = f"stock ({name})"
+    if cfg.data.retain_audio:
+        n = sum(1 for _ in config.RECORDINGS_DIR.glob("*.wav")) \
+            if config.RECORDINGS_DIR.exists() else 0
+        out["Recordings"] = f"on ({n} kept to learn from)"
+    else:
+        out["Recordings"] = "off (nothing to learn from)"
+    out["Nightly learning"] = "on" if service.learn_timer_enabled() else "off"
+    return out
+
+
 def _check_ibus() -> IBusStatus:
     """Run detailed IBus health checks."""
     from pathlib import Path
@@ -325,6 +351,10 @@ def _accuracy_tips(accuracy: dict[str, str]) -> list[str]:
         tips.append("voiceio corrections add WRONG RIGHT  — fix a word that keeps being misheard")
     if vocab == "none":
         tips.append("Add names/jargon to ~/.config/voiceio/vocabulary.txt")
+    if accuracy.get("Recordings", "").startswith("off"):
+        tips.append("voiceio config set data.retain_audio true  — keep recordings so voiceio can learn your voice")
+    elif accuracy.get("Nightly learning") == "off":
+        tips.append("voiceio learn schedule on  — retrain on your voice every night")
     return tips
 
 
@@ -391,7 +421,7 @@ def format_report(report: HealthReport) -> str:
     # Accuracy / learning stack
     if report.features.accuracy:
         lines.append(_section("Accuracy"))
-        lines.append(f"  {DIM}Learns from your dictation history to fix recurring mistakes.{RESET}")
+        lines.append(f"  {DIM}What voiceio knows about your words, and whether it keeps learning.{RESET}")
         for name, status in report.features.accuracy.items():
             lines.append(_feature_line(name, status))
         # Show actionable tips at the bottom

voiceio/learn/train.py

@@ -76,13 +76,17 @@ _DECODER_TARGETS = (r".*decoder\.layers\.\d+\.(self_attn\.(q_proj|k_proj|v_proj|
                     r"|encoder_attn\.(q_proj|out_proj)|fc1|fc2)")
 
 
+TRAIN_HINT = "pip install 'python-voiceio[train]'"
+
+
+def missing_train_deps() -> list[str]:
+    """Training packages that aren't installed (the `train` extra)."""
+    import importlib.util
+    return [m for m in ("torch", "transformers", "peft") if importlib.util.find_spec(m) is None]
+
+
 def require_train_deps() -> None:
-    missing = []
-    for mod in ("torch", "transformers", "peft"):
-        try:
-            __import__(mod)
-        except ImportError:
-            missing.append(mod)
+    missing = missing_train_deps()
     if missing:
         raise RuntimeError(
             f"training needs {', '.join(missing)}: pip install 'python-voiceio[train]'")

voiceio/service.py

@@ -27,6 +27,12 @@ SERVICE_NAME = "voiceio.service"
 SERVICE_DIR = Path.home() / ".config" / "systemd" / "user"
 SERVICE_PATH = SERVICE_DIR / SERVICE_NAME
 
+# Nightly `voiceio learn maintain` (opt-in: `voiceio learn schedule on`)
+LEARN_SERVICE_NAME = "voiceio-learn.service"
+LEARN_TIMER_NAME = "voiceio-learn.timer"
+LEARN_SERVICE_PATH = SERVICE_DIR / LEARN_SERVICE_NAME
+LEARN_TIMER_PATH = SERVICE_DIR / LEARN_TIMER_NAME
+
 # Pre-1.0 weekly cloud mining timer — only referenced to remove it
 CORRECT_SERVICE_NAME = "voiceio-correct.service"
 CORRECT_TIMER_NAME = "voiceio-correct.timer"
@@ -80,6 +86,71 @@ WantedBy=graphical-session.target
 """
 
 
+def _learn_units(bin_path: str) -> tuple[str, str]:
+    """(service, timer) for nightly learning on this machine."""
+    service = f"""\
+[Unit]
+Description=VoiceIO - learn from today's dictation (label, retrain when enough is new)
+Documentation=https://github.com/Hugo0/voiceio#make-it-yours
+
+[Service]
+Type=oneshot
+ExecStart={bin_path} learn maintain
+# Background work: it gets the CPU only when nothing else wants it, so
+# dictation and everything else stay fast. The unit's own cgroup already
+# does what `learn` would otherwise re-exec into a scope for.
+CPUWeight=idle
+IOWeight=10
+Nice=19
+Environment=VOICEIO_IDLE_SCOPE=1 PYTHONUNBUFFERED=1
+"""
+    timer = """\
+[Unit]
+Description=VoiceIO - nightly learning
+
+[Timer]
+OnCalendar=*-*-* 03:30
+RandomizedDelaySec=30min
+# A laptop that was asleep at 03:30 catches up when it next runs.
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+"""
+    return service, timer
+
+
+def _systemctl(*args: str) -> bool:
+    try:
+        return subprocess.run(["systemctl", "--user", *args], capture_output=True,
+                              timeout=10).returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def install_learn_timer() -> bool:
+    """Run `voiceio learn maintain` nightly. True when the timer is enabled."""
+    if _IS_WINDOWS or not has_systemd():
+        return False
+    service, timer = _learn_units(_find_voiceio_bin())
+    SERVICE_DIR.mkdir(parents=True, exist_ok=True)
+    LEARN_SERVICE_PATH.write_text(service)
+    LEARN_TIMER_PATH.write_text(timer)
+    _systemctl("daemon-reload")
+    return _systemctl("enable", "--now", LEARN_TIMER_NAME)
+
+
+def uninstall_learn_timer() -> None:
+    _systemctl("disable", "--now", LEARN_TIMER_NAME)
+    for p in (LEARN_TIMER_PATH, LEARN_SERVICE_PATH):
+        p.unlink(missing_ok=True)
+    _systemctl("daemon-reload")
+
+
+def learn_timer_enabled() -> bool:
+    return LEARN_TIMER_PATH.exists() and _systemctl("is-enabled", "--quiet", LEARN_TIMER_NAME)
+
+
 def uninstall_correct_timer() -> None:
     """Remove the pre-1.0 weekly cloud-mining timer (`correct --auto --batch`).
     It is gone in 1.0: mining moved to the local, opt-in `voiceio learn`."""

voiceio/setup/configfile.py

@@ -75,6 +75,7 @@ def _write_config(
     tts_engine: str = "auto",
     tts_speed: float = 1.0,
     voice_input_prefix: str = "",
+    retain_audio: bool | None = None,
     quiet: bool = False,
 ) -> None:
     """Merge wizard answers into the existing config, preserving everything else.
@@ -113,6 +114,9 @@ def _write_config(
         "speed": tts_speed,
     })
 
+    if retain_audio is not None:   # only when the user was asked
+        section("data")["retain_audio"] = retain_audio
+
     # Cloud endpoint: only touch these keys when the wizard collected a NEW
     # key this run. Otherwise a saved secret / hand-edited endpoint is kept.
     if cloud_api_key:

voiceio/setup/noninteractive.py

@@ -21,6 +21,7 @@ _ALLOWED_ANSWER_KEYS = {
     "sound_enabled", "notify_clipboard", "commands_enabled",
     "punctuation_cleanup", "number_conversion", "voice_input_prefix",
     "tray_enabled", "install_service", "download_model", "install_system_deps",
+    "retain_audio",
 }
 
 
@@ -160,6 +161,8 @@ def run_setup_noninteractive(answers: dict | None = None, *, install_deps: bool
         cloud_api_key=cloud_key,
         cloud_base_url=str(answers.get("cloud_base_url", "")),
         cloud_model=str(answers.get("cloud_model", "")),
+        # Keeping recordings is the user's call; an agent only sets it if told.
+        retain_audio=bool(answers["retain_audio"]) if "retain_audio" in answers else None,
         tts_enabled=bool(answers.get("tts_enabled", True)),
         tts_engine=str(answers.get("tts_engine", "auto")),
         tts_speed=float(answers.get("tts_speed", 1.0)),

voiceio/setup/steps.py

@@ -64,6 +64,7 @@ class SetupState:
     tts_enabled: bool = True
     tts_engine: str = "auto"
     tts_speed: float = 1.0
+    retain_audio: bool | None = None  # None: not asked, leave the config as is
 
     @property
     def is_rerun(self) -> bool:
@@ -90,6 +91,7 @@ class SetupState:
             cloud_model=self.cloud_model,
             tts_enabled=self.tts_enabled, tts_engine=self.tts_engine,
             tts_speed=self.tts_speed,
+            retain_audio=self.retain_audio,
         )
 
 
@@ -497,7 +499,13 @@ def _step_advanced(state: SetupState) -> None:
 
 def _step_finalize(state: SetupState) -> None:
     _print_step(8, _TOTAL_STEPS, "Finalize")
+    print(f"  {DIM}voiceio can learn your voice: keep a recording of each dictation on this")
+    print(f"  machine (never uploaded) and fine-tune on them with `voiceio learn`.{RESET}")
+    state.retain_audio = _ask_yn("Keep recordings so voiceio can learn your voice?",
+                                 default=state.cur.data.retain_audio if state.cur else True)
     _write_config(**state.config_kwargs())
+    if state.retain_audio:
+        _offer_nightly_learning(state)
     _setup_desktop_shortcut(state)
     _install_autostart(state)
     _verify_hotkey(state)
@@ -505,6 +513,24 @@ def _step_finalize(state: SetupState) -> None:
         _start_service()
 
 
+def _offer_nightly_learning(state: SetupState) -> None:
+    """The recordings are only worth keeping if something learns from them."""
+    from voiceio import service
+    if not state.checks["is_linux"] or not service.has_systemd() or service.learn_timer_enabled():
+        return
+    print(f"  {DIM}Every night at idle priority: transcribe new recordings with a bigger model,")
+    print(f"  retrain once enough are new, and tell you if the result is better.{RESET}")
+    if not _ask_yn("Learn from them every night?", default=True):
+        return
+    if service.install_learn_timer():
+        print(f"  {GREEN}✓{RESET} {DIM}Nightly learning on (voiceio learn schedule off to stop){RESET}")
+        from voiceio.learn import train
+        if missing := train.missing_train_deps():
+            print(f"  {DIM}Retraining also needs {', '.join(missing)}: {train.TRAIN_HINT}{RESET}")
+    else:
+        print(f"  {YELLOW}⚠{RESET}  {DIM}Could not enable it; try: voiceio learn schedule on{RESET}")
+
+
 def _setup_desktop_shortcut(state: SetupState) -> None:
     """Set up DE shortcut if on GNOME + socket backend (Linux only)."""
     if not state.checks["is_linux"]:

voiceio/streaming.py

@@ -1,4 +1,9 @@
-"""Streaming transcription with word-level append and final correction."""
+"""Streaming transcription: when to decode what, while the user speaks.
+
+Interim passes decode the un-frozen tail about once a second; long tails are
+frozen at speech pauses so stop only decodes the rest; the final pass runs
+when the user stops. What reaches the screen, and how, is display.TypedText.
+"""
 from __future__ import annotations
 
 import logging
@@ -13,7 +18,7 @@ import numpy as np
 from voiceio.core.decoders.base import Bias
 from voiceio.core.decoders.base import transcribe_timeout
 from voiceio.privacy import describe_transcript
-from voiceio.typers.base import StreamingTyper
+from voiceio.display import TypedText
 
 if TYPE_CHECKING:
     from voiceio.audio_source import AudioSource
@@ -22,7 +27,6 @@ if TYPE_CHECKING:
     from voiceio.typers.base import TyperBackend
 
 log = logging.getLogger(__name__)
-DELETE_SETTLE_SECS = 0.05  # delay between delete and type for ydotool reliability
 
 # Incremental finalization: a freeze cut is only safe at a speech pause.
 _FREEZE_SILENCE_WINDOW_SECS = 0.3
@@ -138,7 +142,7 @@ class StreamingSession:
 
     def __init__(
         self,
-        transcriber: Decoder,
+        decoder: Decoder,
         typer: TyperBackend,
         recorder: AudioSource,
         generation: int = 0,
@@ -149,11 +153,11 @@ class StreamingSession:
         freeze_secs: float = 15.0,
         bias: Bias | None = None,
     ):
-        self._transcriber = transcriber
+        self._decoder = decoder
         # Captured once per session: vocabulary/prompt changes made while this
         # recording runs apply to the next one, never halfway through this.
         self._bias = bias or Bias()
-        self._typer = typer
+        self._display = TypedText(typer)
         # Output-ownership gate: the app sets this so a superseded session (its
         # generation was overtaken by a newer recording) stops emitting ANY
         # typer output on the final path, which would otherwise corrupt the new
@@ -170,7 +174,6 @@ class StreamingSession:
         self._on_interim = on_interim
         self._typer_fail_count = 0
         self._typer_broken_signalled = False
-        self._typed_text = ""
         self._pending = threading.Event()
         self._stop_event = threading.Event()
         # The final pass runs in stop()'s thread, concurrently with whatever
@@ -211,7 +214,7 @@ class StreamingSession:
     @property
     def interim_text(self) -> str:
         """Best-so-far text (post-pipeline). Safe to read while finalizing."""
-        return self._typed_text
+        return self._display.text
 
     def set_is_current(self, is_current: Callable[[], bool]) -> None:
         """Install the output-ownership gate (see __init__).
@@ -229,8 +232,7 @@ class StreamingSession:
         Resets the typed-text tracking: the old backend's on-screen state
         (e.g. a stranded IBus preedit) no longer belongs to us.
         """
-        self._typer = typer
-        self._typed_text = ""
+        self._display = TypedText(typer)
 
     def start(self) -> None:
         """Begin streaming. Recorder must already be started by caller."""
@@ -271,15 +273,15 @@ class StreamingSession:
         if self._recorder is not None:
             self._recorder.set_on_speech_pause(None)
             self._recorder = None
-        log.debug("Streaming session stopped, typed: %s", describe_transcript(self._typed_text))
-        return self._typed_text
+        log.debug("Streaming session stopped, typed: %s", describe_transcript(self._display.text))
+        return self._display.text
 
     def _decode_past_pending_freeze(self, audio: np.ndarray | None):
         """If a freeze is decoding on the final lane, decode the audio after
         its cut on the draft lane meanwhile, so stop waits for the longer of
         the two instead of their sum. Returns (start_sample, result) or None."""
         end = self._freeze_pending_end
-        draft = getattr(self._transcriber, "draft", None)
+        draft = getattr(self._decoder, "draft", None)
         if end is None or draft is None or audio is None or len(audio) <= end:
             return None
         try:
@@ -308,7 +310,7 @@ class StreamingSession:
                     self._typer_broken_signalled = True
                     log.warning(
                         "Typer '%s' failed %d times in streaming, requesting re-probe",
-                        self._typer.name, self._typer_fail_count,
+                        self._display.typer.name, self._typer_fail_count,
                     )
                     if self._on_typer_broken:
                         self._on_typer_broken()
@@ -332,7 +334,7 @@ class StreamingSession:
         """
         t0 = time.monotonic()
         try:
-            result = self._transcriber.decode(chunk, final=True, bias=self._tail_bias())
+            result = self._decoder.decode(chunk, final=True, bias=self._tail_bias())
         except Exception:
             log.exception("Freeze decode failed (boundary unchanged)")
             return
@@ -417,7 +419,7 @@ class StreamingSession:
                 if pre is not None and pre[0] == self._frozen_samples:
                     result = pre[1]  # decoded in parallel with the last freeze
                 else:
-                    result = self._transcriber.decode(tail, final=final, bias=self._tail_bias())
+                    result = self._decoder.decode(tail, final=final, bias=self._tail_bias())
             except Exception:
                 # Decode FAILED (timeout/crash) — this is not silence. Never
                 # advance the freeze boundary or char-diff against a partial
@@ -506,119 +508,29 @@ class StreamingSession:
                 # A superseded session must not touch the typer on the final
                 # path (would corrupt the newer session's output).
                 if final and not self._is_current():
-                    self._typed_text = ""
+                    self._display.text = ""
                     return
-                if isinstance(self._typer, StreamingTyper):
-                    self._typer.clear_preedit()
-                elif self._typed_text:
-                    self._typer.delete_chars(len(self._typed_text))
-                self._typed_text = ""
+                self._display.clear()
                 return
 
             if text:
-                prev = self._typed_text
+                prev = self._display.text
                 self._apply_correction(text, final=final)
-                if not final and self._on_interim and self._typed_text != prev:
+                if not final and self._on_interim and self._display.text != prev:
                     try:
-                        self._on_interim(self._typed_text)
+                        self._on_interim(self._display.text)
                     except Exception:
                         log.debug("on_interim callback failed", exc_info=True)
 
     def _commit_interim_on_final(self) -> None:
-        """Commit whatever interim text we have when the final pass yields none.
-
-        For the IBus preedit path the interim text lives only in the preedit
-        (uncommitted) — commit it so a final-pass timeout doesn't drop it. For
-        keystroke typers the interim text is already in the target app, so
-        there is nothing to do.
-        """
-        if not self._typed_text or not self._is_current():
-            return
-        if isinstance(self._typer, StreamingTyper):
-            log.warning(
-                "Final transcription empty; committing interim preedit text (%d chars)",
-                len(self._typed_text),
-            )
-            self._typer.commit_text(self._typed_text)
+        """Commit whatever interim text we have when the final pass yields none."""
+        if self._is_current():
+            self._display.commit_preview()
 
     def _apply_correction(self, new_text: str, final: bool = False) -> None:
-        """Apply correction to typed text.
-
-        With StreamingTyper (IBus): use preedit during streaming, commit on final.
-        Without: append-only via word-level matching, char-level diff on final.
-        """
-        old = self._typed_text
-
         # A superseded session must emit no typer output on the final path.
         if final and not self._is_current():
             log.debug("Final output suppressed: session superseded")
-            self._typed_text = new_text
+            self._display.text = new_text
             return
-
-        # Preedit path: trivial, just replace the preview text
-        if isinstance(self._typer, StreamingTyper):
-            if final:
-                self._typer.commit_text(new_text)
-                self._typed_text = new_text
-                log.debug("Preedit commit: %s", describe_transcript(new_text))
-            elif new_text != old:
-                self._typer.update_preedit(new_text)
-                self._typed_text = new_text
-                log.debug("Preedit update: %s", describe_transcript(new_text))
-            return
-
-        if new_text == old:
-            return
-
-        if final:
-            self._apply_final_correction(new_text)
-            return
-
-        if not old:
-            # First transcription, just type it
-            self._typer.type_text(new_text)
-            self._typed_text = new_text
-            log.debug("Initial: %s", describe_transcript(new_text))
-            return
-
-        # Short text: allow full replacement (Whisper still warming up)
-        if len(old.split()) <= 2:
-            self._typer.delete_chars(len(old))
-            time.sleep(DELETE_SETTLE_SECS)
-            self._typer.type_text(new_text)
-            self._typed_text = new_text
-            log.debug("Replaced short text: %s", describe_transcript(new_text))
-            return
-
-        # Word-level append-only
-        old_words = old.split()
-        new_words = new_text.split()
-        matched = _word_match_len(old_words, new_words)
-
-        if matched >= len(old_words) and len(new_words) > matched:
-            new_tail = " ".join(new_words[matched:])
-            to_type = " " + new_tail
-            self._typer.type_text(to_type)
-            self._typed_text = old + to_type
-            log.debug("Appended: %s", describe_transcript(to_type.strip()))
-        else:
-            log.debug(
-                "Skipping (matched %d/%d words)",
-                matched, len(old_words),
-            )
-
-    def _apply_final_correction(self, new_text: str) -> None:
-        """Final pass: char-level diff to fix accumulated drift."""
-        old = self._typed_text
-        prefix_len = _common_prefix_len(old, new_text)
-        to_delete = len(old) - prefix_len
-        to_type = new_text[prefix_len:]
-
-        if to_delete > 0:
-            log.debug("Final correction: delete %d, type %s", to_delete, describe_transcript(to_type))
-            self._typer.delete_chars(to_delete)
-            time.sleep(DELETE_SETTLE_SECS)
-        if to_type:
-            self._typer.type_text(to_type)
-
-        self._typed_text = new_text
+        self._display.apply(new_text, final=final)

voiceio/typers/manager.py

@@ -157,7 +157,7 @@ class TyperManager:
 
         Defers the re-probe+upgrade to a background thread that waits
         for the state to reach IDLE. We cannot hot-swap mid-recording:
-        the streaming session tracks ``_typed_text`` in terms of the old
+        the streaming session's TypedText tracks text in terms of the old
         typer's behavior (char-level for clipboard vs preedit for ibus),
         and mid-stream swapping would leave stale or duplicated chars.
         The current recording is already broken — accept that, fix it

voiceio/watchdog.py

@@ -26,11 +26,11 @@ _RESUME_THRESHOLD = 30  # seconds
 
 
 class Watchdog:
-    """Every ``_HEALTH_CHECK_INTERVAL``: transcriber worker, audio stream,
+    """Every ``_HEALTH_CHECK_INTERVAL``: decoder worker, audio stream,
     tray, typer and IBus engine; a full re-probe after suspend/resume.
 
     It never mutates the daemon's state machine itself: ``is_idle`` /
-    ``is_recording`` read it, ``on_transcriber_failed`` asks the daemon to
+    ``is_recording`` read it, ``on_decoder_failed`` asks the daemon to
     enter ERROR, and typer/platform changes go through ``typers``' IDLE-gated
     swap helpers.
     """
@@ -39,26 +39,26 @@ class Watchdog:
         self,
         cfg: config.Config,
         *,
-        transcriber: Decoder,
+        decoder: Decoder,
         recorder: AudioRecorder,
         typers: TyperManager,
         ibus: IBusSession,
         session: Callable[[], StreamingSession | None],
         is_idle: Callable[[], bool],
         is_recording: Callable[[], bool],
-        on_transcriber_failed: Callable[[], None],
+        on_decoder_failed: Callable[[], None],
         on_hotkey: Callable[[], None],
         shutdown: threading.Event,
     ):
         self._cfg = cfg
-        self._transcriber = transcriber
+        self._decoder = decoder
         self._recorder = recorder
         self._typers = typers
         self._ibus = ibus
         self._session = session
         self._is_idle = is_idle
         self._is_recording = is_recording
-        self._on_transcriber_failed = on_transcriber_failed
+        self._on_decoder_failed = on_decoder_failed
         self._on_hotkey = on_hotkey
         self._shutdown = shutdown
 
@@ -72,7 +72,7 @@ class Watchdog:
         ).start()
 
     def _loop(self) -> None:
-        """Periodic health check: transcriber worker, IBus engine, audio stream."""
+        """Periodic health check: decoder worker, IBus engine, audio stream."""
         last_check = time.monotonic()
         while not self._shutdown.is_set():
             self._shutdown.wait(_HEALTH_CHECK_INTERVAL)
@@ -120,25 +120,25 @@ class Watchdog:
             tray.restart(self._on_hotkey)
 
         # Transcriber: ensure worker is alive
-        if not self._transcriber.healthy():
+        if not self._decoder.healthy():
             try:
-                self._transcriber.recover()
-                log.info("Resume: transcriber worker restarted")
+                self._decoder.recover()
+                log.info("Resume: decoder worker restarted")
             except RuntimeError:
-                log.error("Resume: transcriber worker failed")
+                log.error("Resume: decoder worker failed")
 
     def check(self) -> None:
         """Run one health check cycle."""
-        # Check transcriber worker
-        if not self._transcriber.healthy():
+        # Check decoder worker
+        if not self._decoder.healthy():
             if self._is_recording():
                 log.warning("Transcriber worker died during recording")
             try:
-                self._transcriber.recover()
+                self._decoder.recover()
                 log.info("Transcriber worker recovered")
             except RuntimeError:
                 log.error("Transcriber worker permanently failed")
-                self._on_transcriber_failed()
+                self._on_decoder_failed()
 
         # Check audio stream (covers ALSA underrun, PulseAudio/PipeWire
         # restart, device disconnect, stale callback heartbeat)