python-voiceio 0.9.1__tar.gz → 0.9.3__tar.gz

{python_voiceio-0.9.1/python_voiceio.egg-info → python_voiceio-0.9.3}/PKG-INFO

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

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/pyproject.toml

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

{python_voiceio-0.9.1 → python_voiceio-0.9.3/python_voiceio.egg-info}/PKG-INFO

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

python_voiceio-0.9.3/tests/test_ibus_ping.py

@@ -0,0 +1,113 @@
+"""Tests for the shared engine ping used by the daemon health watchdog and
+the engine's own refuse-to-double-run guard (a duplicate engine binding the
+socket path silently starves the healthy instance)."""
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import threading
+
+import pytest
+
+import voiceio.ibus as ibus_mod
+
+# IBus (and AF_UNIX DGRAM + Linux abstract autobind) is Linux-only.
+pytestmark = pytest.mark.skipif(sys.platform != "linux", reason="IBus is Linux-only")
+
+
+def test_no_socket_returns_false(tmp_path, monkeypatch):
+    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", tmp_path / "nope.sock")
+    assert ibus_mod.ping_engine(timeout=0.2) is False
+
+
+def test_healthy_peer_answers_pong(tmp_path, monkeypatch):
+    sock_path = tmp_path / "engine.sock"
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    server.bind(str(sock_path))
+    server.settimeout(2.0)
+
+    def _serve():
+        try:
+            data, addr = server.recvfrom(64)
+            if data == b"ping" and addr:
+                server.sendto(b"pong", addr)
+        except OSError:
+            pass
+
+    t = threading.Thread(target=_serve, daemon=True)
+    t.start()
+    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", sock_path)
+    try:
+        assert ibus_mod.ping_engine(timeout=1.0) is True
+    finally:
+        t.join(timeout=2.0)
+        server.close()
+
+
+def test_unresponsive_socket_returns_false(tmp_path, monkeypatch):
+    """A bound-but-silent socket (starved listener) must read as dead."""
+    sock_path = tmp_path / "engine.sock"
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    server.bind(str(sock_path))
+    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", sock_path)
+    try:
+        assert ibus_mod.ping_engine(timeout=0.2) is False
+    finally:
+        server.close()
+
+
+class TestSingletonLock:
+    """The atomic gate that stops a duplicate engine from stealing the socket.
+
+    ibus-daemon exec-spawns its own engine copy when the voiceio source is
+    activated; only the flock holder may bind the command socket, so the loser
+    exits instead of unlink+rebind-ing it into a zombie.
+    """
+
+    def test_second_acquire_fails_while_held(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(ibus_mod, "LOCK_PATH", tmp_path / "e.lock")
+        fd = ibus_mod.acquire_singleton_lock()
+        assert fd is not None
+        try:
+            # A concurrent engine (same process here, standing in for a second
+            # process on the same file) must be refused.
+            assert ibus_mod.acquire_singleton_lock() is None
+        finally:
+            os.close(fd)
+
+    def test_reacquire_succeeds_after_holder_closes(self, tmp_path, monkeypatch):
+        """Releasing the fd (process death) frees the lock for the next engine."""
+        monkeypatch.setattr(ibus_mod, "LOCK_PATH", tmp_path / "e.lock")
+        fd = ibus_mod.acquire_singleton_lock()
+        assert fd is not None
+        os.close(fd)  # simulate the holder dying
+        fd2 = ibus_mod.acquire_singleton_lock()
+        assert fd2 is not None
+        os.close(fd2)
+
+    def test_lock_is_cross_process(self, tmp_path, monkeypatch):
+        """flock must exclude a genuinely separate process, not just this one."""
+        import subprocess
+        import textwrap
+
+        lock_path = tmp_path / "e.lock"
+        monkeypatch.setattr(ibus_mod, "LOCK_PATH", lock_path)
+        fd = ibus_mod.acquire_singleton_lock()
+        assert fd is not None
+        try:
+            # A child process using the same flock path must be refused while we
+            # hold it. Exit code 7 = "got the lock" (bad), 0 = "refused" (good).
+            code = textwrap.dedent(f"""
+                import fcntl, os, sys
+                fd = os.open({str(lock_path)!r}, os.O_CREAT | os.O_RDWR, 0o600)
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    sys.exit(7)
+                except OSError:
+                    sys.exit(0)
+            """)
+            r = subprocess.run([sys.executable, "-c", code], timeout=5)
+            assert r.returncode == 0
+        finally:
+            os.close(fd)

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/tests/test_robustness.py

@@ -63,6 +63,7 @@ def _make_recorder():
     cfg.silence_threshold = 0.01
     cfg.silence_duration = 0.6
     cfg.auto_stop_silence_secs = 5.0
+    cfg.auto_stop_no_speech_secs = 20.0
 
     with patch("voiceio.recorder.sd"):
         from voiceio.recorder import AudioRecorder
@@ -72,6 +73,78 @@ def _make_recorder():
     return rec
 
 
+class TestAutoStop:
+    """Auto-stop distinguishes 'spoke then paused' from 'nothing ever heard'."""
+
+    def _feed(self, rec, secs, *, speech):
+        """Drive _callback with `secs` of audio; speech=False → silence."""
+        rec._vad.is_speech.return_value = speech
+        frames = int(secs * rec.sample_rate)
+        rec._callback(np.zeros((frames, 1), dtype=np.float32), frames, None, None)
+
+    def test_no_speech_fires_no_speech_reason(self):
+        rec = _make_recorder()
+        rec._recording = True
+        fired = []
+        rec.set_on_auto_stop(lambda reason: fired.append(reason))
+        # 21s of pure silence, speech never heard.
+        self._feed(rec, 21, speech=False)
+        assert fired == ["no_speech"]
+
+    def test_no_speech_does_not_fire_early(self):
+        rec = _make_recorder()
+        rec._recording = True
+        fired = []
+        rec.set_on_auto_stop(lambda reason: fired.append(reason))
+        self._feed(rec, 10, speech=False)  # below the 20s threshold
+        assert fired == []
+
+    def test_speech_then_silence_fires_silence_reason(self):
+        rec = _make_recorder()
+        rec._recording = True
+        fired = []
+        rec.set_on_auto_stop(lambda reason: fired.append(reason))
+        self._feed(rec, 1, speech=True)    # heard speech → _heard_speech
+        self._feed(rec, 6, speech=False)   # 6s silence ≥ 5s auto_stop
+        assert fired == ["silence"]
+
+    def test_single_fire(self):
+        """Callback is cleared on fire — a later chunk must not re-trigger."""
+        rec = _make_recorder()
+        rec._recording = True
+        fired = []
+        rec.set_on_auto_stop(lambda reason: fired.append(reason))
+        self._feed(rec, 21, speech=False)
+        self._feed(rec, 21, speech=False)
+        assert fired == ["no_speech"]
+
+
+class TestAutoStopNotification:
+    """The app surfaces a 'no_speech' auto-stop; a plain 'silence' one is quiet."""
+
+    def test_no_speech_muted_mic_notifies(self):
+        vio, _, _ = _make_vio()
+        vio.recorder.has_signal = MagicMock(return_value=False)  # all zeros = muted
+        with patch("voiceio.feedback.notify") as notify:
+            vio._on_auto_stop("no_speech")
+        assert notify.called
+        assert "mute" in " ".join(notify.call_args[0]).lower()
+
+    def test_no_speech_with_signal_notifies_generic(self):
+        vio, _, _ = _make_vio()
+        vio.recorder.has_signal = MagicMock(return_value=True)  # mic works, user quiet
+        with patch("voiceio.feedback.notify") as notify:
+            vio._on_auto_stop("no_speech")
+        assert notify.called
+        assert "mute" not in " ".join(notify.call_args[0]).lower()
+
+    def test_normal_silence_is_quiet(self):
+        vio, _, _ = _make_vio()
+        with patch("voiceio.feedback.notify") as notify:
+            vio._on_auto_stop("silence")
+        assert not notify.called
+
+
 # ===========================================================================
 # 1. stream_health() tests
 # ===========================================================================

python_voiceio-0.9.3/voiceio/__init__.py

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

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/voiceio/app.py

@@ -283,8 +283,28 @@ class VoiceIO:
             self._last_hotkey = now
             self._toggle()
 
-    def _on_auto_stop(self) -> None:
-        """Called from audio thread when sustained silence triggers auto-stop."""
+    def _on_auto_stop(self, reason: str = "silence") -> None:
+        """Called from the audio thread when the recorder auto-stops.
+
+        reason="silence": spoke, then went quiet — a normal end of dictation.
+        reason="no_speech": nothing was heard the whole time — a muted mic or a
+        hotkey pressed by accident. Surface it so it isn't a silent failure
+        (today's Discord-mute confusion: recording ran, nothing was captured,
+        and there was no sign why).
+        """
+        if reason == "no_speech":
+            from voiceio import feedback
+            if not self.recorder.has_signal():
+                feedback.notify(
+                    "VoiceIO: microphone is muted",
+                    "Stopped — no audio is reaching voiceio. Check your mic's "
+                    "mute button and that the right input device is selected.",
+                )
+            else:
+                feedback.notify(
+                    "VoiceIO: stopped — no speech detected",
+                    "Recording auto-stopped after silence.",
+                )
         threading.Thread(target=self._request_stop, daemon=True).start()
 
     def _request_stop(self) -> None:

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/voiceio/config.py

@@ -71,6 +71,11 @@ class AudioConfig:
     silence_threshold: float = 0.01
     silence_duration: float = 0.6
     auto_stop_silence_secs: float = 5.0
+    # Safety net for a muted mic or a forgotten hotkey: if NO speech is heard
+    # for this long from the start, stop and notify. The 5s auto-stop above
+    # only fires once speech has been heard, so it can't catch a dead mic.
+    # 0 disables.
+    auto_stop_no_speech_secs: float = 20.0
     vad_backend: str = "silero"  # "silero" | "rms"
     vad_threshold: float = 0.5  # Silero speech probability threshold
 

python_voiceio-0.9.3/voiceio/ibus/__init__.py

@@ -0,0 +1,64 @@
+"""IBus input method engine for VoiceIO."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+SOCKET_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.sock"
+READY_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.ready"
+# Held for the engine's lifetime so exactly one process ever owns the command
+# socket — see acquire_singleton_lock().
+LOCK_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.lock"
+
+
+def acquire_singleton_lock() -> int | None:
+    """Take an exclusive, lifetime-held lock on LOCK_PATH.
+
+    Returns the open fd on success (the caller must keep it open — the lock is
+    released when the fd closes, i.e. when the process dies), or None if another
+    engine already holds it.
+
+    This is the race-free gate against duplicate engines. ibus-daemon
+    exec-spawns its own copy of the engine when something activates the voiceio
+    source (GNOME's per-window source memory / Super+Space — voiceio sits first
+    in mru-sources). A ping-then-bind check is check-then-act: two engines
+    starting close together both see "no healthy peer", then both unlink+rebind
+    the DGRAM socket in _socket_listener. The loser is left bound to an orphaned
+    inode — alive but never receiving pings ("zombie") — which the daemon's
+    health watchdog then kills and respawns, churning ~15x/day. flock is atomic:
+    the loser never touches the socket, it just exits.
+    """
+    import fcntl
+
+    fd = os.open(str(LOCK_PATH), os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        os.close(fd)
+        return None
+    return fd
+
+
+def ping_engine(timeout: float = 2.0) -> bool:
+    """True if a live engine answers a ping on SOCKET_PATH.
+
+    Used by the daemon's health watchdog, and by the engine itself at
+    startup to refuse to double-run: a second engine binding the socket
+    path would silently starve the healthy instance (its listener stays
+    blocked on a socket inode that no longer receives anything).
+    """
+    import socket
+
+    if not SOCKET_PATH.exists():
+        return False
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    try:
+        sock.settimeout(timeout)
+        sock.bind("")  # Linux autobind: gives us an address for the reply
+        sock.sendto(b"ping", str(SOCKET_PATH))
+        data, _ = sock.recvfrom(64)
+        return data == b"pong"
+    except OSError:
+        return False
+    finally:
+        sock.close()

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/voiceio/ibus/engine.py

@@ -24,10 +24,18 @@ import gi
 gi.require_version("IBus", "1.0")
 from gi.repository import GLib, GObject, IBus
 
-from voiceio.ibus import READY_PATH, SOCKET_PATH, ping_engine
+from voiceio.ibus import (
+    READY_PATH,
+    SOCKET_PATH,
+    acquire_singleton_lock,
+)
 from voiceio.ibus.pending import PendingBuffer
 
 log = logging.getLogger(__name__)
+
+# Singleton lock fd, held for the process lifetime (see main()). Module-level so
+# it is never garbage-collected — closing the fd would release the lock.
+_lock_fd: int | None = None
 ENGINE_NAME = "voiceio"
 COMPONENT_NAME = "org.voiceio.ibus"
 
@@ -230,13 +238,17 @@ def main() -> None:
         ],
     )
 
-    # Refuse to double-run. ibus-daemon can exec-spawn its own copy of this
-    # engine (component XML) when something activates the voiceio source —
-    # e.g. GNOME's per-window source memory. Binding SOCKET_PATH here would
-    # steal it from the healthy daemon-spawned engine and silently starve it
-    # (alive, but never sees another command or ping → zombie recovery).
-    if ping_engine(timeout=0.5):
-        log.info("Healthy VoiceIO engine already serving %s — exiting duplicate", SOCKET_PATH)
+    # Refuse to double-run, race-free. ibus-daemon exec-spawns its own copy of
+    # this engine (component XML) when something activates the voiceio source
+    # (GNOME per-window source memory / Super+Space — voiceio is first in
+    # mru-sources). Without an atomic gate, two engines both pass a ping check
+    # then both unlink+rebind SOCKET_PATH in _socket_listener; the loser is
+    # left on an orphaned inode — a "zombie" the watchdog kills and respawns.
+    # The lock fd is held for our whole lifetime (released on process death).
+    global _lock_fd
+    _lock_fd = acquire_singleton_lock()
+    if _lock_fd is None:
+        log.info("Another VoiceIO engine holds the lock — exiting duplicate")
         return
 
     IBus.init()

{python_voiceio-0.9.1 → python_voiceio-0.9.3}/voiceio/recorder.py

@@ -108,9 +108,12 @@ class AudioRecorder:
 
         # Auto-stop on sustained silence
         self._auto_stop_secs = cfg.auto_stop_silence_secs
+        self._no_speech_secs = cfg.auto_stop_no_speech_secs
         self._sustained_silence = 0.0
         self._heard_speech = False
-        self._on_auto_stop: Callable[[], None] | None = None
+        # Called with a reason: "silence" (spoke then paused) or "no_speech"
+        # (nothing ever heard — a muted mic or a forgotten hotkey).
+        self._on_auto_stop: Callable[[str], None] | None = None
 
         # Heartbeat: updated by _callback, checked by health watchdog
         self._last_callback_time: float = 0.0
@@ -260,7 +263,7 @@ class AudioRecorder:
         """Set/clear the speech pause callback (used by streaming session)."""
         self._on_speech_pause = callback
 
-    def set_on_auto_stop(self, callback: Callable[[], None] | None) -> None:
+    def set_on_auto_stop(self, callback: Callable[[str], None] | None) -> None:
         """Set/clear the auto-stop callback (fires after sustained silence)."""
         self._on_auto_stop = callback
 
@@ -340,4 +343,20 @@ class AudioRecorder:
             self._on_auto_stop = None
             self._sustained_silence = 0.0
             log.info("Auto-stopping after %.0fs of silence", self._auto_stop_secs)
-            cb()
+            cb("silence")
+
+        # Safety net: nothing heard at all for a long time. Because speech
+        # resets _sustained_silence AND is gated out by not-_heard_speech, this
+        # measures continuous silence from the very start of the recording — a
+        # muted mic (all zeros) or a hotkey pressed by accident. Distinct reason
+        # so the app can surface it instead of failing silently.
+        elif (self._on_auto_stop is not None
+                and self._no_speech_secs > 0
+                and not self._heard_speech
+                and self._sustained_silence >= self._no_speech_secs):
+            cb = self._on_auto_stop
+            self._on_auto_stop = None
+            self._sustained_silence = 0.0
+            log.info("Auto-stopping: no speech heard in %.0fs (mic muted?)",
+                     self._no_speech_secs)
+            cb("no_speech")

python_voiceio-0.9.1/tests/test_ibus_ping.py

@@ -1,56 +0,0 @@
-"""Tests for the shared engine ping used by the daemon health watchdog and
-the engine's own refuse-to-double-run guard (a duplicate engine binding the
-socket path silently starves the healthy instance)."""
-from __future__ import annotations
-
-import socket
-import sys
-import threading
-
-import pytest
-
-import voiceio.ibus as ibus_mod
-
-# IBus (and AF_UNIX DGRAM + Linux abstract autobind) is Linux-only.
-pytestmark = pytest.mark.skipif(sys.platform != "linux", reason="IBus is Linux-only")
-
-
-def test_no_socket_returns_false(tmp_path, monkeypatch):
-    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", tmp_path / "nope.sock")
-    assert ibus_mod.ping_engine(timeout=0.2) is False
-
-
-def test_healthy_peer_answers_pong(tmp_path, monkeypatch):
-    sock_path = tmp_path / "engine.sock"
-    server = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
-    server.bind(str(sock_path))
-    server.settimeout(2.0)
-
-    def _serve():
-        try:
-            data, addr = server.recvfrom(64)
-            if data == b"ping" and addr:
-                server.sendto(b"pong", addr)
-        except OSError:
-            pass
-
-    t = threading.Thread(target=_serve, daemon=True)
-    t.start()
-    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", sock_path)
-    try:
-        assert ibus_mod.ping_engine(timeout=1.0) is True
-    finally:
-        t.join(timeout=2.0)
-        server.close()
-
-
-def test_unresponsive_socket_returns_false(tmp_path, monkeypatch):
-    """A bound-but-silent socket (starved listener) must read as dead."""
-    sock_path = tmp_path / "engine.sock"
-    server = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
-    server.bind(str(sock_path))
-    monkeypatch.setattr(ibus_mod, "SOCKET_PATH", sock_path)
-    try:
-        assert ibus_mod.ping_engine(timeout=0.2) is False
-    finally:
-        server.close()

python_voiceio-0.9.1/voiceio/__init__.py

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

python_voiceio-0.9.1/voiceio/ibus/__init__.py

@@ -1,33 +0,0 @@
-"""IBus input method engine for VoiceIO."""
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-SOCKET_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.sock"
-READY_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio-ibus.ready"
-
-
-def ping_engine(timeout: float = 2.0) -> bool:
-    """True if a live engine answers a ping on SOCKET_PATH.
-
-    Used by the daemon's health watchdog, and by the engine itself at
-    startup to refuse to double-run: a second engine binding the socket
-    path would silently starve the healthy instance (its listener stays
-    blocked on a socket inode that no longer receives anything).
-    """
-    import socket
-
-    if not SOCKET_PATH.exists():
-        return False
-    sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
-    try:
-        sock.settimeout(timeout)
-        sock.bind("")  # Linux autobind: gives us an address for the reply
-        sock.sendto(b"ping", str(SOCKET_PATH))
-        data, _ = sock.recvfrom(64)
-        return data == b"pong"
-    except OSError:
-        return False
-    finally:
-        sock.close()