python-voiceio 1.8.3__tar.gz → 1.9.0__tar.gz

{python_voiceio-1.8.3/python_voiceio.egg-info → python_voiceio-1.9.0}/PKG-INFO

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

{python_voiceio-1.8.3 → python_voiceio-1.9.0}/pyproject.toml

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

{python_voiceio-1.8.3 → python_voiceio-1.9.0/python_voiceio.egg-info}/PKG-INFO

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

{python_voiceio-1.8.3 → python_voiceio-1.9.0}/python_voiceio.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ tests/test_clipboard_typer.py
 tests/test_commands.py
 tests/test_concurrency_lockdown.py
 tests/test_config.py
+tests/test_context_terms.py
 tests/test_corrections.py
 tests/test_decoders.py
 tests/test_engine.py
@@ -85,6 +86,7 @@ voiceio/clipboard_read.py
 voiceio/commands.py
 voiceio/config.py
 voiceio/consent.py
+voiceio/context_terms.py
 voiceio/corrections.py
 voiceio/demo.py
 voiceio/display.py

python_voiceio-1.9.0/tests/test_context_terms.py

@@ -0,0 +1,253 @@
+"""On-screen vocabulary: term extraction, budget share, capture deadline, and
+that capture never sits on the hotkey path."""
+from __future__ import annotations
+
+import threading
+import time
+from unittest.mock import patch
+
+import pytest
+
+from voiceio import context_terms
+from voiceio.context_terms import ScreenContext, capture, extract_terms
+from voiceio.core.bias import SCREEN_TOKEN_SHARE, BiasProvider
+from voiceio.core.decoders.base import BiasMode, Capabilities
+from voiceio.tokens import count_tokens
+
+HOTWORDS = Capabilities(bias=BiasMode.HOTWORDS | BiasMode.PROMPT, max_bias_tokens=120)
+
+
+# ── extraction ────────────────────────────────────────────────────────────
+
+
+class TestExtract:
+    def test_rare_names_camelcase_acronyms(self):
+        terms = extract_terms(["Kalshi pricing - Discord",
+                               "The HyperNEAT paper uses OpenRouter and the OKR doc."])
+        assert {"Kalshi", "HyperNEAT", "OpenRouter", "OKR"} <= set(terms)
+
+    def test_common_words_and_app_names_are_not_terms(self):
+        terms = extract_terms(["Inbox - Google Chrome",
+                               "Please check the API before the meeting with Hugo."])
+        assert terms == []
+
+    def test_multiword_name_but_not_a_greeting(self):
+        terms = extract_terms(["", "Hey Kosh, ask Tarrant Fnordwick about it."])
+        assert "Tarrant Fnordwick" in terms
+        assert "Kosh" in terms
+        assert not any(t.startswith("Hey") for t in terms)
+        # A name and its own parts would spend tokens twice on one word.
+        assert "Tarrant" not in terms and "Fnordwick" not in terms
+
+    def test_identifiers_split_numbers_dropped(self):
+        terms = extract_terms(["", "see github.com/Hugo0/voiceio and v2 of x86_64 build 2026"])
+        assert "voiceio" in terms
+        assert not any(any(c.isdigit() for c in t) for t in terms)
+
+    def test_exclude_is_case_insensitive_and_dedupes_spellings(self):
+        terms = extract_terms(["", "Kalshi kalshi KALSHI Zorblax"], exclude=["zorblax"])
+        assert [t.lower() for t in terms] == ["kalshi"]
+
+    def test_vocabulary_long_tail_ranks_first(self):
+        terms = extract_terms(["", "Zorblax met Quuxley at Wibblecorp."],
+                              prefer=["Wibblecorp"])
+        assert terms[0] == "Wibblecorp"
+
+    def test_title_beats_selection_on_ties(self):
+        terms = extract_terms(["Quuxley", "Zorblax"])
+        assert terms == ["Quuxley", "Zorblax"]
+
+    def test_repeats_outrank_one_offs(self):
+        terms = extract_terms(["", "Zorblax once. Quuxley, Quuxley, Quuxley."])
+        assert terms[0] == "Quuxley"
+
+    def test_capped(self):
+        text = " ".join(f"Zorb{chr(97 + i)}lax" for i in range(20))
+        assert len(extract_terms(["", text], max_terms=5)) == 5
+
+    def test_huge_selection_is_cheap(self):
+        text = "the quick brown fox Zorblax jumps " * 20000
+        t0 = time.monotonic()
+        assert extract_terms(["", text]) == ["Zorblax"]
+        assert time.monotonic() - t0 < 1.0
+
+    def test_empty(self):
+        assert extract_terms(["", ""]) == []
+
+
+# ── budget share in the hotwords ──────────────────────────────────────────
+
+
+def _provider(terms: list[str]) -> BiasProvider:
+    from voiceio import config
+    from voiceio.vocabulary import VocabularyLoader
+    config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    (config.CONFIG_DIR / "vocabulary.txt").write_text("\n".join(terms) + "\n")
+    return BiasProvider(VocabularyLoader(config.ModelConfig()))
+
+
+def _vocab(n: int) -> list[str]:
+    # Distinct pronounceable made-up names, in file (= rank) order.
+    syll = ["ka", "zor", "bli", "mun", "tep", "vas", "quo", "rin", "lud", "fey"]
+    return [(syll[i % 10] + syll[(i // 10) % 10] + syll[(i * 7) % 10]).capitalize() + "x"
+            for i in range(n)]
+
+
+class TestBudget:
+    def test_no_screen_terms_is_unchanged(self):
+        bp = _provider(_vocab(60))
+        assert bp.bias_for(HOTWORDS).hotwords == bp.bias_for(HOTWORDS, []).hotwords
+
+    def test_screen_terms_displace_only_the_vocabulary_tail(self):
+        vocab = _vocab(60)
+        bp = _provider(vocab)
+        base = bp.bias_for(HOTWORDS).hotwords.split(", ")
+        merged = bp.bias_for(HOTWORDS, ["Quuxley", "Wibblecorp"]).hotwords.split(", ")
+        assert "Quuxley" in merged and "Wibblecorp" in merged
+        kept = [t for t in merged if t in vocab]
+        assert kept == base[:len(kept)], "the best-ranked terms survive, in order"
+        assert len(kept) < len(base)
+        assert count_tokens(", ".join(merged), "small") <= 120 + 2  # join slack
+
+    def test_screen_share_is_capped(self):
+        bp = _provider(_vocab(60))
+        many = [f"Zorb{chr(97 + i)}laxian" for i in range(20)]
+        merged = bp.bias_for(HOTWORDS, many).hotwords.split(", ")
+        screen = [t for t in merged if t in many]
+        assert 0 < len(screen) < len(many)
+        assert count_tokens(", ".join(screen), "small") <= SCREEN_TOKEN_SHARE
+        # The vocabulary keeps the rest of the budget.
+        assert len(merged) - len(screen) >= 10
+
+    def test_screen_terms_skip_what_hotwords_carry(self):
+        bp = _provider(["Kalshi", "HyperNEAT"])
+        assert bp.screen_terms(["Kalshi - Discord", "Quuxley and HyperNEAT"], HOTWORDS) == ["Quuxley"]
+
+    def test_unbounded_appends(self):
+        bp = _provider(_vocab(60))
+        caps = Capabilities(bias=BiasMode.UNBOUNDED)
+        merged = bp.bias_for(caps, ["Quuxley"]).hotwords.split(", ")
+        assert merged[-1] == "Quuxley" and len(merged) == 61
+
+    def test_decoder_without_hotwords_gets_nothing(self):
+        bp = _provider(["Kalshi"])
+        assert bp.screen_terms(["Quuxley"], Capabilities(bias=BiasMode.PROMPT)) == []
+
+    def test_extraction_failure_degrades_to_nothing(self):
+        bp = _provider(["Kalshi"])
+        with patch("voiceio.context_terms.extract_terms", side_effect=RuntimeError):
+            assert bp.screen_terms(["Quuxley"], HOTWORDS) == []
+
+
+# ── capture: deadline and degrade ─────────────────────────────────────────
+
+
+class TestCapture:
+    def test_slow_source_is_dropped_at_the_deadline(self):
+        gate = threading.Event()
+
+        def slow(_t):
+            gate.wait(5)
+            return "Zorblax"
+
+        t0 = time.monotonic()
+        ctx = capture(0.1, readers={"title": lambda _t: "Kalshi", "selection": slow})
+        elapsed = time.monotonic() - t0
+        gate.set()
+        assert elapsed < 0.5
+        assert ctx.title == "Kalshi" and ctx.selection == ""
+
+    def test_failing_source_degrades_silently(self):
+        def boom(_t):
+            raise OSError("no display")
+        ctx = capture(0.1, readers={"title": boom, "selection": lambda _t: "x"})
+        assert ctx == ScreenContext(title="", selection="x", secs=ctx.secs)
+
+    def test_no_tools_no_selection(self, monkeypatch):
+        monkeypatch.setattr(context_terms.shutil, "which", lambda _n: None)
+        assert context_terms._read_primary(0.1) == ""
+
+    def test_gnome_wayland_never_uses_wl_paste(self, monkeypatch):
+        """wl-paste can take focus on GNOME and drop the IBus preedit."""
+        from types import SimpleNamespace
+        monkeypatch.delenv("DISPLAY", raising=False)
+        monkeypatch.setattr("voiceio.platform.detect",
+                            lambda: SimpleNamespace(is_wayland=True, desktop="gnome"))
+        monkeypatch.setattr(context_terms.shutil, "which", lambda n: f"/usr/bin/{n}")
+        with patch.object(context_terms.subprocess, "run") as run:
+            assert context_terms._read_primary(0.1) == ""
+        run.assert_not_called()
+
+    def test_selection_read_has_the_deadline_as_timeout(self, monkeypatch):
+        monkeypatch.setenv("DISPLAY", ":0")
+        monkeypatch.setattr(context_terms.shutil, "which", lambda n: f"/usr/bin/{n}")
+        with patch.object(context_terms.subprocess, "run") as run:
+            run.return_value.returncode = 0
+            run.return_value.stdout = "Zorblax".encode()
+            assert context_terms._read_primary(0.15) == "Zorblax"
+        assert run.call_args.kwargs["timeout"] == 0.15
+        assert run.call_args.args[0][:2] == ["xclip", "-o"]
+
+
+# ── the daemon: never on the hotkey path ──────────────────────────────────
+
+
+@pytest.fixture
+def vio():
+    from test_app_wiring import _make_vio
+    from fakes import FakeDecoder
+    dec = FakeDecoder()
+    dec.transcribe.return_value = "hello"
+    v, _, _ = _make_vio(dec)
+    v.cfg.model.screen_vocabulary = True
+    yield v, dec
+    if v._session is not None:
+        v._session.cancel()
+
+
+class TestDaemon:
+    def test_capture_does_not_block_recording_start(self, vio):
+        v, dec = vio
+        gate = threading.Event()
+        captured = threading.Event()
+
+        def blocked_capture(*_a, **_k):
+            gate.wait(5)
+            captured.set()
+            return ScreenContext(title="Quuxley - Discord")
+
+        with patch("voiceio.context_terms.capture", side_effect=blocked_capture):
+            t0 = time.monotonic()
+            v.on_hotkey()
+            assert time.monotonic() - t0 < 1.0
+            assert v.recorder.is_recording, "recording started while capture blocks"
+            assert "Quuxley" not in (v._recording_bias.hotwords or "")
+            gate.set()
+            assert captured.wait(5)
+            for _ in range(100):
+                if "Quuxley" in (v._recording_bias.hotwords or ""):
+                    break
+                time.sleep(0.02)
+        assert "Quuxley" in (v._recording_bias.hotwords or "")
+        assert "Quuxley" in (v._session._bias.hotwords or ""), "applied to later passes"
+
+    def test_late_capture_never_touches_the_next_recording(self, vio):
+        v, _ = vio
+        gate = threading.Event()
+        with patch("voiceio.context_terms.capture",
+                   side_effect=lambda *a, **k: (gate.wait(5), ScreenContext(title="Quuxley"))[1]):
+            v.on_hotkey()
+            rid = v._recording
+            v._recording += 1   # as if this recording ended and another began
+            gate.set()
+            time.sleep(0.3)
+        v._recording = rid
+        assert "Quuxley" not in (v._recording_bias.hotwords or "")
+
+    def test_off_reads_nothing(self, vio):
+        v, _ = vio
+        v.cfg.model.screen_vocabulary = False
+        with patch("voiceio.context_terms.capture") as cap:
+            v.on_hotkey()
+            time.sleep(0.1)
+        cap.assert_not_called()

python_voiceio-1.9.0/voiceio/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.9.0"

{python_voiceio-1.8.3 → python_voiceio-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

{python_voiceio-1.8.3 → python_voiceio-1.9.0}/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

python_voiceio-1.9.0/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"