python-voiceio 1.13.0__tar.gz → 1.14.0__tar.gz

{python_voiceio-1.13.0/python_voiceio.egg-info → python_voiceio-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.13.0
+Version: 1.14.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -109,6 +109,15 @@ voiceio learn status                  # what it learned and how each model score
 
 Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
+## Let your agents talk to you
+
+```bash
+voiceio say --from build-bot "tests are green"     # chime, notification, then it's read aloud
+voiceio say --from deploy --urgent "I need your approval"
+```
+
+Running several coding agents? Have each one call `voiceio say` when it needs you, so you hear *which* one. It never talks over you: while you dictate, announcements wait (speech into an open mic would get typed). They are read in your [tts] voice, offline.
+
 ## Configure
 
 Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/README.md

@@ -56,6 +56,15 @@ voiceio learn status                  # what it learned and how each model score
 
 Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
+## Let your agents talk to you
+
+```bash
+voiceio say --from build-bot "tests are green"     # chime, notification, then it's read aloud
+voiceio say --from deploy --urgent "I need your approval"
+```
+
+Running several coding agents? Have each one call `voiceio say` when it needs you, so you hear *which* one. It never talks over you: while you dictate, announcements wait (speech into an open mic would get typed). They are read in your [tts] voice, offline.
+
 ## Configure
 
 Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/pyproject.toml

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

{python_voiceio-1.13.0 → python_voiceio-1.14.0/python_voiceio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.13.0
+Version: 1.14.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -109,6 +109,15 @@ voiceio learn status                  # what it learned and how each model score
 
 Scheduled learning runs daily or weekly at a time you pick, on mains power and only while you're away from the computer: it stops within seconds when you come back and resumes later where it was. You get a notification with a button to stop it. It never switches models unless the new one wins, and `voiceio learn rollback` undoes a switch. Details: [docs/learning.md](docs/learning.md).
 
+## Let your agents talk to you
+
+```bash
+voiceio say --from build-bot "tests are green"     # chime, notification, then it's read aloud
+voiceio say --from deploy --urgent "I need your approval"
+```
+
+Running several coding agents? Have each one call `voiceio say` when it needs you, so you hear *which* one. It never talks over you: while you dictate, announcements wait (speech into an open mic would get typed). They are read in your [tts] voice, offline.
+
 ## Configure
 
 Everything lives in `~/.config/voiceio/config.toml`; [config.example.toml](config.example.toml) documents every option. `voiceio config set section.key value` edits it in place.

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/python_voiceio.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ python_voiceio.egg-info/dependency_links.txt
 python_voiceio.egg-info/entry_points.txt
 python_voiceio.egg-info/requires.txt
 python_voiceio.egg-info/top_level.txt
+tests/test_announce.py
 tests/test_app_wiring.py
 tests/test_audio_quality.py
 tests/test_audio_source.py
@@ -73,6 +74,7 @@ tests/test_server.py
 tests/test_service.py
 tests/test_setup.py
 tests/test_sherpa.py
+tests/test_spool.py
 tests/test_streaming.py
 tests/test_suggest.py
 tests/test_tokens.py
@@ -85,6 +87,7 @@ tests/test_wordfreq.py
 tests/test_worker_decode.py
 voiceio/__init__.py
 voiceio/__main__.py
+voiceio/announce.py
 voiceio/app.py
 voiceio/audio_source.py
 voiceio/backends.py
@@ -119,6 +122,7 @@ voiceio/recorder.py
 voiceio/report.py
 voiceio/retention.py
 voiceio/service.py
+voiceio/spool.py
 voiceio/streaming.py
 voiceio/suggest.py
 voiceio/tokens.py

python_voiceio-1.14.0/tests/test_announce.py

@@ -0,0 +1,84 @@
+"""`voiceio say`: the message format, the queue, the socket and the CLI."""
+import threading
+import time
+from unittest.mock import patch
+
+from voiceio import announce
+from voiceio.announce import Message
+
+
+def test_encode_parse_round_trip():
+    msg = Message("tests are green", "build bot", urgent=True)
+    cmd = announce.encode(msg)
+    assert cmd.startswith("say:")
+    assert announce.parse(cmd[len("say:"):]) == msg
+    assert msg.spoken == "build bot: tests are green"
+    assert Message("hi").spoken == "hi"
+
+
+def test_parse_rejects_junk_and_caps_length():
+    assert announce.parse("not json") is None
+    assert announce.parse('["a list"]') is None
+    assert announce.parse('{"text": "   "}') is None
+    long = announce.parse('{"text": "%s", "from": "x\\n y"}' % ("a" * 5000))
+    assert len(long.text) == announce.MAX_TEXT and long.sender == "x y"
+
+
+def test_announcer_holds_while_busy_then_speaks_in_order():
+    spoken, busy = [], threading.Event()
+    busy.set()
+    done = threading.Event()
+
+    def speak(text):
+        spoken.append(text)
+        if len(spoken) == 2:
+            done.set()
+
+    with patch.object(announce, "cue_and_notify"):
+        a = announce.Announcer(speak=speak, busy=busy.is_set)
+        a.submit(Message("one", "a"))
+        a.submit(Message("two", "b"))
+        time.sleep(0.4)
+        assert spoken == []          # held while the user dictates
+        busy.clear()
+        assert done.wait(3)
+    assert spoken == ["a: one", "b: two"]
+
+
+def test_announcer_drops_when_full():
+    hold, spoken = threading.Event(), []
+    with patch.object(announce, "cue_and_notify"):
+        a = announce.Announcer(speak=lambda t: (hold.wait(5), spoken.append(t)), busy=lambda: False)
+        results = [a.submit(Message(str(i))) for i in range(announce._QUEUE + 3)]
+        hold.set()
+        deadline = time.monotonic() + 3   # drain inside the patch: no real notifications
+        while a._queue.unfinished_tasks and len(spoken) < sum(results) and time.monotonic() < deadline:
+            time.sleep(0.05)
+    assert not all(results)
+
+
+def test_socket_routes_payload_commands(tmp_path, monkeypatch):
+    from voiceio.hotkeys import socket_backend as sb
+    monkeypatch.setattr(sb, "SOCKET_PATH", tmp_path / "v.sock")
+    got = threading.Event()
+    payloads = []
+    hk = sb.SocketHotkey()
+    hk.handle_payload("say", lambda p: (payloads.append(p), got.set()))
+    hk.start("x", lambda: None)
+    try:
+        assert sb.send_command(announce.encode(Message("hello", "agent")))
+        assert got.wait(3)
+    finally:
+        hk.stop()
+    assert announce.parse(payloads[0]) == Message("hello", "agent")
+
+
+def test_cli_speaks_here_without_a_daemon(tmp_path, monkeypatch, capsys):
+    import sys
+    from voiceio import cli
+    from voiceio.hotkeys import socket_backend as sb
+    monkeypatch.setattr(sb, "SOCKET_PATH", tmp_path / "absent.sock")
+    monkeypatch.setattr(sys, "argv", ["voiceio", "say", "--from", "bot", "hi", "there"])
+    with patch.object(announce, "say_here", return_value=True) as here:
+        cli.main()
+    here.assert_called_once_with(Message("hi there", "bot", False))

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/tests/test_app_wiring.py

@@ -366,7 +366,7 @@ class TestStartCue:
 
         vio.recorder.stream_health = health
         real_start = vio.recorder.start
-        vio.recorder.start = lambda: (events.append("record"), real_start())
+        vio.recorder.start = lambda **kw: (events.append("record"), real_start(**kw))
         vio._quiet = MagicMock()
         return events
 

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/tests/test_report.py

@@ -121,7 +121,23 @@ class _Resp(io.BytesIO):
         return False
 
 
-def test_post_success_reads_receipt(monkeypatch):
+@pytest.fixture
+def outside_pytest(monkeypatch):
+    """post() refuses under pytest; these tests check what it does past that.
+    (pytest sets PYTEST_CURRENT_TEST again after fixtures, so patch the check.)"""
+    monkeypatch.setattr(report, "_test_artifact", lambda text: "")
+
+
+def test_post_refuses_test_runs_and_mock_text(monkeypatch):
+    monkeypatch.setattr(report, "_urlopen", lambda url, timeout: pytest.fail("posted"))
+    ok, why = report.post("voiceio 1.13.0 report")
+    assert not ok and "pytest" in why
+    monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
+    ok, why = report.post("system: Ubuntu · <MagicMock name='mock.platform.desktop'>")
+    assert not ok and "mock" in why
+
+
+def test_post_success_reads_receipt(monkeypatch, outside_pytest):
     seen = []
 
     def fake(url, timeout):
@@ -138,13 +154,13 @@ def test_post_success_reads_receipt(monkeypatch):
 
 @pytest.mark.parametrize("body", [b'{"ok": false, "error": "rate limited"}', b"[]", b"not json",
                                   b'{"ok": true}'])
-def test_post_bad_response_is_failure(monkeypatch, body):
+def test_post_bad_response_is_failure(monkeypatch, outside_pytest, body):
     monkeypatch.setattr(report, "_urlopen", lambda url, timeout: _Resp(body))
     ok, why = report.post("x")
     assert not ok and why
 
 
-def test_post_network_error_never_raises():
+def test_post_network_error_never_raises(outside_pytest):
     # conftest refuses every connection: this is the offline path.
     ok, why = report.post("x")
     assert not ok and "ConnectionRefused" in why

python_voiceio-1.14.0/tests/test_spool.py

@@ -0,0 +1,87 @@
+"""The crash spool: a dictation's audio survives a killed daemon."""
+import os
+
+import numpy as np
+
+from voiceio import spool
+
+
+def _wait(s):
+    s.flush()
+
+
+def test_recording_is_spooled_then_removed(tmp_path):
+    s = spool.Spool(tmp_path)
+    s.begin(7, 16000, prebuffer=np.ones(160, np.float32))
+    s.write(7, np.full((320, 1), 0.5, np.float32))
+    _wait(s)
+    path = s.path(7, 16000)
+    audio = np.fromfile(path, dtype=np.float32)
+    assert len(audio) == 480 and audio[-1] == 0.5
+    assert oct(path.stat().st_mode & 0o777) == "0o600"
+    s.finish(7)
+    _wait(s)
+    assert not path.exists()
+
+
+def test_writes_for_unknown_or_finished_recordings_are_ignored(tmp_path):
+    s = spool.Spool(tmp_path)
+    s.write(1, np.ones(10, np.float32))
+    s.finish(1)
+    _wait(s)
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_orphans_are_files_of_dead_processes(tmp_path, monkeypatch):
+    long = np.zeros(32000, np.float32)
+    (tmp_path / "recording-999999-3-16000.f32").write_bytes(long.tobytes())      # dead
+    (tmp_path / f"recording-{os.getpid()}-4-16000.f32").write_bytes(long.tobytes())  # us
+    (tmp_path / "recording-999998-1-16000.f32").write_bytes(np.zeros(100, np.float32).tobytes())
+    (tmp_path / "notes.txt").write_text("x")
+    monkeypatch.setattr(spool, "_alive", lambda pid: pid != 999999 and pid != 999998)
+    found = spool.orphans(tmp_path)
+    assert [(p.name, len(a), r) for p, a, r in found] == [("recording-999999-3-16000.f32", 32000, 16000)]
+    assert not (tmp_path / "recording-999998-1-16000.f32").exists()   # too short: dropped
+    assert (tmp_path / f"recording-{os.getpid()}-4-16000.f32").exists()
+
+
+def test_missing_dir_has_no_orphans(tmp_path):
+    assert spool.orphans(tmp_path / "nope") == []
+
+
+def test_recorder_taps_every_chunk_of_a_recording():
+    from unittest.mock import MagicMock
+    from voiceio.config import AudioConfig
+    from voiceio.recorder import AudioRecorder
+    rec = AudioRecorder(AudioConfig())
+    rec._stream = MagicMock()
+    rec._ring.append(np.ones((80, 1), np.float32))
+    got = []
+    rec.start(tap=got.append)
+    rec._callback(np.full((160, 1), 0.2, np.float32), 160, None, None)
+    rec.stop()
+    rec._callback(np.full((160, 1), 0.3, np.float32), 160, None, None)   # after stop: not tapped
+    assert [len(c) for c in got] == [80, 160]
+
+
+def test_daemon_recovers_an_orphan_into_history(tmp_path, monkeypatch):
+    from types import SimpleNamespace
+    from unittest.mock import MagicMock
+    from voiceio import app, feedback, history
+    orphan = tmp_path / "recording-999999-1-16000.f32"
+    orphan.write_bytes(np.zeros(32000, np.float32).tobytes())
+    monkeypatch.setattr(spool, "spool_dir", lambda: tmp_path)
+    monkeypatch.setattr(spool, "_alive", lambda pid: False)
+    saved, told = [], []
+    monkeypatch.setattr(history, "append", lambda text, **kw: saved.append((text, kw)))
+    monkeypatch.setattr(feedback, "notify", lambda title, body, urgent=False: told.append(body))
+    vio = app.VoiceIO.__new__(app.VoiceIO)
+    vio.recorder = SimpleNamespace(sample_rate=16000)
+    vio.engine = MagicMock()
+    vio.engine.transcribe.return_value = SimpleNamespace(text="the words that were cut off", raw="r")
+    vio.cfg = SimpleNamespace(history=None)
+    vio._recover_orphans()
+    assert saved[0][0] == "the words that were cut off"
+    assert saved[0][1]["extra"] == {"recovered": True}
+    assert "paste-last" in told[0]
+    assert not orphan.exists()

python_voiceio-1.14.0/voiceio/__init__.py

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

python_voiceio-1.14.0/voiceio/announce.py

@@ -0,0 +1,106 @@
+"""`voiceio say`: let an agent or a script speak to you, and say who it is.
+
+A chime, a desktop notification titled with the sender, then the sender's
+name and the text read aloud. The daemon queues announcements and holds them
+while you dictate: speech played into an open mic would be typed back out,
+and talking over you is rude anyway. Without a daemon, `voiceio say` speaks
+in its own process instead (slower: it loads the voice first).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import queue
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+MAX_TEXT = 600          # characters read aloud; an announcement, not an essay
+_QUEUE = 8              # waiting announcements beyond this are dropped
+_HOLD_SECS = 600        # wait at most this long for a dictation to finish
+
+
+@dataclass(frozen=True)
+class Message:
+    text: str
+    sender: str = ""
+    urgent: bool = False
+
+    @property
+    def spoken(self) -> str:
+        return f"{self.sender}: {self.text}" if self.sender else self.text
+
+
+def encode(msg: Message) -> str:
+    """The control-socket command for `msg`."""
+    return "say:" + json.dumps({"text": msg.text, "from": msg.sender, "urgent": msg.urgent})
+
+
+def parse(payload: str) -> Message | None:
+    try:
+        d = json.loads(payload)
+        text = " ".join(str(d.get("text", "")).split())[:MAX_TEXT]
+        sender = " ".join(str(d.get("from", "")).split())[:60]
+    except (ValueError, AttributeError):
+        return None
+    return Message(text, sender, bool(d.get("urgent"))) if text else None
+
+
+def cue_and_notify(msg: Message) -> None:
+    """The chime and the notification: who is talking, even with no voice."""
+    from voiceio import feedback
+    if feedback.open_cue_stream():
+        (feedback.play_alert_sound if msg.urgent else feedback.play_commit_sound)()
+        time.sleep(0.4)   # let the chime land before the voice starts
+    feedback.notify(msg.sender or "voiceio", msg.text, urgent=msg.urgent)
+
+
+class Announcer:
+    """One announcement at a time, in order, on its own thread."""
+
+    def __init__(self, speak: Callable[[str], None], busy: Callable[[], bool],
+                 hold_secs: float = _HOLD_SECS) -> None:
+        self._speak = speak
+        self._busy = busy
+        self._hold_secs = hold_secs
+        self._queue: queue.Queue[Message] = queue.Queue(maxsize=_QUEUE)
+        threading.Thread(target=self._run, name="announcer", daemon=True).start()
+
+    def submit(self, msg: Message) -> bool:
+        try:
+            self._queue.put_nowait(msg)
+            return True
+        except queue.Full:
+            log.warning("say: %d announcements waiting, dropped one from %s",
+                        _QUEUE, msg.sender or "?")
+            return False
+
+    def _run(self) -> None:
+        while True:
+            msg = self._queue.get()
+            deadline = time.monotonic() + self._hold_secs
+            while self._busy() and time.monotonic() < deadline:
+                time.sleep(0.25)
+            try:
+                cue_and_notify(msg)
+                self._speak(msg.spoken)
+            except Exception:
+                log.exception("say: announcement from %s failed", msg.sender or "?")
+
+
+def say_here(msg: Message) -> bool:
+    """No daemon: chime, notify and speak in this process. False if no TTS
+    engine works here (the chime and notification still happened)."""
+    from voiceio import config, tts
+    from voiceio.tts.player import TTSPlayer
+    cue_and_notify(msg)
+    cfg = config.load().tts
+    engine = tts.select(cfg, allow_network=False)
+    if engine is None:
+        return False
+    audio, rate = engine.synthesize(msg.spoken, cfg.voice, cfg.speed)
+    TTSPlayer().play(audio, rate)
+    return True

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/voiceio/app.py

@@ -189,6 +189,9 @@ class VoiceIO:
         # TTS (text-to-speech)
         self._tts_engine = None
         self._tts_player = None
+        self._announcer = None
+        from voiceio.spool import Spool
+        self._spool = Spool()
         self._tts_hotkey = None
         if cfg.tts.enabled:
             from voiceio.tts import select as tts_select
@@ -368,7 +371,7 @@ class VoiceIO:
         if session is not None:
             session.cancel()
         self._state = _State.IDLE
-        self._typers.end(rid)
+        self._end_recording(rid)
         self._idle_audio.touch()
         log.info("Recording cancelled")
 
@@ -595,9 +598,10 @@ class VoiceIO:
             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)
         rid = self._recording
+        self._spool.begin(rid, self.recorder.sample_rate)
+        self.recorder.start(tap=lambda chunk, r=rid: self._spool.write(r, chunk))
+        self.recorder.set_on_auto_stop(self._on_auto_stop)
         self.recorder.set_on_dead_stream(lambda: self._revive_mic(rid))
         # Ducking lowers the whole output, voiceio's chimes included: it waits
         # for the start chime to play out, and _do_stop restores the volume
@@ -655,13 +659,13 @@ class VoiceIO:
                 self._output_thread(self._process, audio, gen, rid, self._recording_bias)
             else:
                 # No processing thread will run — release the source here.
-                self._typers.end(rid)
+                self._end_recording(rid)
         else:
             # Streaming mode but session already gone (race) — nothing to do
             self._state = _State.IDLE
             log.debug("Stop: streaming session already finalized")
             # No finalizer will run to release the input source, so do it here.
-            self._typers.end(rid)
+            self._end_recording(rid)
 
     def _capture_context(self, rid: int) -> None:
         from voiceio import retention
@@ -766,7 +770,7 @@ class VoiceIO:
                 self._finalizing = None
         if self._discard_cancelled(gen, extra):
             log.info("Cancelled dictation discarded")
-            self._typers.end(rid)
+            self._end_recording(rid)
             return
         if self._generation != gen:
             # A later recording has already stopped: this output is stale, but
@@ -776,7 +780,7 @@ class VoiceIO:
             if final_text:
                 self.engine.commit(final_text, raw=session.raw_final_text,
                                    duration=elapsed, extra=extra)
-            self._typers.end(rid)
+            self._end_recording(rid)
             return
         if final_text:
             self._copy_result_async(final_text)
@@ -801,7 +805,7 @@ class VoiceIO:
         self._warn_if_nothing_captured(final_text, gen)
         # Release the IBus input source now that the final commit is done.
         # A no-op if a newer recording has claimed it since.
-        self._typers.end(rid)
+        self._end_recording(rid)
         # Transition to IDLE under lock to avoid racing with _toggle
         with self._hotkey_lock:
             if self._generation == gen and self._state == _State.FINALIZING:
@@ -834,7 +838,7 @@ class VoiceIO:
             log.exception("Processing failed")
         finally:
             # Release the IBus input source after the batch commit (or failure).
-            self._typers.end(rid)
+            self._end_recording(rid)
 
     # ── Text-to-speech ─────────────────────────────────────────────
 
@@ -869,6 +873,62 @@ class VoiceIO:
         finally:
             tray.set_processing(False)
 
+    def _end_recording(self, rid: int) -> None:
+        """A dictation is over: delivered, saved to history, or cancelled.
+        Exactly one call per recording."""
+        self._typers.end(rid)
+        self._spool.finish(rid)
+
+    def _recover_orphans(self) -> None:
+        """Decode recordings a killed daemon left in the spool into history."""
+        from voiceio import feedback, history, spool
+        for path, audio, rate in spool.orphans():
+            secs = len(audio) / rate
+            if rate != self.recorder.sample_rate:
+                log.warning("spool: %s is at %d Hz, not %d; left as is", path.name, rate,
+                            self.recorder.sample_rate)
+                continue
+            try:
+                result = self.engine.transcribe(audio, bias=self.engine.bias())
+            except Exception:
+                log.exception("spool: could not decode %s (%.0fs); left for the next start",
+                              path.name, secs)
+                continue
+            text = (result.text or "").strip()
+            if text:
+                history.append(text, raw=result.raw, duration=secs,
+                               extra={"recovered": True}, cfg=self.cfg.history)
+                feedback.notify("VoiceIO recovered a dictation",
+                                f"{secs:.0f}s cut off when voiceio stopped: \"{text[:120]}\" "
+                                "— `voiceio paste-last` types it", urgent=True)
+                log.info("spool: recovered %.0fs into history", secs)
+            path.unlink(missing_ok=True)
+
+    # ── Announcements (`voiceio say`) ───────────────────────────────────
+
+    def on_say(self, payload: str) -> None:
+        """An agent or script asks to be heard: queue it, never talk over it."""
+        from voiceio import announce
+        msg = announce.parse(payload)
+        if msg is None:
+            log.warning("say: ignored a malformed request")
+            return
+        if self._announcer is None:
+            self._announcer = announce.Announcer(
+                speak=self._speak_now, busy=lambda: self._state in (
+                    _State.RECORDING, _State.FINALIZING))
+        self._announcer.submit(msg)
+
+    def _speak_now(self, text: str) -> None:
+        """Speak to the end (on the announcer's own thread); nothing if no TTS."""
+        if self._tts_player is None or self._tts_engine is None:
+            return
+        while self._tts_player.is_playing():   # the user's own read-aloud goes first
+            time.sleep(0.2)
+        audio, sample_rate = self._tts_engine.synthesize(
+            text, self.cfg.tts.voice, self.cfg.tts.speed)
+        self._tts_player.play(audio, sample_rate)   # synchronous
+
     # ── Feedback ────────────────────────────────────────────────────────
 
     def _play_record_cue(self, start: bool) -> None:
@@ -941,6 +1001,8 @@ class VoiceIO:
         control.handle("release", self.on_hotkey_release)
         control.handle("cancel", self.cancel)
         control.handle("paste-last", self.paste_last)
+        if hasattr(control, "handle_payload"):
+            control.handle_payload("say", self.on_say)
         if self._cancel_hotkey is not None:
             self._cancel_hotkey.start(self.cfg.hotkey.cancel_key, self.cancel)
 
@@ -989,6 +1051,8 @@ class VoiceIO:
             f"voiceio v{__version__} ready. Press [{self.cfg.hotkey.key}] to record "
             f"(model={self.cfg.model.name}, typer={self._typers.typer.name})",
         )
+        threading.Thread(target=self._recover_orphans, daemon=True,
+                         name="spool-recover").start()
 
         # Ctrl-C and `systemctl stop voiceio` must run the SAME cleanup path
         # (restore input source, engine shutdown) — the finally block below.

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/voiceio/cli/__init__.py

@@ -45,6 +45,17 @@ def main() -> None:
     sub.add_parser("cancel", help="Abandon the current dictation: nothing is typed or kept"
                    ).set_defaults(func=lambda a: _send("cancel"))
 
+    p_say = sub.add_parser(
+        "say", help="Speak to the user: chime, notification, then the text read aloud",
+        description="For agents and scripts: `voiceio say --from build-bot 'tests are green'`. "
+                    "The daemon waits until you stop dictating; without one, it speaks here.")
+    p_say.add_argument("text", nargs="+", help="what to say")
+    p_say.add_argument("--from", dest="sender", default="",
+                       help="who is talking, said first and shown as the notification title")
+    p_say.add_argument("--urgent", action="store_true",
+                       help="the alert chime and an urgent notification")
+    p_say.set_defaults(func=_cmd_say)
+
     p_setup = sub.add_parser("setup", help="Configure voiceio (interactive wizard)")
     p_setup.add_argument("--defaults", action="store_true",
                          help="Non-interactive: accept all recommended defaults")
@@ -164,6 +175,20 @@ def _cmd_setup(args: argparse.Namespace) -> None:
     hint("test", "Run 'voiceio doctor --live' to try a quick recording")
 
 
+def _cmd_say(args: argparse.Namespace) -> None:
+    from voiceio import announce
+    from voiceio.hotkeys.socket_backend import SOCKET_PATH, send_command
+    msg = announce.Message(" ".join(" ".join(args.text).split())[:announce.MAX_TEXT],
+                           " ".join(args.sender.split()), args.urgent)
+    if not msg.text:
+        raise SystemExit("nothing to say")
+    if SOCKET_PATH.exists() and send_command(announce.encode(msg)):
+        return
+    if not announce.say_here(msg):
+        print("no text-to-speech engine works here: sent the notification only "
+              "(voiceio doctor shows why)", file=sys.stderr)
+
+
 def _send(command: str) -> None:
     """Send a command to the running daemon."""
     from voiceio.hotkeys.socket_backend import send_command

{python_voiceio-1.13.0 → python_voiceio-1.14.0}/voiceio/feedback.py

@@ -141,6 +141,10 @@ def play_commit_sound() -> None:
     _play("commit")
 
 
+def play_alert_sound() -> None:
+    _play("alert")
+
+
 # The usual cause, by far: a hardware mic switch, a mute key or a muted
 # source. Each look the same to voiceio — a stream that sends only zeros.
 MIC_HINT = "Is the mic switched off or muted (privacy switch, mute key)?"