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

{python_voiceio-1.12.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.12.0
+Version: 1.14.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -65,7 +65,7 @@ Dynamic: license-file
 **[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
 
 - **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
-- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (about 2x faster, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (text lands ~0.7 s after you stop talking instead of ~4.4 s, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
 - **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
 
 ## Install
@@ -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.12.0 → python_voiceio-1.14.0}/README.md

@@ -12,7 +12,7 @@
 **[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
 
 - **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
-- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (about 2x faster, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (text lands ~0.7 s after you stop talking instead of ~4.4 s, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
 - **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
 
 ## Install
@@ -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.12.0 → python_voiceio-1.14.0}/pyproject.toml

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

{python_voiceio-1.12.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.12.0
+Version: 1.14.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -65,7 +65,7 @@ Dynamic: license-file
 **[Try it in your browser at voiceio.dev](https://voiceio.dev)**: no install, the model runs in the tab.
 
 - **Types anywhere.** Press your hotkey, speak, and the words stream into the focused app with a live underlined preview (IBus), on Wayland and X11: GNOME, KDE, Hyprland, sway, i3.
-- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (about 2x faster, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
+- **Runs on your machine.** Whisper, or NVIDIA's Parakeet (text lands ~0.7 s after you stop talking instead of ~4.4 s, with every name you use as a hotword), decodes your speech locally. No account, no server, no telemetry; logs never contain your words.
 - **Learns your words.** Keep your recordings (opt-in, on your disk) and voiceio fine-tunes its model on them while the machine is idle. It switches only when the new model wins on clips it never trained on. On the author's voice: 12.1% → 4.9% word errors after one night on a laptop CPU.
 
 ## Install
@@ -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.12.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
@@ -208,6 +212,7 @@ voiceio/tts/edge_engine.py
 voiceio/tts/espeak.py
 voiceio/tts/piper_engine.py
 voiceio/tts/player.py
+voiceio/tts/supertonic_engine.py
 voiceio/typers/__init__.py
 voiceio/typers/base.py
 voiceio/typers/chain.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.12.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.12.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.12.0 → python_voiceio-1.14.0}/tests/test_sherpa.py

@@ -195,7 +195,8 @@ def test_default_is_parakeet_only_when_sherpa_has_the_fix(monkeypatch):
     assert catalog.default_model("en") == "small"
     monkeypatch.setattr(sherpa, "features", lambda: SherpaFeatures(True, True, False))
     assert catalog.default_model("en") == catalog.PARAKEET
-    assert catalog.default_model("es") == "small"     # Parakeet v2 is English only
+    assert catalog.default_model("es") == catalog.PARAKEET_V3
+    assert catalog.default_model("ja") == "small"      # outside Parakeet v3's languages
 
 
 def test_config_resolves_unset_or_auto_name_but_an_explicit_choice_wins(monkeypatch, tmp_path):
@@ -343,6 +344,10 @@ def test_doctor_reports_the_decoder(monkeypatch):
     assert "aren't used" in _learning_status(cfg)["Voice model"]
     cfg.model.name = "small"
     assert catalog.PARAKEET in _decoder_status(cfg)["Decoder"]
+    cfg.model.language = "es"
+    assert catalog.PARAKEET_V3 in _decoder_status(cfg)["Decoder"]
+    cfg.model.language = "ja"
+    assert _decoder_status(cfg) == {}
 
 
 def test_eval_results_are_found_for_sherpa_models(monkeypatch, tmp_path):

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.12.0 → python_voiceio-1.14.0}/tests/test_tts.py

@@ -423,3 +423,79 @@ def test_piper_shutdown_releases_voice():
     engine._voice = MagicMock()
     engine.shutdown()
     assert engine._voice is None
+
+
+# ── supertonic tests ─────────────────────────────────────────────────
+
+class _FakeGenerated:
+    samples = [0.0, 0.5, -1.5]
+    sample_rate = 44100
+
+
+def _fake_sherpa(calls):
+    so = MagicMock()
+
+    class Tts:
+        def __init__(self, config):
+            calls["config"] = config
+
+        def generate(self, text, gen):
+            calls["text"], calls["gen"] = text, gen
+            return _FakeGenerated()
+
+    so.OfflineTts = Tts
+    so.GenerationConfig = lambda: type("G", (), {})()
+    return so
+
+
+def _supertonic_dir(path):
+    from voiceio.tts import supertonic_engine as st
+    for stem in st._STEMS:
+        (path / f"{stem}.int8.onnx").write_bytes(b"")
+    for f in st._FILES:
+        (path / f).write_bytes(b"")
+    return path
+
+
+def test_supertonic_probe_needs_supertonic_in_sherpa():
+    from voiceio.tts.supertonic_engine import SupertonicEngine
+    old = MagicMock(spec=[])   # a sherpa-onnx without OfflineTtsSupertonicModelConfig
+    with patch.dict("sys.modules", {"sherpa_onnx": old}):
+        assert not SupertonicEngine().probe().ok
+    with patch.dict("sys.modules", {"sherpa_onnx": MagicMock()}):
+        assert SupertonicEngine().probe().ok
+
+
+def test_supertonic_reads_in_its_language_and_returns_int16(tmp_path):
+    from voiceio.tts import supertonic_engine as st
+    calls = {}
+    model = _supertonic_dir(tmp_path)
+    with patch.dict("sys.modules", {"sherpa_onnx": _fake_sherpa(calls)}), \
+            patch("voiceio.core.decoders.fetch.download_archive", return_value=model) as dl:
+        engine = st.SupertonicEngine(language="es")
+        audio, rate = engine.synthesize("hola", voice="", speed=0)
+        engine.synthesize("otra vez", voice="2", speed=1.2)
+    dl.assert_called_once()                       # loaded once, then reused
+    assert dl.call_args.args[0] == st.MODEL
+    assert calls["gen"].extra == {"lang": "es"}
+    assert calls["gen"].sid == 2 and calls["gen"].speed == 1.2
+    assert rate == 44100 and audio.dtype == np.int16
+    assert audio.tolist()[2] == -32767            # clipped, not wrapped
+
+
+def test_supertonic_auto_language_reads_english():
+    from voiceio.tts.supertonic_engine import SupertonicEngine
+    assert SupertonicEngine(language="auto")._language == "en"
+    assert SupertonicEngine()._language == "en"
+
+
+def test_supertonic_completeness_check(tmp_path):
+    from voiceio.tts import supertonic_engine as st
+    assert not st._complete(tmp_path)
+    assert st._complete(_supertonic_dir(tmp_path))
+
+
+def test_chain_passes_language_to_supertonic():
+    from voiceio.tts import chain
+    engine = chain._create("supertonic", TTSConfig(engine="supertonic", language="de"))
+    assert engine.name == "supertonic" and engine._language == "de"

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