python-voiceio 1.8.2__py3-none-any.whl → 1.9.0__py3-none-any.whl

{python_voiceio-1.8.2.dist-info → python_voiceio-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.8.2
+Version: 1.9.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT

{python_voiceio-1.8.2.dist-info → python_voiceio-1.9.0.dist-info}/RECORD

@@ -1,19 +1,20 @@
-python_voiceio-1.8.2.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=d6593s-XBNvVxri9lr2qLUDZQ3Zk3-VXHEwdb4pj8qA,22
+python_voiceio-1.9.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=ljy9wwnU6FSzJrHgJSWUcZ_nIboERJauUm7HTpNQfNg,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=kOvdXNDovKInC1B5jCNx1iyjasFzLTQy_ZEizEF3YkI,42268
+voiceio/app.py,sha256=ce3bf2Es-7KgciMZLYJO2qpJgZId_hOmqdmTFGcun1w,43668
 voiceio/audio_source.py,sha256=rR6NRtNzmZ8uqmNPxareBWTJmuBaOxIGI5QINR_l-qc,9102
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
 voiceio/clipboard_read.py,sha256=7f5aX644Fiy2S6MXxADfSgRtvO3P1U-r_VkzEgWrwKQ,5376
 voiceio/commands.py,sha256=Jz-txXSw32Adf8B912M8CzQIh4UMmEKRCZBPXU4bBaU,6014
-voiceio/config.py,sha256=h70Pgsk9gYVkvFud71VMIFm39fG35MAmXHFz7TpLqBs,22725
+voiceio/config.py,sha256=Pv8Wx_ieY4y6xUJqP6fLkpBzCsiuKNcW8G8ox0Eit2M,22971
 voiceio/consent.py,sha256=3stv3iZvYl_Dt4GUe-GUVOHEGi-2fOl-QqF3pDjraS4,1862
+voiceio/context_terms.py,sha256=I5EkkxCR8VrzeUX89-JM4I0QgoYGPtn62DfgXO8hrP8,9906
 voiceio/corrections.py,sha256=IIRViwjL9kkMy26-1dd0DtTfT0Tiedn6pmmHoaeayMQ,10047
 voiceio/demo.py,sha256=jA282e7UWDwtP1IXT2bPHH5wl6eKdBNvOJcoNDWzZlQ,8766
 voiceio/display.py,sha256=ZGBNRjuvg3chkJjduyPJs4s5ZY5vqC_mcaov94PIPzo,5313
 voiceio/feedback.py,sha256=Q4zlWotRl4Lh3whr7P6YsvJVoNknmTap93ab_utimts,8890
 voiceio/focus.py,sha256=PGj839UUZE7ZPwaiLDTAX3S8d_QjwaT4y6ugXyylL9M,4304
-voiceio/health.py,sha256=0tsikLYK-COj4ILquLWci9-3kA7KoC-JMKlCtW9IKFw,22539
+voiceio/health.py,sha256=R8Gh5BNtELOAHLnbnCtzJ55KIJoZMAJp4FNLEc9RavI,22804
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
 voiceio/history.py,sha256=8RN6qyJZMLgyNIdYuu5WVNjad4d_4TKFz2ohg5KW0F8,5965
 voiceio/idle_audio.py,sha256=0GEbm0g-a2uVxIMWEKpaYus06mnrc8qvWr09a85FWS0,7225
@@ -23,7 +24,7 @@ voiceio/numbers.py,sha256=CXJtlMhmV6_9Z1FtKAF4-RXycw8voV-BYHPBpdw1I6Y,13571
 voiceio/pidlock.py,sha256=OZLNskUyv9_F3WgyHZWw8WmKt0W7ioxH6xgHitOwCww,1216
 voiceio/platform.py,sha256=uG_5KeYey_29GCn4nSOQJ1UpoCrBC_m2DR7IeoRnuL4,19142
 voiceio/postcorrect.py,sha256=JN5l9xnyGfYq2_owSUwkJ513QiQQKxCrT3hjU5aJCpg,17322
-voiceio/postprocess.py,sha256=rzKmf_ZCskhGnqLEbHaiQX-Sz9yutdJwcwposz7GJ4Q,4661
+voiceio/postprocess.py,sha256=9vpth8u2xOIKU6SimY-hsEDrs4X9YJSI67ZO_f2PpxM,6048
 voiceio/power.py,sha256=mKiG5ioHbzgtW2S-OKGFOPzZFbG0HwUUyMn8kE5JRoQ,681
 voiceio/privacy.py,sha256=FqnA9jx9RCqWW-i6Dh7JcT7vzz97kbUGyQEvsHLvpqc,573
 voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
@@ -31,28 +32,28 @@ voiceio/quiet_audio.py,sha256=AapeuhrJwR20fsl-Ksgv4qpptrcQezk6A2_i4Kr18Ks,11451
 voiceio/recorder.py,sha256=E3YwZecJqd06GGoRSjFi2Q-7GoRzBkAMBGspKVkF9rc,16746
 voiceio/retention.py,sha256=5ydw2dJ2gTQ39BYdg3Bk4mk-KNJkJcGUKzssndYwdY8,6137
 voiceio/service.py,sha256=q4_Mk8m3KCG14CGZ468ZrFvNvyXuWSOjKFUjRnksgAI,16391
-voiceio/streaming.py,sha256=Cfkr3b0vM8x9q7XYeXWl1KaG2xs5-t7lpsMrfL7KlmU,25610
+voiceio/streaming.py,sha256=67hHvAQ7Z99iwtwy6BXPBPqE0q9mNpoP0Lhh8-RufIk,25968
 voiceio/suggest.py,sha256=jX4bCpnddyrteKfRBPbnUgf-Rk5145LFaSTat0_Ll2E,4836
-voiceio/tokens.py,sha256=m5tusR3zEBX7fRKaDUj4z-DSv8NcMhE-02HviAziENQ,5710
+voiceio/tokens.py,sha256=y9KBDgLukUMieO576rgyBn8qEQqElra66spQwoWXDXk,6321
 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/vocabulary.py,sha256=V74eubSYn6hAQGIgRJ74p22ztvxw2dtal-IbB4cVBr8,10895
 voiceio/watchdog.py,sha256=XnrpM3ULeUoJ-sMt_aNNzJSLqOuK4ocJAMHQ00knYuw,7838
-voiceio/wordfreq.py,sha256=PTAoaEUX1D2Y12jjd8A9cFTqsZkDDZt6eesBBL_4toA,3151
+voiceio/wordfreq.py,sha256=AxmVgpQRfm2YAYQpHCRRrBUTpa12y_ngiFNScrGr4GM,3543
 voiceio/cli/__init__.py,sha256=EM2Qa1COWkqSQ9hFuPKdf8_OD5JoGsY3QCpQA-waEJQ,8353
 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=7FvEEgdw8jf5XXvC7-4S7iIpcjBbn7dx4czIijg61C0,2597
-voiceio/cli/learn.py,sha256=9i1mW4XUbSN74_afZjt1gbL77flx8WzctLHW0oKHArs,32300
+voiceio/cli/learn.py,sha256=ajVP7RRFBLXa0Sf-pbYrccPpuB58oHjd4wR9JkcOwtw,32914
 voiceio/cli/models.py,sha256=fye_mHbsXLY11uRC1BCDlucCHPny9ftoehAeUJPMJv0,4263
 voiceio/cli/servicecmd.py,sha256=2St2WfLkt06EpC51I5i9Ykv_pvLKzu_dz01M-29O3-4,4830
 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
-voiceio/core/engine.py,sha256=jWmFsgx3-Nx6AhuDW60jSWCPsJC2Cc4mKhKO9jVqxK8,8247
+voiceio/core/bias.py,sha256=Kxxy7UJOZbA4gYJJbJVL27-1mMaMCm8WTujDNJR9WUY,6093
+voiceio/core/engine.py,sha256=7g3oXXo731Rcxem60xTWq7UXqTkKth2m_GyycUdJiUE,8665
 voiceio/core/pipeline.py,sha256=p164xjnuUXlNQQoRvJVNNEahoklqNGYfwx8o7y6i8tM,7049
 voiceio/core/decoders/__init__.py,sha256=CmbkAucTNjzDIzTMdbMggoibHsQ_H03eHrMJhODpplg,2473
 voiceio/core/decoders/base.py,sha256=D-umP8Eqk6GLg6IzTPA6Q1BomlHutU2AqsVRn4SS4XU,3787
@@ -85,7 +86,7 @@ voiceio/learn/metrics.py,sha256=b2xWUzPpNpXHn6zgS1upPbEcpW3ExH9SmSLIUzPhStQ,5174
 voiceio/learn/quiet.py,sha256=5Ov3mvE1G3CjhwFQOuJvGeju242zFASi29tketnUyew,1523
 voiceio/learn/review.py,sha256=X5qs5yEf20Ao3gMhsbW3Eur62hSqy9AYlv08Pcrllxo,5572
 voiceio/learn/store.py,sha256=MauWhGaI2drMbiChIZOblpPS_uVAw-1sNWGyGACHYw8,12816
-voiceio/learn/teacher.py,sha256=uF4hQkrdjv012TTBRSwrhQqqAeCFNoidABcrgzSVUoI,3696
+voiceio/learn/teacher.py,sha256=FhCv08Js3chs4Vbh0VN3ZI9p05HFxeeeFJF8jTjjzPQ,3751
 voiceio/learn/train.py,sha256=FtZMa4ddsPMRUxkyqC-Qf9OveZmgRMHiGXx5WHj_jT8,18214
 voiceio/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 voiceio/models/silero_vad.onnx,sha256=GhU6IvRQnikqlOZ9b5uF6N6yW0mIaCt-F0xlJ52HiOM,2327524
@@ -132,8 +133,8 @@ voiceio/typers/pynput_type.py,sha256=f3w131YWJfNGd4IAcWtuKd2Gcwu3467QwGW3OBUEXNI
 voiceio/typers/wtype.py,sha256=11vOAKHjMat-fITd4sUoUWwgniyVp65EbH3i4mL6Vhg,1762
 voiceio/typers/xdotool.py,sha256=OuT_zW_z07jSAqu9Cmn_gL1mJfQsiX62ecqFRvpAarQ,1332
 voiceio/typers/ydotool.py,sha256=oY5EXB-nI7PvxTL_5Tb3JjfvyhmLNYNnUFvkb1XUn_U,5978
-python_voiceio-1.8.2.dist-info/METADATA,sha256=2SK3PktKq9k4l5bG9ki71XPCxzDES_Nt4SIzJZtjoFk,7519
-python_voiceio-1.8.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_voiceio-1.8.2.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
-python_voiceio-1.8.2.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-1.8.2.dist-info/RECORD,,
+python_voiceio-1.9.0.dist-info/METADATA,sha256=t77vZeISZAjr-72w7Ef9mhi_rDOTzcU5Ha4odNvwlng,7519
+python_voiceio-1.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_voiceio-1.9.0.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
+python_voiceio-1.9.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-1.9.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "1.8.2"
+__version__ = "1.9.0"

voiceio/app.py

@@ -168,6 +168,10 @@ class VoiceIO:
         threading.Thread(
             target=retention.prune, args=(cfg.data,), daemon=True,
         ).start()
+        if cfg.model.screen_vocabulary:
+            # Word frequency tables load in ~1s; not on the first dictation.
+            from voiceio.context_terms import warm
+            threading.Thread(target=warm, args=(cfg.model.language,), daemon=True).start()
 
         # Hotkey deduplication
         self._hotkey_lock = threading.Lock()
@@ -557,10 +561,12 @@ class VoiceIO:
         # `voiceio vocab`/`corrections` apply from the next recording.
         bias = self.engine.bias()
         self._recording_bias = bias
-        if self.cfg.data.capture_context:
-            # Snapshot the dictation target now — focus may change by finalize
+        if self.cfg.data.capture_context or self.cfg.model.screen_vocabulary:
+            # Snapshot the dictation target now — focus may change by finalize.
+            # Off this thread: the chime and the mic never wait on it.
             self._context_title = None
-            threading.Thread(target=self._capture_context, daemon=True).start()
+            threading.Thread(target=self._capture_context, args=(self._recording,),
+                             daemon=True, name="screen-context").start()
         self._record_start = time.monotonic()
         self.recorder.start()
         self.recorder.set_on_auto_stop(self._on_auto_stop)
@@ -627,9 +633,29 @@ class VoiceIO:
             # No finalizer will run to release the input source, so do it here.
             self._typers.end(rid)
 
-    def _capture_context(self) -> None:
+    def _capture_context(self, rid: int) -> None:
         from voiceio import retention
-        self._context_title = retention.active_window_title()
+        if not self.cfg.model.screen_vocabulary:
+            self._context_title = retention.active_window_title()
+            return
+        from voiceio import context_terms
+        t0 = time.monotonic()
+        screen = context_terms.capture()
+        if self.cfg.data.capture_context:
+            self._context_title = screen.title or None
+        terms = self.engine.screen_terms([screen.title, screen.selection])
+        if not terms:
+            return
+        bias = self.engine.bias(screen_terms=terms)
+        with self._hotkey_lock:
+            if self._recording != rid or self._state != _State.RECORDING:
+                return
+            self._recording_bias = bias
+            if self._session is not None:
+                self._session.set_bias(bias)
+        # A count only: these are words from the user's screen.
+        log.debug("Screen vocabulary: %d term(s) from %s, ready %.0f ms after start",
+                  len(terms), "+".join(screen.sources()), (time.monotonic() - t0) * 1000)
 
     def _retention_extra(self, audio: np.ndarray | None) -> dict:
         """Save the utterance audio (before transcription, so it survives

voiceio/cli/learn.py

@@ -417,6 +417,16 @@ def cmd_train(args: argparse.Namespace) -> None:
               f"  (compare with the current model, then `voiceio learn promote {run.name}`)")
 
 
+def _train_language() -> str:
+    """The language a fine-tune is trained under: the one dictation decodes
+    with. "auto" has no single answer, so it has to be set first."""
+    lang = _cfg().model.language or "en"
+    if lang == "auto":
+        raise SystemExit("Fine-tuning needs one language: set it with "
+                         "`voiceio config set model.language es` (your dictation language).")
+    return lang
+
+
 def _train(ds: Path, *, base: str = "small", epochs: int = 4, synthetic_share: float = 0.3,
            full: bool = False, remote: bool = False) -> Path | None:
     """Export `ds` and fine-tune on it; returns the run dir (None for --remote)."""
@@ -433,8 +443,11 @@ def _train(ds: Path, *, base: str = "small", epochs: int = 4, synthetic_share: f
         return None
     train.require_train_deps()
     hotwords = (folder / train.HOTWORDS_FILE).read_text(encoding="utf-8")
+    # The language token the model is trained under must be the one it decodes
+    # with: training a Spanish voice under "en" taught it the wrong prompt.
     hf = train.train(folder, run, train.TrainConfig(
-        base=base, epochs=epochs, decoder_only=False if full else None, hotwords=hotwords))
+        base=base, epochs=epochs, decoder_only=False if full else None, hotwords=hotwords,
+        language=_train_language()))
     train.convert(hf, run / "ct2")
     return run
 

voiceio/config.py

@@ -90,6 +90,10 @@ class ModelConfig:
     # "modified_beam_search" (required for hotwords).
     decoding: str = ""
     vocabulary_file: str = ""  # path to vocabulary.txt
+    # Bias each dictation toward rare names on screen: the focused window's
+    # title and the selected text (voiceio/context_terms.py). Read locally
+    # when recording starts; never stored or sent anywhere.
+    screen_vocabulary: bool = True
     # 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

voiceio/context_terms.py

@@ -0,0 +1,253 @@
+"""On-screen vocabulary: bias one dictation toward the names you can see.
+
+Most misrecognitions are proper nouns and jargon, and the word you are about
+to say is often already on screen: in the focused window's title or in the
+text you just selected. This reads those two sources when a recording starts,
+picks out the terms Whisper is likely to miss (rare words, CamelCase,
+acronyms, multiword names) and hands them to `core.bias` for this one
+recording, inside a small share of the hotword budget.
+
+Capture happens off the hotkey path, under a hard deadline, and degrades to
+"no terms" on any failure. Nothing captured here is logged or written to
+disk; only a term count is logged.
+
+Not used: AT-SPI (the focused widget's text). It needs PyGObject, which the
+venv can't import, so a system-Python helper; a one-shot walk of the
+accessibility tree took 120-900 ms on GNOME, and Chromium/Electron apps expose
+their text only while a screen reader is on.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import subprocess
+import threading
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+# Capture deadline. Long enough for two ~20 ms subprocess reads under load,
+# short enough that the terms are in place before the first interim pass.
+CAPTURE_TIMEOUT_SECS = 0.15
+# Only the head of a large selection is scanned: extraction stays ~10 ms.
+MAX_SCAN_CHARS = 8000
+MAX_TERMS = 8
+
+# Zipf thresholds (see wordfreq.py: 2.0 ≈ top 30K words). A capitalized word
+# is a name, and Whisper misses names it has seen far more often than generic
+# rare words (Kosh 2.1, Wayland 2.7), so names get a higher bar.
+_ZIPF_LOWER = 2.0
+_ZIPF_NAME = 3.0
+_ZIPF_MIXED = 3.5
+_ZIPF_COMMON = 4.0
+
+_TOKEN = re.compile(r"[\w'’.\-/@#:+]+")
+_WORD = re.compile(r"^[A-Za-zÀ-ɏ][A-Za-zÀ-ɏ'’\-]*[A-Za-zÀ-ɏ]$")
+_MIXED = re.compile(r"[a-zà-ÿ][A-ZÀ-Þ]|[A-ZÀ-Þ]{2}[a-zà-ÿ]")
+
+
+@dataclass(frozen=True)
+class ScreenContext:
+    title: str = ""
+    selection: str = ""
+    secs: float = 0.0
+
+    def sources(self) -> list[str]:
+        return [n for n, v in (("title", self.title), ("selection", self.selection)) if v]
+
+
+def _kind(word: str, zipf: Callable[[str], float]) -> int:
+    """How much a word looks like something Whisper will miss: 3 = CamelCase
+    or rare name, 2 = acronym, 1 = rare lowercase word, 0 = not a term."""
+    if not _WORD.match(word) or len(word) < 3:
+        return 0
+    if _MIXED.search(word):
+        return 3 if len(word) <= 20 and zipf(word) < _ZIPF_MIXED else 0
+    if word.isupper():
+        return 2 if len(word) <= 6 and zipf(word) < _ZIPF_NAME else 0
+    if word[0].isupper():
+        return 3 if zipf(word) < _ZIPF_NAME else 0
+    return 1 if len(word) >= 4 and zipf(word) < _ZIPF_LOWER else 0
+
+
+def _words(text: str) -> list[list[str]]:
+    """Runs of plain words; an identifier, URL or number ends a run, and its
+    letter parts (voiceio.dev → voiceio) stand alone."""
+    runs: list[list[str]] = [[]]
+    for line in text.splitlines():
+        runs.append([])
+        for tok in _TOKEN.findall(line):
+            stripped = tok.strip("'’.-:")
+            if _WORD.match(stripped):
+                runs[-1].append(stripped)
+                if tok.rstrip("'’") != stripped:   # trailing punctuation ends the run
+                    runs.append([])
+                continue
+            runs.append([])
+            for part in re.split(r"[^A-Za-zÀ-ɏ'’]+", tok):
+                if _WORD.match(part):
+                    runs[-1].append(part)
+                    runs.append([])
+    return [r for r in runs if r]
+
+
+def _name_end(run: list[str], kinds: list[int], i: int,
+              zipf: Callable[[str], float]) -> int:
+    """End of a multiword name starting at run[i] (2-3 capitalized words,
+    one of them rare), or i when there is none. Very common words don't
+    start or end a name: "Hey Kosh" is a greeting, not a name."""
+    j = i
+    while j < len(run) and j - i < 3 and run[j][0].isupper() and not run[j].isupper():
+        j += 1
+    if j - i < 2 or zipf(run[i]) >= _ZIPF_COMMON or run[i] == run[i + 1]:
+        return i
+    while j - i >= 2 and zipf(run[j - 1]) >= _ZIPF_COMMON:
+        j -= 1
+    return j if j - i >= 2 and any(k == 3 for k in kinds[i:j]) else i
+
+
+def extract_terms(
+    texts: Iterable[str],
+    *,
+    language: str = "en",
+    exclude: Iterable[str] = (),
+    prefer: Iterable[str] = (),
+    max_terms: int = MAX_TERMS,
+) -> list[str]:
+    """Candidate hotwords from on-screen text, best first.
+
+    `texts` in priority order (title before selection). `exclude` holds terms
+    already biased (case-insensitive); `prefer` the user's full vocabulary,
+    whose long tail never fits the budget — seeing one of them on screen is
+    the strongest signal there is.
+    """
+    from functools import lru_cache
+
+    from voiceio.wordfreq import _zipf
+
+    zipf = lru_cache(maxsize=4096)(lambda w: _zipf(w, language))
+    excluded = {t.lower() for t in exclude}
+    preferred = {t.lower() for t in prefer}
+    # lowercased term → [score, first seen, spelling as first seen]
+    scores: dict[str, list] = {}
+
+    def add(term: str, score: float) -> None:
+        key = term.lower()
+        if key in excluded:
+            return
+        if key in scores:
+            # Repeats add a little, so the term the page is about outranks a
+            # one-off, without letting a long page flood the list.
+            scores[key][0] += 0.5
+            return
+        scores[key] = [score + (3 if key in preferred else 0), len(scores), term]
+
+    texts = list(texts)
+    for rank, text in enumerate(texts):
+        weight = (len(texts) - rank) * 0.1   # earlier source wins ties
+        for run in _words((text or "")[:MAX_SCAN_CHARS]):
+            kinds = [_kind(w, zipf) for w in run]
+            i = 0
+            while i < len(run):
+                j = _name_end(run, kinds, i, zipf)
+                if j > i + 1:
+                    add(" ".join(run[i:j]), 3 + weight)
+                    i = j
+                    continue
+                if kinds[i]:
+                    add(run[i], kinds[i] + weight)
+                i += 1
+
+    ranked = sorted(scores.values(), key=lambda v: (-v[0], v[1]))
+    out: list[str] = []
+    seen_words: set[str] = set()
+    for _, _, term in ranked:
+        parts = term.lower().split()
+        if seen_words.intersection(parts):
+            continue   # a name and its parts cost tokens twice for one word
+        out.append(term)
+        seen_words.update(parts)
+        if len(out) >= max_terms:
+            break
+    return out
+
+
+def warm(language: str = "en") -> None:
+    """Load the word frequency tables now, not on the first dictation."""
+    extract_terms(["Warmup"], language=language)
+
+
+# ── capture ────────────────────────────────────────────────────────────────
+
+
+def _read_primary(timeout: float) -> str:
+    """The PRIMARY selection (highlighted text). xclip through XWayland first:
+    on GNOME, wl-paste can take keyboard focus for a frame, which drops an
+    IBus preedit — never acceptable at the start of a dictation."""
+    from voiceio.platform import detect
+    p = detect()
+    if os.environ.get("DISPLAY") and shutil.which("xclip"):
+        argv = ["xclip", "-o", "-selection", "primary"]
+    elif p.is_wayland and p.desktop != "gnome" and shutil.which("wl-paste"):
+        argv = ["wl-paste", "-p", "--no-newline"]
+    else:
+        return ""
+    try:
+        out = subprocess.run(argv, capture_output=True, timeout=timeout)
+    except (subprocess.TimeoutExpired, OSError):
+        return ""
+    if out.returncode != 0:
+        return ""
+    return out.stdout[:MAX_SCAN_CHARS * 4].decode("utf-8", "replace")
+
+
+def _read_title(_timeout: float) -> str:
+    from voiceio import retention
+    return retention.active_window_title() or ""
+
+
+def capture(timeout: float = CAPTURE_TIMEOUT_SECS, *,
+            readers: dict[str, Callable[[float], str]] | None = None) -> ScreenContext:
+    """Read the window title and selection in parallel; whatever isn't back
+    by `timeout` is dropped (its thread finishes on its own). Never raises."""
+    readers = readers or {"title": _read_title, "selection": _read_primary}
+    t0 = time.monotonic()
+    results: dict[str, str] = {}
+
+    def run(name: str, fn: Callable[[float], str]) -> None:
+        try:
+            results[name] = fn(timeout) or ""
+        except Exception:  # noqa: BLE001 — context is a bonus
+            log.debug("screen context: %s failed", name, exc_info=True)
+
+    threads = [threading.Thread(target=run, args=item, daemon=True,
+                                name=f"screen-{item[0]}") for item in readers.items()]
+    for t in threads:
+        t.start()
+    deadline = t0 + timeout
+    for t in threads:
+        t.join(max(0.0, deadline - time.monotonic()))
+    got = dict(results)   # snapshot: a late reader must not change it
+    return ScreenContext(title=got.get("title", ""), selection=got.get("selection", ""),
+                         secs=time.monotonic() - t0)
+
+
+def describe() -> str:
+    """For `voiceio doctor`: which sources this session can read."""
+    from voiceio.focus import focused_window
+    from voiceio.platform import detect
+    p = detect()
+    sources = []
+    if os.environ.get("DISPLAY") and shutil.which("xclip"):
+        sources.append("selection (xclip)")
+    elif p.is_wayland and p.desktop != "gnome" and shutil.which("wl-paste"):
+        sources.append("selection (wl-paste)")
+    if focused_window(xwayland=True) is not None:
+        sources.append("window title")
+    elif p.is_wayland and p.desktop in ("gnome", "kde"):
+        sources.append("window title of X11 apps only")
+    return ", ".join(sources) or "no source available"

voiceio/core/bias.py

@@ -7,10 +7,11 @@ back so the limited hotword budget follows what the user actually dictates.
 from __future__ import annotations
 
 import logging
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 from voiceio.core.decoders.base import Bias, BiasMode, Capabilities
-from voiceio.tokens import HOTWORDS_TOKEN_BUDGET
+from voiceio.tokens import HOTWORDS_TOKEN_BUDGET, count_tokens, fit_prefix
 
 if TYPE_CHECKING:
     from voiceio.corrections import CorrectionDict
@@ -22,6 +23,15 @@ log = logging.getLogger(__name__)
 # Used when a bounded decoder doesn't declare its own budget.
 DEFAULT_HOTWORDS_TOKEN_BUDGET = HOTWORDS_TOKEN_BUDGET
 
+# Most of the bounded budget on-screen terms may take (context_terms.py). One
+# proper noun costs 4-6 tokens, so this is the 4-5 terms that matter for one
+# dictation, and it only displaces the static vocabulary's lowest-ranked ~20%
+# (~5-7 of ~34 terms) — and only while the screen actually offers terms. The
+# vocabulary + screen part stays inside the same budget, so the hotwords (and
+# decode cost) barely grow: only a displaced term that is also a correction
+# target comes back in the tail.
+SCREEN_TOKEN_SHARE = 24
+
 
 class BiasProvider:
     def __init__(
@@ -46,13 +56,29 @@ class BiasProvider:
         """The last `n` committed utterances (oldest first)."""
         return self._prompts.recent(n) if self._prompts is not None else []
 
-    def bias_for(self, caps: Capabilities) -> Bias:
+    def screen_terms(self, texts: Sequence[str], caps: Capabilities) -> list[str]:
+        """Terms worth biasing from on-screen text (window title, selection),
+        minus what the hotwords already carry. Never raises."""
+        if not any(texts) or not caps.bias & (BiasMode.HOTWORDS | BiasMode.UNBOUNDED):
+            return []
+        try:
+            from voiceio.context_terms import extract_terms
+            return extract_terms(
+                texts, language=self._language,
+                exclude=self._static_terms(caps) + self._rare_correction_targets(),
+                prefer=self._vocab.get_all(),
+            )
+        except Exception:  # noqa: BLE001
+            log.debug("screen term extraction failed", exc_info=True)
+            return []
+
+    def bias_for(self, caps: Capabilities, screen_terms: Sequence[str] = ()) -> Bias:
         """A fresh Bias for one recording/request. Never raises: biasing is a
         bonus and must not be able to block a dictation."""
         hotwords = None
         if caps.bias & (BiasMode.HOTWORDS | BiasMode.UNBOUNDED):
             try:
-                hotwords = self._hotwords(caps) or None
+                hotwords = self._hotwords(caps, screen_terms) or None
             except Exception:  # noqa: BLE001
                 log.debug("hotword selection failed", exc_info=True)
         prompt = None
@@ -72,16 +98,31 @@ class BiasProvider:
         except Exception:  # noqa: BLE001 — a counter must never break dictation
             log.debug("vocab usage update failed", exc_info=True)
 
-    def _hotwords(self, caps: Capabilities) -> str:
+    def _budget(self, caps: Capabilities) -> int:
+        return caps.max_bias_tokens or DEFAULT_HOTWORDS_TOKEN_BUDGET
+
+    def _static_terms(self, caps: Capabilities) -> list[str]:
         if caps.bias & BiasMode.UNBOUNDED:
-            terms = self._vocab.get_all()
-        else:
-            budget = caps.max_bias_tokens or DEFAULT_HOTWORDS_TOKEN_BUDGET
-            terms = self._vocab.get_selected(token_budget=budget)
+            return self._vocab.get_all()
+        return self._vocab.get_selected(token_budget=self._budget(caps))
+
+    def _hotwords(self, caps: Capabilities, screen_terms: Sequence[str] = ()) -> str:
+        terms = self._static_terms(caps)
+        taken = {t.lower() for t in terms}
+        screen = [t for t in screen_terms if t.lower() not in taken]
+        if screen and not caps.bias & BiasMode.UNBOUNDED:
+            # Screen terms take their share off the TAIL of the ranked
+            # vocabulary, so the total stays inside the budget.
+            model = self._vocab.model_name
+            screen = fit_prefix(screen, SCREEN_TOKEN_SHARE, model)
+            if screen:
+                used = count_tokens(", ".join(screen), model)
+                terms = fit_prefix(terms, self._budget(caps) - used, model)
         # Only RARE correction targets: common words add no bias and hundreds
         # of them blow Whisper's shared prompt+output budget.
-        extra = [t for t in self._rare_correction_targets() if t not in terms]
-        return ", ".join(terms + extra)
+        extra = [t for t in self._rare_correction_targets()
+                 if t not in terms and t not in screen]
+        return ", ".join(terms + screen + extra)
 
     def _rare_correction_targets(self) -> list[str]:
         """Cached against corrections.json's mtime (it rarely changes)."""
@@ -96,3 +137,4 @@ class BiasProvider:
             ]
             self._rare_targets_mtime = mtime
         return self._rare_targets
+

voiceio/core/engine.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import logging
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
@@ -107,11 +107,17 @@ class Engine:
     def recent(self, n: int = 3) -> list[str]:
         return self._bias.recent(n)
 
-    def bias(self) -> Bias:
+    def bias(self, screen_terms: Sequence[str] = ()) -> Bias:
         """Biasing for the next recording/request. Corrections and vocabulary
-        are mtime-cached, so edits apply without a restart."""
+        are mtime-cached, so edits apply without a restart. `screen_terms`
+        (from `screen_terms()`) take a small share of the hotword budget."""
         self.corrections.load()
-        return self._bias.bias_for(self.decoder.capabilities)
+        return self._bias.bias_for(self.decoder.capabilities, screen_terms)
+
+    def screen_terms(self, texts: Sequence[str]) -> list[str]:
+        """On-screen terms worth biasing this dictation toward (see
+        context_terms), minus what the hotwords already carry."""
+        return self._bias.screen_terms(texts, self.decoder.capabilities)
 
     def record_usage(self, text: str) -> None:
         """Feed a committed utterance back: prompt history + vocab usage."""

voiceio/health.py

@@ -224,6 +224,12 @@ def _check_features() -> FeatureGroups:
             else:
                 groups.accuracy["Vocabulary"] = "none"
 
+        if cfg.model.screen_vocabulary:
+            from voiceio.context_terms import describe as describe_screen
+            groups.accuracy["Screen vocabulary"] = f"on ({describe_screen()})"
+        else:
+            groups.accuracy["Screen vocabulary"] = "off"
+
         groups.accuracy.update(_learning_status(cfg))
 
         if cfg.postcorrect.enabled:

voiceio/learn/teacher.py

@@ -45,7 +45,7 @@ class WhisperTeacher:
         # A background batch job (see cli.learn._yield_cpu): use every core idle.
         self._model = load_model(model, device=device, compute_type=compute_type,
                                  cpu_threads=max(4, (os.cpu_count() or 8) // 2))
-        self._language = language
+        self._language = None if language in ("", "auto") else language   # None: detect
         terms = [t for t in vocabulary if t]
         # Prompt, not hotwords: hotwords are capped at 223 tokens; a prompt
         # of the most important terms still biases spelling. The tokenizer

voiceio/postprocess.py

@@ -23,6 +23,21 @@ _NO_CASE_LANGUAGES = frozenset({"zh", "ja", "ko", "ar", "he", "th", "hi", "bn",
 _FILLER_RE = re.compile(
     r"[^\S\n]*,?[^\S\n]*\b(?:[Uu]h[-\s]?huh|[Mm]hm|[Uu]h+m*|[Uu]m+|[Hh]m{2,})\b[^\S\n]*,?[^\S\n]*",
 )
+# A word (2+ letters, not part of a dotted name or an ellipsis) ending in "."
+# and followed by a lowercase word: a segment boundary, not a sentence end.
+_SEGMENT_STOP_RE = re.compile(r"(?<![.\w])([A-Za-zÀ-ɏ]{2,})\.(\s+)(?=[a-zà-ÿ])")
+_ABBREVIATIONS = frozenset({
+    "etc", "vs", "approx", "cf", "al", "mr", "mrs", "ms", "dr", "st", "jr", "sr",
+    "inc", "ltd", "co", "fig", "eq", "vol", "no", "pp", "ca", "min", "max", "sec",
+})
+
+
+def _not_an_ending(word: str) -> bool:
+    """The word before a "." is an abbreviation or a dotted name, not a
+    sentence's last word."""
+    return "." in word or word.lower() in _ABBREVIATIONS
+
+
 # A re-decode artifact is a whole duplicated sentence; require this many words
 # so emphatic short repeats ("No. No.", "Stop. Stop.") are preserved.
 _MIN_DEDUP_WORDS = 4
@@ -95,14 +110,28 @@ def cleanup(text: str, language: str = "en") -> str:
     text = re.sub(r"\s+([.,;:?!])", r"\1", text)
 
     if language not in _NO_CASE_LANGUAGES:
+        # Whisper closes every segment with "." even mid-sentence, and the next
+        # segment then carries on in lowercase ("a bit bigger. and remove the
+        # latch"): on real dictation that was 1 in 4 notes. A lowercase
+        # continuation means the sentence did not end, so it gets a comma —
+        # before the capitalization below would make the false stop permanent.
+        text = _SEGMENT_STOP_RE.sub(
+            lambda m: m.group(0) if m.group(1).lower() in _ABBREVIATIONS
+            else m.group(1) + "," + m.group(2),
+            text,
+        )
+
+
         # Capitalize first character
         text = text[0].upper() + text[1:]
 
         # Capitalize after sentence-ending punctuation (an ellipsis is a
-        # pause, not an ending)
+        # pause, not an ending, and so is the dot of "etc.", "e.g." or a name
+        # like "hugo0.com")
         text = re.sub(
-            r"(?<!\.\.)([.?!]\s+)([a-z\u00E0-\u00FF])",
-            lambda m: m.group(1) + m.group(2).upper(),
+            r"(\S*)(?<!\.\.)([.?!]\s+)([a-z\u00E0-\u00FF])",
+            lambda m: m.group(0) if m.group(2)[0] == "." and _not_an_ending(m.group(1))
+            else m.group(1) + m.group(2) + m.group(3).upper(),
             text,
         )
 

voiceio/streaming.py

@@ -156,6 +156,8 @@ class StreamingSession:
         self._decoder = decoder
         # Captured once per session: vocabulary/prompt changes made while this
         # recording runs apply to the next one, never halfway through this.
+        # The one exception is set_bias(): on-screen terms read just after
+        # the start.
         self._bias = bias or Bias()
         self._display = TypedText(typer)
         # Output-ownership gate: the app sets this so a superseded session (its
@@ -278,6 +280,12 @@ class StreamingSession:
         log.debug("Streaming session stopped, typed: %s", describe_transcript(self._display.text))
         return self._display.text
 
+    def set_bias(self, bias: Bias) -> None:
+        """Bias for passes that START from now on (one in flight keeps the
+        one it began with): the on-screen terms, captured off the hotkey path
+        after the session started."""
+        self._bias = bias
+
     def cancel(self) -> bool:
         """Abandon the dictation: stop decoding and take back what was shown
         (IBus preedit cleared, typed interim words deleted). False when the

voiceio/tokens.py

@@ -70,6 +70,23 @@ def truncate_to_tokens(text: str, max_tokens: int, model_name: str) -> str:
     space = cut.find(" ")
     return cut[space + 1:] if 0 <= space < 20 else cut
 
+def fit_prefix(terms: list[str], budget: int, model_name: str) -> list[str]:
+    """The longest prefix of `terms` whose ", "-joined form fits `budget`.
+
+    Measured joined, never summed per term: BPE merges across the separators,
+    so per-term counts double-count the joins and spend the budget ~2x too
+    fast. A binary search needs ~log2(n) encodes instead of n.
+    """
+    lo, hi = 0, len(terms)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if count_tokens(", ".join(terms[:mid]), model_name) <= budget:
+            lo = mid
+        else:
+            hi = mid - 1
+    return terms[:lo]
+
+
 # Fallback ratio when no tokenizer is available. Measured over Hugo's actual
 # vocabulary (proper nouns/technical terms), NOT prose — deliberately
 # pessimistic so an estimate never over-fills the budget.

voiceio/vocabulary.py

@@ -110,7 +110,7 @@ def select_terms(
     """
     import time
 
-    from voiceio.tokens import count_tokens
+    from voiceio.tokens import count_tokens, fit_prefix
 
     if not terms or token_budget <= 0:
         return []
@@ -121,20 +121,7 @@ def select_terms(
         key=lambda it: (-_score(it[1], stats, now), it[0]),
     )]
 
-    # Binary-search the longest ranked prefix that fits. Costing terms one by
-    # one and summing overcounts badly — BPE merges across the ", " separators,
-    # so per-term counts double-count the joins and spend the budget ~2x too
-    # fast. Measuring the joined string is the only honest count, and a prefix
-    # search needs ~log2(n) encodes instead of n.
-    lo, hi = 0, len(ranked)
-    while lo < hi:
-        mid = (lo + hi + 1) // 2
-        if count_tokens(", ".join(ranked[:mid]), model_name) <= token_budget:
-            lo = mid
-        else:
-            hi = mid - 1
-
-    selected = ranked[:lo]
+    selected = fit_prefix(ranked, token_budget, model_name)
     # Emit in ranked order — faster-whisper truncates hotwords from the tail, so
     # anything dropped downstream is the lowest-scoring term.
     if len(selected) < len(terms):
@@ -277,6 +264,10 @@ class VocabularyLoader:
         self._loaded_all = True
         self._selection_valid = False  # terms changed → re-rank
 
+    @property
+    def model_name(self) -> str:
+        return self._model_cfg.name
+
     def get_all(self) -> list[str]:
         """Every term, untruncated — for postcorrect, which has no token budget."""
         self._ensure_all()

voiceio/wordfreq.py

@@ -41,14 +41,26 @@ _CONTRACTIONS = frozenset({
 })
 
 
+def _zipf(word: str, language: str) -> float:
+    """Zipf frequency, 0.0 for a language wordfreq has no list for. "auto"
+    (detect per dictation) has no single list either: score it as English,
+    which is where the jargon in a vocabulary list usually comes from."""
+    if language in ("", "auto"):
+        language = "en"
+    try:
+        return zipf_frequency(word.lower(), language)
+    except LookupError:
+        return 0.0
+
+
 def is_common(word: str, language: str = "en", threshold: float = _ZIPF_COMMON_THRESHOLD) -> bool:
     """Check if a word is common (high frequency). Used for suggesting corrections."""
-    return zipf_frequency(word.lower(), language) >= threshold
+    return _zipf(word, language) >= threshold
 
 
 def rank(word: str, language: str = "en") -> int | None:
     """Get approximate frequency rank. None if not found."""
-    z = zipf_frequency(word.lower(), language)
+    z = _zipf(word, language)
     if z == 0.0:
         return None
     # Convert zipf to approximate rank (higher zipf = lower rank number)
@@ -61,7 +73,7 @@ def is_known(word: str, language: str = "en") -> bool:
     wl = word.lower()
     if wl in _CONTRACTIONS:
         return True
-    return zipf_frequency(wl, language) >= _ZIPF_KNOWN_THRESHOLD
+    return _zipf(wl, language) >= _ZIPF_KNOWN_THRESHOLD
 
 
 def extract_words(text: str) -> list[str]: