stackvox 0.5.0__tar.gz → 0.6.0__tar.gz

{stackvox-0.5.0/stackvox.egg-info → stackvox-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.5.0
+Version: 0.6.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0

{stackvox-0.5.0 → stackvox-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.5.0"
+version = "0.6.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -100,7 +100,11 @@ show_missing = true
 skip_covered = false
 
 [tool.mypy]
-python_version = "3.10"
+# Matches the interpreter CI runs mypy under, and must be >= 3.12: numpy's
+# bundled stubs use PEP 695 `type` aliases, which mypy rejects as a syntax
+# error when told to target an older Python. Runtime support for 3.10+ is
+# still verified by the pytest matrix (py3.10–3.13).
+python_version = "3.12"
 files = ["stackvox", "tests"]
 warn_unused_ignores = true
 warn_redundant_casts = true

{stackvox-0.5.0 → stackvox-0.6.0}/stackvox/__init__.py

@@ -5,6 +5,7 @@ from importlib.metadata import version as _pkg_version
 
 from stackvox import daemon
 from stackvox.engine import Stackvox, speak, synthesize
+from stackvox.text import normalize_for_speech
 
 try:
     __version__ = _pkg_version("stackvox")
@@ -13,4 +14,4 @@ except PackageNotFoundError:
     # bootstrap before `pip install -e .` has completed).
     __version__ = "0.0.0+unknown"
 
-__all__ = ["Stackvox", "daemon", "speak", "synthesize"]
+__all__ = ["Stackvox", "daemon", "normalize_for_speech", "speak", "synthesize"]

{stackvox-0.5.0 → stackvox-0.6.0}/stackvox/engine.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import logging
+import queue
+import re
 import sys
 import threading
 import urllib.request
@@ -69,6 +71,17 @@ def _ensure_models(cache_dir: Path) -> tuple[Path, Path]:
     return model_path, voices_path
 
 
+# Split after ., !, or ? that is followed by whitespace, and on newlines. The
+# whitespace requirement leaves decimals ("0.95") and mid-token dots
+# ("file.ts") intact, which is good enough for speech chunking.
+_SENTENCE_BOUNDARY = re.compile(r"(?<=[.!?])\s+|\n+")
+
+
+def _split_sentences(text: str) -> list[str]:
+    """Break text into sentence-ish chunks for low-latency streaming playback."""
+    return [part.strip() for part in _SENTENCE_BOUNDARY.split(text.strip()) if part.strip()]
+
+
 class Stackvox:
     """Reusable TTS engine. Load the model once, speak many times.
 
@@ -89,6 +102,8 @@ class Stackvox:
         self.lang = lang
         model_path, voices_path = _ensure_models(cache_dir or _default_cache_dir())
         self._kokoro = Kokoro(str(model_path), str(voices_path))
+        self._stop_event = threading.Event()
+        self._play_thread: threading.Thread | None = None
 
     def synthesize(
         self,
@@ -106,6 +121,21 @@ class Stackvox:
         )
         return samples, sample_rate
 
+    def _cancel_active(self) -> None:
+        """Supersede any in-progress stream so a new ``speak`` starts clean.
+
+        Signals the running stream's stop event and joins its thread, so we
+        never overlap two streams on the shared output device or orphan the
+        previous playback thread.
+        """
+        thread = self._play_thread
+        self._play_thread = None
+        if thread is None or thread is threading.current_thread() or not thread.is_alive():
+            return
+        self._stop_event.set()
+        sd.stop()
+        thread.join()
+
     def speak(
         self,
         text: str,
@@ -114,14 +144,98 @@ class Stackvox:
         lang: str | None = None,
         blocking: bool = True,
     ) -> None:
-        """Synthesize and play through the system default output device."""
-        samples, sample_rate = self.synthesize(text, voice=voice, speed=speed, lang=lang)
-        sd.play(samples, sample_rate)
+        """Synthesize and play through the system default output device.
+
+        Streams sentence by sentence: the first sentence starts playing as soon
+        as it is synthesized (~0.2s) while the rest synthesize in the background,
+        rather than waiting for the whole text to synthesize first.
+        """
+        self._cancel_active()
+        # Each stream gets its own cancellation token, so a later speak() (or a
+        # stop() in between) can never clear an older stream's cancellation.
+        stop_event = threading.Event()
+        self._stop_event = stop_event
         if blocking:
-            sd.wait()
+            self._stream_play(text, stop_event, voice=voice, speed=speed, lang=lang)
+            return
+
+        def _run() -> None:
+            try:
+                self._stream_play(text, stop_event, voice=voice, speed=speed, lang=lang)
+            except Exception:
+                logger.exception("stackvox playback failed")
+
+        self._play_thread = threading.Thread(target=_run, daemon=True, name="stackvox-play")
+        self._play_thread.start()
+
+    def _stream_play(
+        self,
+        text: str,
+        stop_event: threading.Event,
+        voice: str | None = None,
+        speed: float | None = None,
+        lang: str | None = None,
+    ) -> None:
+        """Synthesize sentence by sentence and play each as it is ready.
+
+        Kokoro batches by phoneme count (~510), so a whole paragraph synthesizes
+        as one blob before any audio — the source of the lead-in lag. Splitting
+        into sentences ourselves means the first sentence (~0.2s to synthesize)
+        plays almost immediately. A producer thread synthesizes ahead into a
+        bounded queue while this thread plays, so later sentences are usually
+        ready by the time the previous one finishes.
+
+        A synthesis failure is re-raised rather than swallowed, so a blocking
+        caller sees the error instead of silent success; ``stop_event`` cancels
+        the stream between sentences.
+        """
+        sentences = _split_sentences(text)
+        if not sentences:
+            return
+
+        chunks: queue.Queue = queue.Queue(maxsize=8)
+        sentinel = object()
+
+        def _produce() -> None:
+            try:
+                for sentence in sentences:
+                    if stop_event.is_set():
+                        break
+                    chunks.put(self.synthesize(sentence, voice=voice, speed=speed, lang=lang))
+            except Exception as exc:  # hand the failure to the consumer to re-raise
+                chunks.put(exc)
+            finally:
+                chunks.put(sentinel)
+
+        producer = threading.Thread(target=_produce, daemon=True, name="stackvox-synth")
+        producer.start()
+        error: Exception | None = None
+        try:
+            while not stop_event.is_set():
+                item = chunks.get()
+                if item is sentinel:
+                    break
+                if isinstance(item, Exception):
+                    error = item
+                    break
+                samples, sample_rate = item
+                sd.play(samples, sample_rate)
+                sd.wait()
+        finally:
+            # Stop the producer and keep draining so it can never stay parked on
+            # a full queue — that's what guarantees the synth thread always exits.
+            stop_event.set()
+            while producer.is_alive():
+                try:
+                    chunks.get_nowait()
+                except queue.Empty:
+                    producer.join(timeout=0.05)
+        if error is not None:
+            raise error
 
     def stop(self) -> None:
         """Stop any in-progress playback started with blocking=False."""
+        self._stop_event.set()
         sd.stop()
 
     def voices(self) -> list[str]:

stackvox-0.6.0/stackvox/text.py

@@ -0,0 +1,310 @@
+"""Turn real-world text — Markdown, Claude responses, prose — into something
+that *sounds* right when synthesized.
+
+StackVox speaks whatever string it's given; this module is the pre-step that
+makes that string speakable: strip Markdown structure, expand units and
+numbers, shape pauses, and apply a caller-supplied pronunciation dictionary.
+
+The primary entry point is :func:`normalize_for_speech`. Each stage is also
+exposed for composition and testing. See ``docs/speech-normalization.md``.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "normalize_for_speech",
+    "markdown_to_paragraphs",
+    "strip_emoji",
+    "strip_thousands_separators",
+    "decimals_to_words",
+    "expand_units",
+    "apply_pronunciations",
+    "shape_pauses",
+    "ensure_terminal_stop",
+]
+
+# --------------------------------------------------------------------------- #
+# Emoji                                                                       #
+# --------------------------------------------------------------------------- #
+
+_EMOJI = re.compile(
+    "["
+    "\U0001f000-\U0001faff"  # symbols, emoticons, pictographs, supplemental
+    "\U00002600-\U000027bf"  # misc symbols + dingbats
+    "\U00002190-\U000021ff"  # arrows
+    "\U00002b00-\U00002bff"  # misc symbols and arrows
+    "\U0000fe00-\U0000fe0f"  # variation selectors
+    "]+",
+    flags=re.UNICODE,
+)
+
+
+def strip_emoji(text: str) -> str:
+    return _EMOJI.sub("", text)
+
+
+# --------------------------------------------------------------------------- #
+# Units & symbols (locale-keyed)                                              #
+# --------------------------------------------------------------------------- #
+# (pattern, replacement). Digit-glued units capture the leading digit and
+# re-emit it, so "65kg" -> "65 kilograms". IMPORTANT: currency/unit expansion
+# must run BEFORE the decimal-point split, or "£1.63" becomes "£1 point 63".
+
+_UNIT_RULES: dict[str, list[tuple[str, str]]] = {
+    "en-GB": [
+        (r"£\s?(\d[\d,]*(?:\.\d+)?)", r"\1 pounds"),  # £1.63 -> 1.63 pounds
+        (r"\bkWh\b", "kilowatt hours"),
+        (r"\bMPG\b", "miles per gallon"),
+        (r"(\d)\s?kg\b", r"\1 kilograms"),
+        (r"(\d)\s?km\b", r"\1 kilometres"),
+        (r"(\d)p\b", r"\1 pence"),  # 25p, 167.14p
+        (r"\s*÷\s*", " divided by "),
+        (r"\s*×\s*", " times "),
+        (r"\s*=\s*", " equals "),
+    ],
+}
+DEFAULT_LOCALE = "en-GB"
+
+
+def expand_units(text: str, locale: str = DEFAULT_LOCALE) -> str:
+    for pattern, repl in _UNIT_RULES.get(locale, _UNIT_RULES[DEFAULT_LOCALE]):
+        text = re.sub(pattern, repl, text)
+    return text
+
+
+# --------------------------------------------------------------------------- #
+# Numbers                                                                     #
+# --------------------------------------------------------------------------- #
+
+
+def strip_thousands_separators(text: str) -> str:
+    """1,198.9 -> 1198.9 (so the whole number is read as one, not split)."""
+    return re.sub(r"(?<=\d),(?=\d)", "", text)
+
+
+def decimals_to_words(text: str) -> str:
+    """1198.9 -> "1198 point 9"; 770.72 -> "770 point 7 2". Removes the bare
+    "." between digits, which TTS can otherwise read as a full stop."""
+    return re.sub(
+        r"(\d+)\.(\d+)",
+        lambda m: m.group(1) + " point " + " ".join(m.group(2)),
+        text,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Pronunciations                                                              #
+# --------------------------------------------------------------------------- #
+
+
+def apply_pronunciations(text: str, mapping: dict[str, str] | None) -> str:
+    """Whole-word, case-insensitive spoken-form substitutions."""
+    for written, spoken in (mapping or {}).items():
+        text = re.sub(rf"\b{re.escape(written)}\b", spoken, text, flags=re.IGNORECASE)
+    return text
+
+
+# --------------------------------------------------------------------------- #
+# Pauses                                                                      #
+# --------------------------------------------------------------------------- #
+
+
+def shape_pauses(text: str) -> str:
+    """Give punctuation the beats it deserves: a dash used as punctuation reads
+    as a rushed nothing, and a "(" runs onto the previous word."""
+    text = text.replace("→", " to ")
+    text = re.sub(r"\s*[—–]\s*", " ... ", text)  # em / en dash
+    text = re.sub(r"\s+--?\s+", " ... ", text)  # spaced ASCII hyphen(s)
+    text = re.sub(r"(\w)\s*\(", r"\1, (", text)  # comma before "("
+    return text
+
+
+def ensure_terminal_stop(text: str) -> str:
+    """Guarantee terminal punctuation so a pause lands before the next line —
+    StackVox pauses on punctuation, not on line breaks."""
+    text = text.rstrip()
+    return text if text.endswith((".", "!", "?", ":", "…")) else text + "."
+
+
+# --------------------------------------------------------------------------- #
+# Markdown -> prose                                                           #
+# --------------------------------------------------------------------------- #
+
+
+def _strip_md_inline(line: str) -> str:
+    line = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", line)  # images
+    line = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", line)  # inline links -> text
+    line = re.sub(r"\[([^\]]+)\]\[[^\]]*\]", r"\1", line)  # reference links -> text
+    line = re.sub(r"`([^`]+)`", r"\1", line)  # inline code -> text
+    line = re.sub(r"<!--.*?-->", "", line)  # HTML comments
+    line = re.sub(r"</?[a-zA-Z][^>]*>", "", line)  # real tags + <url> autolinks; leaves "a < b"
+    line = re.sub(r"https?://\S+", "", line)  # bare URLs: strip rather than read them aloud
+    # Emphasis: only strip *paired, boundary-flanked* markers, so code-ish tokens
+    # that aren't emphasis in CommonMark — *args, **kwargs, __init__, snake_case —
+    # survive intact. Underscores are left alone entirely (TTS doesn't voice them).
+    line = re.sub(r"(?<![*\w])\*\*(?=\S)(.+?)(?<=\S)\*\*(?![*\w])", r"\1", line)  # bold
+    line = re.sub(r"(?<![*\w])\*(?=\S)(.+?)(?<=\S)\*(?![*\w])", r"\1", line)  # italic
+    line = re.sub(r"(?<!~)~~(?=\S)(.+?)(?<=\S)~~(?!~)", r"\1", line)  # strikethrough
+    return line
+
+
+def markdown_to_paragraphs(text: str, *, tables: str = "drop", strip_emoji_flag: bool = False) -> list[str]:
+    """Reduce Markdown to a list of speakable paragraphs. Headings and list
+    items become their own paragraphs (so each gets its own pause). Tables are
+    dropped or rendered comma-separated per ``tables``."""
+    text = re.sub(r"(?ms)^[ \t]*(```|~~~).*?^[ \t]*\1[ \t]*$", "\n", text)  # fenced code
+    text = re.sub(r"```+|~~~+", " ", text)  # stray fences
+    if strip_emoji_flag:
+        text = strip_emoji(text)
+
+    paragraphs: list[str] = []
+    current: list[str] = []
+    in_table = False
+
+    def flush() -> None:
+        if current:
+            paragraphs.append(" ".join(current))
+            current.clear()
+
+    def emit_csv_row(cells_source: str) -> None:
+        cells = [c.strip() for c in _strip_md_inline(cells_source.strip("|")).split("|")]
+        joined = ", ".join(c for c in cells if c)
+        if joined:
+            paragraphs.append(joined)
+
+    for raw in text.splitlines():
+        row = raw.strip()
+
+        if not row:  # blank line ends the current paragraph and any table block
+            flush()
+            in_table = False
+            continue
+
+        # link reference definition ( [id]: https://… ) — invisible when rendered
+        if re.match(r"^\[[^\]]+\]:\s*\S", row):
+            flush()
+            continue
+
+        # table separator row ( |---|---| or --- | --- )
+        if re.fullmatch(r"\|?[\s:|-]*-[\s:|-]*\|?", row):
+            # Only a *table* separator if the line above held cells; otherwise it's
+            # a `---` horizontal rule / setext underline (no table context).
+            if current and "|" in current[-1]:
+                header = current.pop()
+                flush()
+                if tables == "csv":
+                    emit_csv_row(header)
+                in_table = True
+            else:
+                flush()
+                in_table = False
+            continue
+
+        # setext underline ( === ) — drop so it isn't voiced as "equals equals…"
+        if re.fullmatch(r"=+", row):
+            flush()
+            continue
+
+        # table row: outer-pipe form, or a bare-pipe row within a table block
+        outer_pipe = len(row) >= 2 and row.startswith("|") and row.endswith("|")
+        if outer_pipe or (in_table and "|" in row):
+            flush()
+            if tables == "csv":
+                emit_csv_row(row)
+            continue
+
+        # horizontal rule ( *** / ___ ; --- is handled by the separator branch )
+        if re.fullmatch(r"([-*_])(?:\s*\1){2,}", row):
+            flush()
+            in_table = False
+            continue
+
+        in_table = False
+        is_heading = re.match(r"^\s{0,3}#{1,6}\s+", raw)
+        is_item = re.match(r"^\s*([-*+]|\d+[.)])\s+", raw)
+        cleaned = _strip_md_inline(re.sub(r"^\s{0,3}(#{1,6}\s*|(?:>\s?)+)", "", raw))
+        cleaned = re.sub(r"^\s*([-*+]|\d+[.)])\s+", "", cleaned).strip()
+        if is_item:  # drop task-list checkboxes ( - [ ] / - [x] )
+            cleaned = re.sub(r"^\[[ xX]\]\s+", "", cleaned).strip()
+
+        if is_heading or is_item:  # each stands alone -> its own pause
+            flush()
+            if cleaned:
+                paragraphs.append(cleaned)
+        elif cleaned:
+            current.append(cleaned)
+        else:
+            flush()
+
+    flush()
+    return paragraphs
+
+
+# --------------------------------------------------------------------------- #
+# Orchestrator                                                                #
+# --------------------------------------------------------------------------- #
+
+
+def _shape_paragraph(
+    text: str,
+    *,
+    pronunciations: dict[str, str] | None,
+    expand_units_flag: bool,
+    expand_numbers_flag: bool,
+    pauses_flag: bool,
+    locale: str,
+) -> str:
+    if expand_numbers_flag:
+        text = strip_thousands_separators(text)
+    if pauses_flag:
+        text = shape_pauses(text)
+    if pronunciations:
+        text = apply_pronunciations(text, pronunciations)
+    if expand_units_flag:  # units BEFORE decimals (see note above)
+        text = expand_units(text, locale)
+    if expand_numbers_flag:
+        text = decimals_to_words(text)
+    return re.sub(r"[ \t]{2,}", " ", text).strip()
+
+
+def normalize_for_speech(
+    text: str,
+    *,
+    markdown: bool = True,
+    pronunciations: dict[str, str] | None = None,
+    expand_units: bool = True,
+    expand_numbers: bool = True,
+    pauses: bool = True,
+    tables: str = "drop",
+    strip_emoji: bool = False,
+    terminal_stops: bool = True,
+    locale: str = DEFAULT_LOCALE,
+) -> str:
+    """Normalize ``text`` into speakable prose. Returns paragraphs joined by
+    newlines. See ``docs/speech-normalization.md`` for the full contract."""
+    expand_units_flag, expand_numbers_flag = expand_units, expand_numbers
+
+    if markdown:
+        paragraphs = markdown_to_paragraphs(text, tables=tables, strip_emoji_flag=strip_emoji)
+    else:
+        # `strip_emoji` (the bool kwarg) shadows the module function here, so
+        # reach for the underlying pattern directly.
+        body = _EMOJI.sub("", text) if strip_emoji else text
+        paragraphs = [p.strip() for p in re.split(r"\n\s*\n", body) if p.strip()]
+
+    out = []
+    for para in paragraphs:
+        shaped = _shape_paragraph(
+            para,
+            pronunciations=pronunciations,
+            expand_units_flag=expand_units_flag,
+            expand_numbers_flag=expand_numbers_flag,
+            pauses_flag=pauses,
+            locale=locale,
+        )
+        if not shaped:
+            continue
+        out.append(ensure_terminal_stop(shaped) if terminal_stops else shaped)
+    return "\n".join(out)

{stackvox-0.5.0 → stackvox-0.6.0/stackvox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.5.0
+Version: 0.6.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0

{stackvox-0.5.0 → stackvox-0.6.0}/stackvox.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ stackvox/daemon.py
 stackvox/engine.py
 stackvox/paths.py
 stackvox/py.typed
+stackvox/text.py
 stackvox/updates.py
 stackvox.egg-info/PKG-INFO
 stackvox.egg-info/SOURCES.txt
@@ -24,4 +25,5 @@ tests/test_daemon.py
 tests/test_daemon_protocol.py
 tests/test_engine.py
 tests/test_paths.py
+tests/test_text.py
 tests/test_updates.py

{stackvox-0.5.0 → stackvox-0.6.0}/tests/test_engine.py

@@ -8,6 +8,7 @@ runtime dependencies.
 
 from __future__ import annotations
 
+import logging
 import threading
 
 import numpy as np
@@ -99,24 +100,105 @@ class TestSynthesize:
 
 
 class TestSpeak:
-    def test_blocking_calls_play_and_wait(self, fake_kokoro, fake_audio):
-        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
-        tts = engine.Stackvox()
-        tts.speak("hi")
-        engine.sd.play.assert_called_once()
-        engine.sd.wait.assert_called_once()
+    def test_blocking_synthesizes_and_plays_each_sentence(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10, dtype=np.float32), 24000)
 
-    def test_non_blocking_skips_wait(self, fake_kokoro, fake_audio):
-        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        engine.Stackvox().speak("One sentence. Two sentence. Three here.")
+
+        # One synth + play cycle per sentence — that's what enables early audio.
+        assert fake_kokoro.return_value.create.call_count == 3
+        assert engine.sd.play.call_count == 3
+        assert engine.sd.wait.call_count == 3
+
+    def test_single_sentence_plays_once(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10, dtype=np.float32), 24000)
+        engine.Stackvox().speak("Just one sentence with no terminal punctuation")
+        assert engine.sd.play.call_count == 1
+
+    def test_non_blocking_plays_in_background_thread(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10, dtype=np.float32), 24000)
         tts = engine.Stackvox()
-        tts.speak("hi", blocking=False)
-        engine.sd.play.assert_called_once()
-        engine.sd.wait.assert_not_called()
 
-    def test_stop_calls_sounddevice_stop(self, fake_kokoro, fake_audio):
-        engine.Stackvox().stop()
+        tts.speak("hi there", blocking=False)
+
+        assert tts._play_thread is not None
+        tts._play_thread.join(timeout=5)
+        engine.sd.play.assert_called()
+
+    def test_passes_engine_defaults_to_synthesis(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(4, dtype=np.float32), 24000)
+        engine.Stackvox(voice="af_sarah", speed=1.0, lang="en-us").speak("hello")
+        fake_kokoro.return_value.create.assert_called_once_with(
+            "hello", voice="af_sarah", speed=1.0, lang="en-us"
+        )
+
+    def test_per_call_overrides_take_priority(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(4, dtype=np.float32), 24000)
+        engine.Stackvox(voice="af_sarah", speed=1.0, lang="en-us").speak(
+            "hi", voice="bf_emma", speed=1.5, lang="en-gb"
+        )
+        fake_kokoro.return_value.create.assert_called_once_with(
+            "hi", voice="bf_emma", speed=1.5, lang="en-gb"
+        )
+
+    def test_stop_sets_event_and_calls_sounddevice_stop(self, fake_kokoro, fake_audio):
+        tts = engine.Stackvox()
+        tts.stop()
+        assert tts._stop_event.is_set()
         engine.sd.stop.assert_called_once()
 
+    def test_blocking_surfaces_synthesis_errors(self, fake_kokoro, fake_audio):
+        # Regression: a Kokoro failure must propagate, not report silent success.
+        fake_kokoro.return_value.create.side_effect = RuntimeError("boom")
+        tts = engine.Stackvox()
+        with pytest.raises(RuntimeError, match="boom"):
+            tts.speak("hello there")
+
+    def test_non_blocking_logs_synthesis_errors_without_crashing(self, fake_kokoro, fake_audio, caplog):
+        fake_kokoro.return_value.create.side_effect = RuntimeError("boom")
+        tts = engine.Stackvox()
+        with caplog.at_level(logging.ERROR):
+            tts.speak("hi there", blocking=False)
+            assert tts._play_thread is not None
+            tts._play_thread.join(timeout=5)
+        assert "playback failed" in caplog.text
+
+    def test_each_speak_uses_a_fresh_stop_event(self, fake_kokoro, fake_audio):
+        # A per-stream event means a later speak() can't clear an older stream's
+        # cancellation (and stop() only affects the stream it was called on).
+        fake_kokoro.return_value.create.return_value = (np.zeros(4, dtype=np.float32), 24000)
+        tts = engine.Stackvox()
+        original = tts._stop_event
+        tts.speak("one sentence")
+        assert tts._stop_event is not original
+
+    def test_speak_after_stop_still_plays(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(4, dtype=np.float32), 24000)
+        tts = engine.Stackvox()
+        tts.stop()
+        tts.speak("hello world")
+        engine.sd.play.assert_called()
+
+
+class TestSplitSentences:
+    def test_splits_on_sentence_punctuation(self):
+        assert engine._split_sentences("One. Two! Three?") == ["One.", "Two!", "Three?"]
+
+    def test_leaves_decimals_and_mid_token_dots_intact(self):
+        assert engine._split_sentences("Set speed 0.95 in config.toml now.") == [
+            "Set speed 0.95 in config.toml now."
+        ]
+
+    def test_splits_on_newlines(self):
+        assert engine._split_sentences("Line one\nLine two\n\nLine three") == [
+            "Line one",
+            "Line two",
+            "Line three",
+        ]
+
+    def test_blank_text_yields_no_sentences(self):
+        assert engine._split_sentences("   \n  ") == []
+
 
 class TestVoices:
     def test_returns_sorted_voice_ids(self, fake_kokoro):

stackvox-0.6.0/tests/test_text.py

@@ -0,0 +1,197 @@
+"""Tests for stackvox.text — speech-text normalization."""
+
+from stackvox.text import (
+    apply_pronunciations,
+    decimals_to_words,
+    ensure_terminal_stop,
+    expand_units,
+    markdown_to_paragraphs,
+    normalize_for_speech,
+    shape_pauses,
+    strip_emoji,
+    strip_thousands_separators,
+)
+
+# --- numbers ---------------------------------------------------------------
+
+
+def test_thousands_separators_removed():
+    assert strip_thousands_separators("1,198.9 and 2,294.7") == "1198.9 and 2294.7"
+
+
+def test_decimals_spoken_digit_by_digit():
+    assert decimals_to_words("1198.9") == "1198 point 9"
+    assert decimals_to_words("770.72") == "770 point 7 2"
+
+
+def test_year_is_not_a_decimal():
+    assert decimals_to_words("built in 2023") == "built in 2023"
+
+
+# --- units -----------------------------------------------------------------
+
+
+def test_currency_and_pence():
+    assert expand_units("£1.63") == "1.63 pounds"
+    assert expand_units("25p per litre") == "25 pence per litre"
+    assert expand_units("167.14p") == "167.14 pence"
+
+
+def test_kwh_spaced_and_glued_units():
+    assert expand_units("13.5 kWh") == "13.5 kilowatt hours"
+    assert expand_units("per kWh") == "per kilowatt hours"
+    assert expand_units("65kg") == "65 kilograms"
+    assert expand_units("a 4km trip") == "a 4 kilometres trip"
+
+
+def test_math_symbols():
+    assert expand_units("770 ÷ 2 × 3 = 5").strip() == "770 divided by 2 times 3 equals 5"
+
+
+def test_unknown_locale_falls_back_to_en_gb():
+    assert expand_units("£5", locale="xx-YY") == "5 pounds"
+
+
+# --- pronunciations --------------------------------------------------------
+
+
+def test_pronunciations_whole_word_case_insensitive():
+    m = {"Redis": "Reddis", "agy": "antigravity"}
+    assert apply_pronunciations("Redis and AGY", m) == "Reddis and antigravity"
+
+
+def test_pronunciations_do_not_match_substrings():
+    # "StackOne" must not partially rewrite "StackOneHQ"
+    assert apply_pronunciations("StackOneHQ", {"StackOne": "stack one"}) == "StackOneHQ"
+
+
+# --- pauses ----------------------------------------------------------------
+
+
+def test_dash_becomes_ellipsis_pause():
+    assert shape_pauses("in control - once I started") == "in control ... once I started"
+
+
+def test_comma_inserted_before_paren():
+    assert shape_pauses("Claude Code (CC)") == "Claude Code, (CC)"
+
+
+def test_ensure_terminal_stop():
+    assert ensure_terminal_stop("About") == "About."
+    assert ensure_terminal_stop("Ready?") == "Ready?"
+    assert ensure_terminal_stop("A list:") == "A list:"
+
+
+# --- emoji -----------------------------------------------------------------
+
+
+def test_strip_emoji():
+    assert (
+        strip_emoji("done ✅ and 🚀 go").replace("  ", " ").strip()
+        == "done  and  go".replace("  ", " ").strip()
+    )
+
+
+# --- markdown --------------------------------------------------------------
+
+
+def test_markdown_headings_and_lists_are_own_paragraphs():
+    md = "# Title\n\nBody line.\n\n- one\n- two"
+    assert markdown_to_paragraphs(md) == ["Title", "Body line.", "one", "two"]
+
+
+def test_markdown_links_and_code_reduced_to_text():
+    md = "See [the docs](https://x.example) and run `make build`."
+    assert markdown_to_paragraphs(md) == ["See the docs and run make build."]
+
+
+def test_fenced_code_dropped():
+    md = "Before.\n\n```py\nprint('hi')\n```\n\nAfter."
+    assert markdown_to_paragraphs(md) == ["Before.", "After."]
+
+
+def test_tables_dropped_by_default():
+    md = "| A | B |\n| --- | --- |\n| 1 | 2 |"
+    assert markdown_to_paragraphs(md) == []
+
+
+def test_tables_as_csv():
+    md = "| A | B |\n| --- | --- |\n| 1 | 2 |"
+    assert markdown_to_paragraphs(md, tables="csv") == ["A, B", "1, 2"]
+
+
+def test_tables_without_outer_pipes_are_recognized():
+    md = "A | B\n--- | ---\n1 | 2"
+    assert markdown_to_paragraphs(md) == []
+    assert markdown_to_paragraphs(md, tables="csv") == ["A, B", "1, 2"]
+
+
+def test_code_identifiers_are_not_treated_as_emphasis():
+    # __init__, **kwargs and *args are not emphasis in CommonMark — keep them.
+    md = "The `__init__` method takes **kwargs and *args."
+    assert markdown_to_paragraphs(md) == ["The __init__ method takes **kwargs and *args."]
+
+
+def test_paired_emphasis_markers_are_stripped():
+    md = "This is **bold** and *italic* text."
+    assert markdown_to_paragraphs(md) == ["This is bold and italic text."]
+
+
+def test_angle_brackets_in_prose_are_kept():
+    # Only real HTML tags are stripped, not comparisons.
+    assert markdown_to_paragraphs("Voltage: x < y and y > z.") == ["Voltage: x < y and y > z."]
+    assert markdown_to_paragraphs("Wrap <b>x</b> now.") == ["Wrap x now."]
+
+
+def test_bare_urls_and_reference_definitions_are_dropped():
+    md = "See [the docs][docs] here.\n\n[docs]: https://example.com/path"
+    assert markdown_to_paragraphs(md) == ["See the docs here."]
+    # whitespace left by the stripped URL is collapsed by the full pipeline
+    assert normalize_for_speech("Go to https://example.com now.") == "Go to now."
+
+
+def test_setext_underline_is_dropped():
+    assert markdown_to_paragraphs("The Verdict\n===========\n\nBody.") == ["The Verdict", "Body."]
+
+
+def test_task_list_checkboxes_are_stripped():
+    assert markdown_to_paragraphs("- [ ] todo\n- [x] done") == ["todo", "done"]
+
+
+def test_nested_blockquote_markers_are_stripped():
+    assert markdown_to_paragraphs("> > deeply quoted") == ["deeply quoted"]
+
+
+# --- end to end ------------------------------------------------------------
+
+
+def test_currency_runs_before_decimal_split():
+    # The ordering bug guard: £1.63 -> "1.63 pounds" -> "1 point 6 3 pounds",
+    # never "£1 point 63".
+    out = normalize_for_speech("It cost £1.63 today.", markdown=False)
+    assert "1 point 6 3 pounds" in out
+    assert "£" not in out
+
+
+def test_blog_style_normalization():
+    md = "## The Verdict\n\nIt drew 770.72 kWh for £192.68 - a loss."
+    out = normalize_for_speech(md, pronunciations={}, tables="drop")
+    assert out == ("The Verdict.\nIt drew 770 point 7 2 kilowatt hours for 192 point 6 8 pounds ... a loss.")
+
+
+def test_speaklast_style_normalization():
+    md = "I updated `Redis` ✅ and the CLI (v2)."
+    out = normalize_for_speech(
+        md,
+        pronunciations={"Redis": "Reddis", "CLI": "C L I"},
+        tables="csv",
+        strip_emoji=True,
+    )
+    assert "Reddis" in out
+    assert "C L I, (v2)" in out
+    assert "✅" not in out
+
+
+def test_plain_text_mode_splits_paragraphs():
+    out = normalize_for_speech("First para.\n\nSecond para.", markdown=False)
+    assert out == "First para.\nSecond para."