stackvox 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.4.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
@@ -118,11 +118,13 @@ Keeps the model resident so each subsequent call is instant:
 
 ```bash
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
-stackvox status        # is the daemon up?
+stackvox status        # is the daemon up? also shows version + any pending PyPI update
 stackvox say "Hello"   # send text to the daemon (fails if not running)
 stackvox stop          # graceful shutdown
 ```
 
+stackvox checks PyPI for newer versions but only at two moments — when you run `stackvox status` and at daemon startup. The script-heavy paths (`say`, `speak`, `stackvox-say`, hooks, CI) never make a network call. To see notices on every invocation set `STACKVOX_UPDATE_NOTICE=1`. To disable the check entirely set `STACKVOX_NO_UPDATE_CHECK=1`. The check is auto-skipped when common CI env vars (`CI`, `GITHUB_ACTIONS`, etc.) are set so build logs stay clean.
+
 ## `stackvox-say` (bash helper, ~13ms)
 
 When you want minimum latency from shell scripts (hooks, CI steps, etc.), skip the Python client and use the bash helper — it talks directly to the daemon's unix socket via `nc`:

{stackvox-0.4.0 → stackvox-0.6.0}/README.md

@@ -84,11 +84,13 @@ Keeps the model resident so each subsequent call is instant:
 
 ```bash
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
-stackvox status        # is the daemon up?
+stackvox status        # is the daemon up? also shows version + any pending PyPI update
 stackvox say "Hello"   # send text to the daemon (fails if not running)
 stackvox stop          # graceful shutdown
 ```
 
+stackvox checks PyPI for newer versions but only at two moments — when you run `stackvox status` and at daemon startup. The script-heavy paths (`say`, `speak`, `stackvox-say`, hooks, CI) never make a network call. To see notices on every invocation set `STACKVOX_UPDATE_NOTICE=1`. To disable the check entirely set `STACKVOX_NO_UPDATE_CHECK=1`. The check is auto-skipped when common CI env vars (`CI`, `GITHUB_ACTIONS`, etc.) are set so build logs stay clean.
+
 ## `stackvox-say` (bash helper, ~13ms)
 
 When you want minimum latency from shell scripts (hooks, CI steps, etc.), skip the Python client and use the bash helper — it talks directly to the daemon's unix socket via `nc`:

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.4.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.4.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.4.0 → stackvox-0.6.0}/stackvox/cli.py

@@ -4,12 +4,13 @@ from __future__ import annotations
 
 import argparse
 import logging
+import os
 import sys
 from pathlib import Path
 
 import soundfile as sf
 
-from stackvox import config, daemon
+from stackvox import config, daemon, updates
 from stackvox.engine import Stackvox
 
 
@@ -226,9 +227,18 @@ def _cmd_stop(_: argparse.Namespace) -> int:
 def _cmd_status(_: argparse.Namespace) -> int:
     if daemon.is_running():
         print(f"running (pid {daemon.PID_PATH.read_text().strip()}) on {daemon.SOCKET_PATH}")
-        return 0
-    print("stopped")
-    return 1
+        rc = 0
+    else:
+        print("stopped")
+        rc = 1
+    # Status is the canonical "is everything OK?" query — surface update info
+    # here regardless of running/stopped. Synchronous fetch with 2s timeout.
+    info = updates.check_for_update()
+    if info is not None:
+        print(f"version: {info.current} ({updates.format_notice(info)})")
+    else:
+        print(f"version: {updates._current_version()}")
+    return rc
 
 
 def _cmd_voices(args: argparse.Namespace) -> int:
@@ -289,6 +299,21 @@ def _cmd_install_helper(args: argparse.Namespace) -> int:
     return 0
 
 
+def _maybe_print_update_notice() -> None:
+    """Opt-in stderr notice for the script-friendly default-off case.
+
+    Off by default (most stackvox invocations are non-interactive — hooks,
+    CI, scripts — and pollution there is worse than the missed notice).
+    Set `STACKVOX_UPDATE_NOTICE=1` to turn it on. Reads cache only; never
+    fetches from PyPI on this path.
+    """
+    if not os.environ.get("STACKVOX_UPDATE_NOTICE"):
+        return
+    info = updates.cached_update()
+    if info is not None:
+        print(f"[stackvox] {updates.format_notice(info)}", file=sys.stderr)
+
+
 def main() -> int:
     _configure_logging()
     argv = sys.argv[1:]
@@ -299,6 +324,8 @@ def main() -> int:
     elif not argv and not sys.stdin.isatty():
         argv = ["speak"]
 
+    _maybe_print_update_notice()
+
     parser = _build_parser(config.load_defaults())
     args = parser.parse_args(argv)
 

{stackvox-0.4.0 → stackvox-0.6.0}/stackvox/daemon.py

@@ -28,6 +28,7 @@ from typing import Any
 
 import sounddevice as sd
 
+from stackvox import updates
 from stackvox.engine import DEFAULT_LANG, DEFAULT_SPEED, DEFAULT_VOICE, Stackvox
 from stackvox.paths import pid_path, socket_path
 
@@ -260,6 +261,22 @@ def is_running() -> bool:
     return _pid_alive(pid)
 
 
+def _check_for_update_async() -> None:
+    """Spawn a background thread that checks PyPI for an update and logs it.
+
+    Runs at daemon startup, off the critical path. The user is at a terminal
+    when they `stackvox serve`, so the daemon's stderr is visible — that's
+    the highest-leverage moment to surface "you should upgrade".
+    """
+
+    def _worker() -> None:
+        info = updates.check_for_update()
+        if info is not None:
+            logger.info(updates.format_notice(info))
+
+    threading.Thread(target=_worker, daemon=True, name="update-check").start()
+
+
 def serve(voice: str = DEFAULT_VOICE, speed: float = DEFAULT_SPEED, lang: str = DEFAULT_LANG) -> None:
     if is_running():
         raise RuntimeError(f"daemon already running (pid {PID_PATH.read_text().strip()})")
@@ -273,6 +290,7 @@ def serve(voice: str = DEFAULT_VOICE, speed: float = DEFAULT_SPEED, lang: str =
     server.state = state  # type: ignore[attr-defined]
 
     PID_PATH.write_text(str(os.getpid()))
+    _check_for_update_async()
 
     def handle_signal(signum: int, frame: object) -> None:
         state.shutdown()

{stackvox-0.4.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)