python-voiceio 1.15.0__tar.gz → 1.15.2__tar.gz

{python_voiceio-1.15.0/python_voiceio.egg-info → python_voiceio-1.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.15.0
+Version: 1.15.2
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -146,6 +146,10 @@ Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](confi
 
 Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
 
+## How it's built
+
+I write voiceio with AI coding assistants, mostly Claude Code. I decide what goes in and I use it every day, which is how most of its bugs get found.
+
 ## Credits
 
 - Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models; [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) with NVIDIA's [Parakeet-TDT](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2). The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/README.md

@@ -93,6 +93,10 @@ Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](confi
 
 Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
 
+## How it's built
+
+I write voiceio with AI coding assistants, mostly Claude Code. I decide what goes in and I use it every day, which is how most of its bugs get found.
+
 ## Credits
 
 - Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models; [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) with NVIDIA's [Parakeet-TDT](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2). The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/pyproject.toml

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

{python_voiceio-1.15.0 → python_voiceio-1.15.2/python_voiceio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.15.0
+Version: 1.15.2
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -146,6 +146,10 @@ Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](confi
 
 Open an issue before a large PR. [CONTRIBUTING.md](CONTRIBUTING.md) covers the architecture, conventions and the reasoning behind the model choice. Install reports and ideas are welcome on the [feedback board](https://voiceio.dev/#feedback).
 
+## How it's built
+
+I write voiceio with AI coding assistants, mostly Claude Code. I decide what goes in and I use it every day, which is how most of its bugs get found.
+
 ## Credits
 
 - Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models; [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) with NVIDIA's [Parakeet-TDT](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v2). The in-browser demo runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/python_voiceio.egg-info/SOURCES.txt

@@ -79,6 +79,7 @@ tests/test_streaming.py
 tests/test_suggest.py
 tests/test_tokens.py
 tests/test_transcriber.py
+tests/test_tray.py
 tests/test_tts.py
 tests/test_typer_manager.py
 tests/test_vad.py

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_feedback_stream.py

@@ -1,11 +1,11 @@
 """The persistent cue stream: buffer size and cue timing."""
 from __future__ import annotations
 
-import pytest
+from types import SimpleNamespace
 
-pytest.importorskip("sounddevice")
+import pytest
 
-from voiceio import feedback  # noqa: E402
+from voiceio import feedback
 
 
 class FakeStream:
@@ -24,7 +24,7 @@ class FakeStream:
 @pytest.fixture
 def fake_stream(monkeypatch):
     FakeStream.opened = []
-    monkeypatch.setattr(feedback.sd, "OutputStream", FakeStream)
+    monkeypatch.setattr(feedback, "sd", SimpleNamespace(OutputStream=FakeStream))
     monkeypatch.setattr(feedback, "_stream", None)
     monkeypatch.setattr(feedback, "_sounds", {})
     return FakeStream

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_health.py

@@ -123,3 +123,29 @@ def test_learning_status_and_tips(monkeypatch):
     assert st["Voice model"] == "fine-tuned on you (v0001-small-x)"
     assert st["Recordings"].startswith("on (") and st["Scheduled learning"] == "off"
     assert any("learn schedule on" in t for t in _accuracy_tips(st))
+
+
+def test_silent_ibus_engine_is_not_a_warning_while_voiceio_is_stopped():
+    from voiceio.health import HealthReport, IBusStatus
+    p = Platform(os="linux", display_server="wayland", desktop="kde")
+    ib = IBusStatus(component_installed=True, daemon_running=True, voiceio_running=False)
+    text = format_report(HealthReport(platform=p, ibus_checks=ib))
+    line = next(ln for ln in text.splitlines() if "Engine answers" in ln)
+    assert "⚠" not in line and "isn't running" in line
+    ib.voiceio_running = True
+    line = next(ln for ln in format_report(HealthReport(platform=p, ibus_checks=ib)).splitlines()
+                if "Engine answers" in ln)
+    assert "⚠" in line and "service restart" in line
+
+
+def test_check_ibus_asks_about_voiceio_only_when_the_engine_is_silent():
+    from voiceio import health
+    with patch("voiceio.ibus.install.component_installed", return_value=True), \
+         patch("voiceio.ibus.install.daemon_running", return_value=True), \
+         patch("voiceio.ibus.ping_engine", return_value=False), \
+         patch("voiceio.pidlock.daemon_alive", return_value=False) as alive:
+        assert health._check_ibus().voiceio_running is False
+        with patch("voiceio.ibus.ping_engine", return_value=True):
+            alive.reset_mock()
+            assert health._check_ibus().voiceio_running is True
+            alive.assert_not_called()

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_idle_audio.py

@@ -3,17 +3,16 @@ from __future__ import annotations
 
 import threading
 import time
+from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 import numpy as np
 import pytest
 
-pytest.importorskip("sounddevice")
-
-from voiceio import feedback, idle_audio  # noqa: E402
-from voiceio.config import AudioConfig, Config  # noqa: E402
-from voiceio.idle_audio import IdleAudio  # noqa: E402
-from voiceio.recorder import AudioRecorder  # noqa: E402
+from voiceio import feedback, idle_audio
+from voiceio.config import AudioConfig, Config
+from voiceio.idle_audio import IdleAudio
+from voiceio.recorder import AudioRecorder
 
 
 class FakeInput:
@@ -50,8 +49,9 @@ class FakeOutput(FakeInput):
 @pytest.fixture
 def streams(monkeypatch):
     FakeInput.opened = FakeOutput.opened = 0
-    monkeypatch.setattr("voiceio.recorder.sd.InputStream", FakeInput)
-    monkeypatch.setattr(feedback.sd, "OutputStream", FakeOutput)
+    # Whole fakes: touching the real module would initialize PortAudio.
+    monkeypatch.setattr("voiceio.recorder.sd", SimpleNamespace(InputStream=FakeInput))
+    monkeypatch.setattr(feedback, "sd", SimpleNamespace(OutputStream=FakeOutput))
     monkeypatch.setattr(feedback, "_stream", None)
 
 

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_postprocess.py

@@ -88,6 +88,20 @@ class TestStripDisfluencies:
         assert strip_disfluencies("uh-huh right") == "right"
         assert strip_disfluencies("uh huh yes") == "yes"
 
+    def test_mm_hmm_goes_whole(self):
+        # Parakeet ends about 1 clip in 4 with an invented "Mm-hmm."; cutting
+        # only its "hmm" typed a stray "Mm-." after real dictation.
+        assert strip_disfluencies("I sent it. Mm-hmm.") == "I sent it."
+        assert strip_disfluencies("Are you sure? Mm-hmm.") == "Are you sure?"
+        assert strip_disfluencies("Mm-hmm.") == ""
+        assert strip_disfluencies("Fine. Mm-hmm. So it works.") == "Fine. So it works."
+        assert strip_disfluencies("mmhmm that works") == "that works"
+
+    def test_fillers_inside_hyphenated_words_survive(self):
+        assert strip_disfluencies("a hmm-hmm sound") == "a hmm-hmm sound"
+        assert strip_disfluencies("she said uh-uh twice") == "she said uh-uh twice"
+        assert strip_disfluencies("the 5 mm drill") == "the 5 mm drill"
+
     def test_preserves_emphatic_short_repeat(self):
         # Short repeats are emphasis, not a re-decode artifact — keep them.
         assert strip_disfluencies("No. No.") == "No. No."

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_report.py

@@ -9,7 +9,7 @@ import pytest
 
 from voiceio import report
 from voiceio.config import Config
-from voiceio.health import BackendStatus, HealthReport
+from voiceio.health import BackendStatus, HealthReport, IBusStatus
 from voiceio.platform import Platform
 
 FAKE_HOME = "/home/zelda-tester"
@@ -104,6 +104,16 @@ def test_report_lists_failures_and_warnings():
     assert "insecure permissions on 2 file(s)" in text
 
 
+def test_silent_ibus_engine_is_expected_while_voiceio_is_stopped():
+    # Two 1.15.0 reports warned "ibus engine ping" only because voiceio wasn't running.
+    ib = IBusStatus(component_installed=True, daemon_running=True, env_persisted=True)
+    stopped = report.build_report(_health(ibus_checks=IBusStatus(**{**vars(ib), "voiceio_running": False})),
+                                  cfg=Config())
+    assert "engine ping" not in stopped and "voiceio not running" in stopped
+    running = report.build_report(_health(ibus_checks=ib), cfg=Config())
+    assert "ibus engine ping" in running and "voiceio not running" not in running
+
+
 def test_comment_is_one_bounded_line():
     text = report.build_report(_health(), comment="a\nb\tc " + "x" * 1000, cfg=Config())
     line = next(ln for ln in text.splitlines() if ln.startswith("comment:"))
@@ -111,6 +121,14 @@ def test_comment_is_one_bounded_line():
     assert len(line) <= len("comment: ") + report.MAX_COMMENT
 
 
+def test_comment_drops_terminal_escapes():
+    # A real 1.15.0 report arrived with "comment: \x1bv" (Alt+V at the prompt).
+    text = report.build_report(_health(), comment="\x1bv", cfg=Config())
+    assert "comment:" not in text and "\x1b" not in text
+    text = report.build_report(_health(), comment="works\x1b[D\x1b[C great\x07", cfg=Config())
+    assert "comment: works great" in text.splitlines()
+
+
 # ── posting ──
 
 class _Resp(io.BytesIO):

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/tests/test_robustness.py

@@ -936,3 +936,20 @@ class TestZombieStreamRecovery:
         # any real signal → not a zombie
         rec._ring.append(np.full(rec._ring._max, 0.1, dtype=np.float32))
         assert rec.is_zombie() is False
+
+
+def test_app_imports_when_portaudio_cannot_initialize(tmp_path):
+    # ubuntu-26.04 runners: libportaudio2 pulls libpulse0, and with no pulse
+    # server `import sounddevice` raises; importing voiceio.app must not.
+    import subprocess
+    import sys
+    (tmp_path / "sounddevice.py").write_text(
+        "class PortAudioError(Exception): pass\n"
+        "raise PortAudioError('PulseAudio_Initialize: Can\\'t connect to server')\n")
+    code = ("import voiceio.app, voiceio.recorder as r\n"
+            "try:\n    r.sd.InputStream\nexcept Exception as e:\n"
+            "    print(type(e).__name__)\n")
+    out = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True,
+                         env={**__import__("os").environ, "PYTHONPATH": str(tmp_path)})
+    assert out.returncode == 0, out.stderr
+    assert out.stdout.strip() == "PortAudioError"

python_voiceio-1.15.2/tests/test_tray.py

@@ -0,0 +1,58 @@
+"""Tray backend probing: what doctor/setup promise must match what start() does."""
+from __future__ import annotations
+
+import builtins
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from voiceio import tray
+from voiceio.tray import _pystray
+
+linux = pytest.mark.skipif(not sys.platform.startswith("linux"), reason="linux probe")
+
+
+@linux
+def test_appindicator_wins():
+    with patch.object(tray, "_find_system_python", return_value="/usr/bin/python3"):
+        assert tray.probe_availability() == (True, "AppIndicator3 available", "")
+
+
+@linux
+def test_pystray_xembed_fallback_counts_as_a_tray():
+    # KDE/LXQt users without python3-gi got "no tray" though start() falls back to pystray.
+    with patch.object(tray, "_find_system_python", return_value=None), \
+         patch.object(tray, "_pystray_backend", return_value="xorg"):
+        ok, reason, hint = tray.probe_availability()
+    assert ok and "no menu" in reason and "for the full menu" in hint
+
+
+@linux
+def test_no_backend_at_all():
+    with patch.object(tray, "_find_system_python", return_value=None), \
+         patch.object(tray, "_pystray_backend", return_value=None):
+        ok, reason, hint = tray.probe_availability()
+    assert not ok and "AppIndicator3" in reason and hint.startswith("install:")
+
+
+def _import_raising(exc):
+    real = builtins.__import__
+
+    def fake(name, *a, **kw):
+        if name == "pystray":
+            raise exc
+        return real(name, *a, **kw)
+    return fake
+
+
+class _DisplayNameError(Exception):
+    """Stands in for Xlib.error.DisplayNameError (no DISPLAY): not an ImportError."""
+
+
+def test_pystray_without_x_display_does_not_raise(monkeypatch):
+    monkeypatch.delitem(sys.modules, "pystray", raising=False)
+    with patch("builtins.__import__", _import_raising(_DisplayNameError(":0"))):
+        assert tray._pystray_backend() is None
+        assert _pystray.start(lambda: None, Path("idle.png"), []) is False

python_voiceio-1.15.2/voiceio/__init__.py

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

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/feedback.py

@@ -20,11 +20,9 @@ from pathlib import Path
 
 import numpy as np
 
-try:
-    import sounddevice as sd
-except ImportError as _e:
-    from voiceio.platform import desktop_dep_hint
-    raise ImportError(desktop_dep_hint("sounddevice")) from _e
+from voiceio.platform import LazySounddevice
+
+sd = LazySounddevice()
 
 log = logging.getLogger(__name__)
 

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/health.py

@@ -25,6 +25,8 @@ class IBusStatus:
     component_installed: bool = False
     daemon_running: bool = False
     socket_reachable: bool = False
+    # The engine runs while voiceio does, so a silent one only matters then.
+    voiceio_running: bool = True
     gnome_source_configured: bool = False
     env_persisted: bool = False
 
@@ -301,6 +303,10 @@ def _check_ibus() -> IBusStatus:
     # Ping, not exists(): an engine can hold a socket file yet be deaf.
     from voiceio.ibus import ping_engine
     status.socket_reachable = ping_engine(timeout=1.0)
+    if not status.socket_reachable:
+        from voiceio.config import PID_PATH
+        from voiceio.pidlock import daemon_alive
+        status.voiceio_running = daemon_alive(PID_PATH)
 
     # Check GNOME input source
     try:
@@ -433,7 +439,9 @@ def format_report(report: HealthReport) -> str:
     lines.append(_check_line("Tray icon", report.tray_ok,
                              report.tray_reason if not report.tray_ok else "",
                              warn=not report.tray_ok))
-    if report.tray_fix_hint and not report.tray_ok:
+    if report.tray_ok and report.tray_fix_hint:  # works, but degraded
+        lines[-1] += f"  {DIM}{report.tray_reason}{RESET}"
+    if report.tray_fix_hint:
         lines.append(f"    {DIM}→ {report.tray_fix_hint}{RESET}")
 
     # IBus pipeline
@@ -448,6 +456,10 @@ def format_report(report: HealthReport) -> str:
             ("GNOME input source", ibus.gnome_source_configured, "voiceio setup"),
             ("Env persisted (reboot-safe)", ibus.env_persisted, "voiceio setup"),
         ]:
+            if label == "Engine answers" and not ok and not ibus.voiceio_running:
+                lines.append(f"  {DIM}–{RESET} {label}  "
+                             f"{DIM}starts with voiceio, which isn't running{RESET}")
+                continue
             lines.append(_check_line(label, ok, hint if not ok else "",
                                      warn=not ok))
 

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/platform.py

@@ -15,6 +15,22 @@ log = logging.getLogger(__name__)
 DESKTOP_EXTRA_INSTALL = "pipx install --force 'python-voiceio[desktop]'"
 
 
+class LazySounddevice:
+    """`sounddevice`, imported on first use. Its import initializes PortAudio,
+    which raises when libpulse is installed but no sound server runs (CI,
+    headless boxes): imported eagerly, that broke `import voiceio.app` and
+    every command behind it."""
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):  # introspection (mock, inspect) must not import it
+            raise AttributeError(name)
+        try:
+            import sounddevice
+        except ImportError as e:
+            raise ImportError(desktop_dep_hint("sounddevice")) from e
+        return getattr(sounddevice, name)
+
+
 def desktop_dep_hint(package: str) -> str:
     """One-line message for a desktop dependency that failed to import."""
     return (

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/postprocess.py

@@ -19,8 +19,9 @@ _NO_CASE_LANGUAGES = frozenset({"zh", "ja", "ko", "ar", "he", "th", "hi", "bn",
 #     own line doesn't swallow the paragraph/list break around it.
 # Word repetitions ("had had" is valid English) and filler "like"/"you know"
 # need judgment and are left to the LLM layer. Order matters: multi-token
-# "uh-huh" before "[Uu]h+" so it isn't clipped to a stray "-huh".
-_FILLER = r"\b(?:[Uu]h[-\s]?huh|[Mm]hm|[Uu]h+m*|[Uu]m+|[Hh]m{2,})\b"
+# "uh-huh" and "mm-hmm" (Parakeet invents "Mm-hmm." on a clip's quiet tail)
+# before the bare forms. Never a piece of a hyphenated word: that left "Mm-.".
+_FILLER = r"(?<!-)\b(?:[Uu]h[-\s]?huh|[Mm]m-?[Hh]m+|[Mm]hm|[Uu]h+m*|[Uu]m+|[Hh]m{2,})\b(?!-)"
 # A run of fillers and the comma/space around it; the lowercase letter after it, when
 # it opened a sentence, gets capitalized ("those. Um so I" -> "those. So I"),
 # or the sentence end before it would read as a false stop and become a comma.

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/recorder.py

@@ -8,19 +8,15 @@ from typing import TYPE_CHECKING, Callable
 
 import numpy as np
 
-try:
-    import sounddevice as sd
-except ImportError as _e:
-    from voiceio.platform import desktop_dep_hint
-    raise ImportError(desktop_dep_hint("sounddevice")) from _e
-
 from voiceio.audio_source import AudioBuffer
+from voiceio.platform import LazySounddevice
 
 if TYPE_CHECKING:
     from voiceio.config import AudioConfig
     from voiceio.vad import VadBackend
 
 log = logging.getLogger(__name__)
+sd = LazySounddevice()
 
 # Peak amplitude below this is treated as no signal at all (a muted mic emits
 # exact zeros; a working mic's "silence" still noises above ~1e-4). Matches the

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/report.py

@@ -30,6 +30,8 @@ TIMEOUT_SECS = 8.0
 MAX_COMMENT = 300
 MAX_DETAIL = 90
 
+# A terminal escape: CSI sequences (arrow keys) or ESC plus one key (Alt+key).
+_ESCAPE = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|.)?", re.S)
 _IPV4 = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
 _IPV6 = re.compile(r"\b(?:[0-9a-f]{1,4}:){3,7}[0-9a-f]{1,4}\b", re.I)
 _MAC = re.compile(r"\b(?:[0-9a-f]{2}[:-]){5}[0-9a-f]{2}\b", re.I)
@@ -155,7 +157,7 @@ def build_report(
     if health.ibus_checks is not None:
         ib = health.ibus_checks
         for label, ok in (("component", ib.component_installed), ("daemon", ib.daemon_running),
-                          ("engine ping", ib.socket_reachable),
+                          ("engine ping", ib.socket_reachable or not ib.voiceio_running),
                           ("env persisted", ib.env_persisted)):
             if not ok:
                 warned.append(f"ibus {label}")
@@ -178,7 +180,9 @@ def build_report(
         f"python {_py_platform.python_version()}",
         f"backends: hotkey {hotkey.name if hotkey else 'none'} · "
         f"typer {typer.name if typer else 'none'} · audio {audio} "
-        f"(vad {cfg.audio.vad_backend})",
+        f"(vad {cfg.audio.vad_backend})"
+        + (" · voiceio not running" if health.ibus_checks is not None
+           and not health.ibus_checks.voiceio_running else ""),
         f"model: {_model_label(cfg.model.name)}",
     ]
     if unavailable:
@@ -186,6 +190,7 @@ def build_report(
     lines.append("failed: " + "; ".join(failed) if failed else "failed: none")
     if warned:
         lines.append("warnings: " + "; ".join(warned))
+    comment = "".join(c if c.isprintable() else " " for c in _ESCAPE.sub("", comment))
     comment = " ".join(comment.split())[:MAX_COMMENT]
     if comment:
         lines.append(f"comment: {comment}")
@@ -233,6 +238,10 @@ def _interactive() -> bool:
 
 
 def _ask(prompt: str) -> str:
+    try:
+        import readline  # noqa: F401  line editing, so arrow keys don't type escapes
+    except ImportError:
+        pass
     try:
         return input(prompt)
     except (EOFError, KeyboardInterrupt):

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/setup/steps.py

@@ -184,7 +184,8 @@ def _print_tray_check() -> bool:
     from voiceio.tray import probe_availability
     tray_ok, tray_reason, tray_fix_hint = probe_availability()
     if tray_ok:
-        _print_check("Tray icon", True, "system tray indicator available")
+        _print_check("Tray icon", True, f"{tray_reason}; {tray_fix_hint}" if tray_fix_hint
+                     else "system tray indicator available")
     else:
         _print_check("Tray icon", False,
                      tray_fix_hint if tray_fix_hint else tray_reason,

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/tray/__init__.py

@@ -59,11 +59,16 @@ def probe_availability() -> tuple[bool, str, str]:
         if py:
             return True, "AppIndicator3 available", ""
         from voiceio.platform import pkg_install
+        hint = f"install: {pkg_install('python3-gi', 'gir1.2-ayatanaappindicator3-0.1')}"
+        if _pystray_backend() == "xorg":
+            # What start() falls back to: an XEmbed icon (KDE and LXQt show
+            # it), animated, but without the menu.
+            return True, "basic icon (pystray, no menu)", f"for the full menu, {hint}"
         return (
             False,
             "no python3 with GTK3/AppIndicator3 bindings "
             "(set VOICEIO_SYSTEM_PYTHON to override)",
-            f"install: {pkg_install('python3-gi', 'gir1.2-ayatanaappindicator3-0.1')}",
+            hint,
         )
     elif sys.platform == "darwin":
         try:
@@ -82,6 +87,15 @@ def probe_availability() -> tuple[bool, str, str]:
     return False, "unsupported platform", ""
 
 
+def _pystray_backend() -> str | None:
+    """The backend pystray picks here ("xorg", "appindicator", ...), or None."""
+    try:
+        import pystray
+    except Exception:  # ImportError, or Xlib errors when there's no X display
+        return None
+    return pystray.Icon.__module__.rsplit("._", 1)[-1]
+
+
 def _start_indicator(
     theme_dir: Path,
     icon_names: list[str],

{python_voiceio-1.15.0 → python_voiceio-1.15.2}/voiceio/tray/_pystray.py

@@ -35,6 +35,9 @@ def start(
     except ImportError:
         log.warning("pystray/Pillow not installed, tray icon disabled")
         return False
+    except Exception as e:  # Linux import opens an X display: none means Xlib errors
+        log.warning("pystray unusable (%s), tray icon disabled", e)
+        return False
 
     _idle_img = Image.open(idle_path)
     _recording_frames = [Image.open(p) for p in frame_paths]

python_voiceio-1.15.0/voiceio/__init__.py

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