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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.13.0
+Version: 1.15.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.15.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.15.0}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.13.0
+Version: 1.15.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.15.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.15.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.15.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.15.0}/tests/test_learn_pipeline.py

@@ -307,6 +307,32 @@ def test_status_shows_scores_and_suggests_a_winning_run(capsys):
     assert "next: voiceio learn promote v0001-small-x" in out
 
 
+def test_status_never_suggests_whisper_over_another_decoder(capsys):
+    import argparse
+
+    from voiceio import config
+    from voiceio.cli import learn as cli
+    config.CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    config.CONFIG_PATH.write_text('[model]\nname = "parakeet-tdt-0.6b-v2"\n')
+    _clip("s.wav", 3, "x")
+    store.add_label("s.wav", [Segment(0, 3, "hi")], "teacher:fake")
+    ds = store.build_dataset()
+    run = store.learn_dir() / "models" / "v0001-small-x"
+    (run / "ct2").mkdir(parents=True)
+    runs = store.learn_dir() / "runs"
+    runs.mkdir()
+    for i, (dec, wer, rec) in enumerate([("sherpa:parakeet-tdt-0.6b-v2", 0.10, 0.5),
+                                         (f"faster-whisper:{run / 'ct2'}", 0.08, 0.8)]):
+        (runs / f"eval-2026010{i}.json").write_text(json.dumps({
+            "decoder": dec, "dataset": ds.name, "mode": "offline", "wer": wer,
+            "term_recall": rec, "repetitions": 0, "clips": 5, "gold": 0,
+            "metrics": metrics.METRICS_VERSION}))
+    cli.cmd_status(argparse.Namespace())
+    out = capsys.readouterr().out
+    assert "parakeet-tdt-0.6b-v2 (active)" in out and "WER 10.0%" in out
+    assert "next: voiceio learn promote" not in out
+
+
 def test_paired_comparison_reports_direction_and_uncertainty():
     clips = [f"{i}.wav" for i in range(20)]
     cur = {"per_clip": [{"file": f, "wer": 0.10} for f in clips]}

{python_voiceio-1.13.0 → python_voiceio-1.15.0}/tests/test_presence.py

@@ -38,6 +38,7 @@ AWAY = 600
     (Probe(idle=1800), False, "away 30 min"),
     (Probe(idle=1800, inhibited=True), True, "keeping the session awake"),   # a video
     (Probe(idle=1800, inhibited=True, locked=True), False, "away"),
+    (Probe(idle=3 * 3600, inhibited=True), False, "away 180 min"),   # an agent, not a viewer
     # No idle monitor: logind decides, and "can't tell" means in use.
     (Probe(), True, "can't tell"),
     (Probe(session=SeatSession(exists=False)), False, "nobody is logged in"),

{python_voiceio-1.13.0 → python_voiceio-1.15.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.13.0 → python_voiceio-1.15.0}/tests/test_server.py

@@ -310,6 +310,7 @@ def test_ws_ready_partial_final_sequence():
     assert final["text"] == "Hello world."
     assert final["raw"] == "hello world raw"
     assert isinstance(final["ms"], int)
+    assert final["cut_short"] is False and "why" not in final
     assert engine.committed == ["Hello world."]  # learned from; kept if opted in
 
 
@@ -348,8 +349,9 @@ def test_ws_client_disconnect_still_finalizes():
     assert engine.sessions[0].stopped_with is not None
 
 
-def test_ws_enforces_the_duration_cap():
+def test_ws_duration_cap_finalizes_what_fits_marked_cut_short():
     cfg = ServerConfig(max_audio_secs=0.05)  # 800 samples
+    engine = FakeEngine()
 
     async def go(client):
         ws = await client.ws_connect("/ws/transcribe")
@@ -361,11 +363,36 @@ def test_ws_enforces_the_duration_cap():
         await ws.close()
         return frames
 
-    frames = run_with_client(go, cfg=cfg)
-    kinds = [f["type"] for f in frames]
-    assert "error" in kinds
-    # An overrun must not also claim a usable final transcript.
-    assert "final" not in kinds
+    frames = run_with_client(go, cfg=cfg, engine=engine)
+    final = frames[-1]
+    assert final["type"] == "final" and final["text"] == "Hello world."
+    # The words are kept, and the client is told they are not the whole note.
+    assert final["cut_short"] is True and "limit" in final["why"]
+    assert len(engine.sessions[0].stopped_with) == 800   # only what fits is decoded
+
+
+def test_ws_stalled_stream_is_finalized_with_what_it_has():
+    """A client that goes quiet without a stop (a starved or frozen sender)
+    still gets a transcript of the audio it sent."""
+    cfg = ServerConfig(stall_secs=0.2)
+    engine = FakeEngine()
+
+    async def go(client):
+        ws = await client.ws_connect("/ws/transcribe")
+        await ws.receive_json()
+        await ws.send_bytes(_pcm(800))
+        frames = []
+        async for msg in ws:          # no stop: the server ends it
+            frames.append(json.loads(msg.data))
+        await ws.close()
+        return frames
+
+    frames = run_with_client(go, cfg=cfg, engine=engine)
+    final = frames[-1]
+    assert final["type"] == "final" and final["text"] == "Hello world."
+    assert final["cut_short"] is True and "no audio or stop" in final["why"]
+    assert len(engine.sessions[0].stopped_with) == 800
+    assert engine.committed == ["Hello world."]
 
 
 def test_ws_second_concurrent_session_is_refused():
@@ -439,11 +466,12 @@ def test_config_from_env(monkeypatch):
     monkeypatch.setenv("VOICE_MODEL", "base")
     monkeypatch.setenv("VOICE_THREADS", "2")
     monkeypatch.setenv("VOICE_MAX_SECS", "60")
+    monkeypatch.setenv("VOICE_STALL_SECS", "45")
     monkeypatch.setenv("VOICE_TTS_ALLOW_NETWORK", "1")
     cfg = ServerConfig.from_env()
     assert (cfg.host, cfg.port, cfg.model) == ("0.0.0.0", 8790, "base")
     assert cfg.threads == "2"
-    assert cfg.max_audio_secs == 60.0
+    assert (cfg.max_audio_secs, cfg.stall_secs) == (60.0, 45.0)
     assert cfg.tts_allow_network is True
 
 

{python_voiceio-1.13.0 → python_voiceio-1.15.0}/tests/test_sherpa.py

@@ -41,6 +41,10 @@ class FakeSherpa:
                 self.rec = {"hotwords": hotwords, "samples": 0}
                 fake.streams.append(self.rec)
 
+            def set_option(self, key, value):
+                assert isinstance(value, str)
+                self.rec[key] = value
+
             def accept_waveform(self, sr, a):
                 assert sr == 16000 and a.dtype == np.float32
                 self.rec["samples"] = len(a)
@@ -114,6 +118,7 @@ def test_one_recognizer_and_per_stream_pretokenized_proper_nouns(fake, tmp_path)
     assert out.text == "hello world"
     # Lowercase (mined jargon) and unusable terms never become hotwords.
     assert fake.streams[-1]["hotwords"] == "▁Kal shi/▁Hy per"
+    assert fake.streams[-1]["length_reward"] == "0.5"   # per stream, as upstream reads it
     dec.decode(_audio(2), bias=Bias(hotwords="Hyper"))
     dec.decode(_audio(2), bias=Bias())
     assert [s["hotwords"] for s in fake.streams[1:]] == ["▁Hy per", None]
@@ -135,7 +140,7 @@ def test_without_the_tdt_fix_decodes_greedy_and_unbiased(fake, monkeypatch, tmp_
     assert dec.decode(_audio(1), bias=Bias(hotwords="Kalshi")).text == "hello world"
     kw = fake.created[-1]
     assert kw["decoding_method"] == "greedy_search" and "length_reward" not in kw
-    assert fake.streams[-1]["hotwords"] is None
+    assert fake.streams[-1]["hotwords"] is None and "length_reward" not in fake.streams[-1]
 
 
 def test_long_audio_is_decoded_in_pieces_of_at_most_30s(fake, tmp_path):

python_voiceio-1.15.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.15.0/voiceio/__init__.py

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

python_voiceio-1.15.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