stackvox 0.7.0__tar.gz → 0.9.0__tar.gz

{stackvox-0.7.0/stackvox.egg-info → stackvox-0.9.0}/PKG-INFO

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

{stackvox-0.7.0 → stackvox-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.7.0"
+version = "0.9.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"

{stackvox-0.7.0 → stackvox-0.9.0}/stackvox/cli.py

@@ -208,6 +208,12 @@ def _add_normalize_args(parser: argparse.ArgumentParser, *, with_switch: bool) -
         type=Path,
         help="JSON file mapping written -> spoken forms (whole-word, case-insensitive)",
     )
+    parser.add_argument(
+        "--no-dev-terms",
+        dest="dev_terms",
+        action="store_false",
+        help="Do not spell out dev acronyms espeak mispronounces (CLI, CI, IDE, AWS, URI, IAM, ...)",
+    )
     parser.add_argument(
         "--no-expand-units",
         dest="expand_units",
@@ -268,6 +274,7 @@ def _normalize_kwargs(args: argparse.Namespace) -> dict:
     return {
         "markdown": args.markdown,
         "pronunciations": _load_pronunciations(args.pronunciations),
+        "dev_terms": args.dev_terms,
         "expand_units": args.expand_units,
         "expand_numbers": args.expand_numbers,
         "pauses": args.pauses,
@@ -382,9 +389,18 @@ def _cmd_stop(_: argparse.Namespace) -> int:
 
 
 def _cmd_status(_: argparse.Namespace) -> int:
+    installed = updates._current_version()
     if daemon.is_running():
         print(f"running (pid {daemon.PID_PATH.read_text().strip()}) on {daemon.SOCKET_PATH}")
         rc = 0
+        # The running daemon can lag the installed package if it wasn't restarted
+        # after an upgrade — surface that skew instead of trusting it blindly.
+        got, running_version = daemon.version()
+        if got and running_version != installed:
+            print(
+                f"daemon running {running_version}, but {installed} is installed "
+                f"— restart the daemon (stackvox stop; stackvox serve) to pick it up"
+            )
     else:
         print("stopped")
         rc = 1

{stackvox-0.7.0 → stackvox-0.9.0}/stackvox/daemon.py

@@ -222,6 +222,10 @@ class _Handler(socketserver.StreamRequestHandler):
             self.wfile.write(b"ok\n")
             return
 
+        if command == "version":
+            self.wfile.write(f"{updates._current_version()}\n".encode())
+            return
+
         if command == "stop":
             self.wfile.write(b"ok\n")
             threading.Thread(target=self.server.shutdown, daemon=True).start()
@@ -343,3 +347,14 @@ def stop() -> tuple[bool, str]:
 
 def ping() -> tuple[bool, str]:
     return send({"command": "ping"}, timeout=PING_TIMEOUT_SECONDS)
+
+
+def version(timeout: float = PING_TIMEOUT_SECONDS) -> tuple[bool, str]:
+    """(got_version, version_or_error) reported by the running daemon.
+
+    The running daemon can differ from the installed package if it wasn't
+    restarted after an upgrade, so this reports what is actually serving — not
+    what's on disk. A version reply starts with a digit; error strings don't.
+    """
+    _, resp = send({"command": "version"}, timeout=timeout)
+    return resp[:1].isdigit(), resp

{stackvox-0.7.0 → stackvox-0.9.0}/stackvox/engine.py

@@ -22,6 +22,12 @@ DEFAULT_VOICE = "af_sarah"
 DEFAULT_SPEED = 1.0
 DEFAULT_LANG = "en-us"
 
+# Streaming playback smoothing: play a touch of silence before the first word so
+# output-device warm-up (notably a Bluetooth codec/profile switch) lands during
+# silence, and ramp the opening samples up from zero to avoid an onset click.
+_PRIME_SILENCE_SECONDS = 0.12
+_FADE_IN_SECONDS = 0.008
+
 _MODEL_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx"
 _VOICES_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin"
 
@@ -82,6 +88,16 @@ def _split_sentences(text: str) -> list[str]:
     return [part.strip() for part in _SENTENCE_BOUNDARY.split(text.strip()) if part.strip()]
 
 
+def _fade_in(samples: np.ndarray, sample_rate: int) -> np.ndarray:
+    """Ramp the opening samples up from zero so playback doesn't begin with a click."""
+    ramp_len = min(len(samples), int(sample_rate * _FADE_IN_SECONDS))
+    if ramp_len <= 0:
+        return samples
+    faded = np.array(samples, dtype="float32", copy=True)
+    faded[:ramp_len] *= np.linspace(0.0, 1.0, ramp_len, dtype="float32")
+    return faded
+
+
 class Stackvox:
     """Reusable TTS engine. Load the model once, speak many times.
 
@@ -104,6 +120,8 @@ class Stackvox:
         self._kokoro = Kokoro(str(model_path), str(voices_path))
         self._stop_event = threading.Event()
         self._play_thread: threading.Thread | None = None
+        self._stream: sd.OutputStream | None = None
+        self._stream_lock = threading.Lock()
 
     def synthesize(
         self,
@@ -210,6 +228,7 @@ class Stackvox:
         producer = threading.Thread(target=_produce, daemon=True, name="stackvox-synth")
         producer.start()
         error: Exception | None = None
+        stream: sd.OutputStream | None = None
         try:
             while not stop_event.is_set():
                 item = chunks.get()
@@ -219,9 +238,36 @@ class Stackvox:
                     error = item
                     break
                 samples, sample_rate = item
-                sd.play(samples, sample_rate)
-                sd.wait()
+                samples = np.ascontiguousarray(samples, dtype="float32")
+                if stream is None:
+                    # One stream for the whole utterance: writing chunks into it is
+                    # gapless and avoids the per-sentence open/close that crackles at
+                    # the start. Prime with silence so device warm-up (e.g. a
+                    # Bluetooth codec switch) lands before the first word, and fade
+                    # the opening samples in to avoid an onset click.
+                    stream = sd.OutputStream(samplerate=sample_rate, channels=1, dtype="float32")
+                    stream.start()
+                    with self._stream_lock:
+                        self._stream = stream
+                    prime = int(sample_rate * _PRIME_SILENCE_SECONDS)
+                    if prime > 0:
+                        stream.write(np.zeros(prime, dtype="float32"))
+                    samples = _fade_in(samples, sample_rate)
+                try:
+                    stream.write(samples)
+                except Exception:
+                    if stop_event.is_set():
+                        break  # aborted by stop(); expected
+                    raise
         finally:
+            with self._stream_lock:
+                self._stream = None
+            if stream is not None:
+                try:
+                    stream.stop()
+                    stream.close()
+                except Exception:
+                    logger.debug("stream teardown failed", exc_info=True)
             # 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()
@@ -236,6 +282,12 @@ class Stackvox:
     def stop(self) -> None:
         """Stop any in-progress playback started with blocking=False."""
         self._stop_event.set()
+        with self._stream_lock:
+            if self._stream is not None:
+                try:
+                    self._stream.abort()
+                except Exception:
+                    logger.debug("stream abort failed", exc_info=True)
         sd.stop()
 
     def voices(self) -> list[str]:

{stackvox-0.7.0 → stackvox-0.9.0}/stackvox/text.py

@@ -18,6 +18,7 @@ __all__ = [
     "markdown_to_paragraphs",
     "strip_emoji",
     "strip_thousands_separators",
+    "versions_to_words",
     "decimals_to_words",
     "expand_units",
     "apply_pronunciations",
@@ -84,6 +85,21 @@ def strip_thousands_separators(text: str) -> str:
     return re.sub(r"(?<=\d),(?=\d)", "", text)
 
 
+_VERSION = re.compile(r"(?<!\d)\d+(?:\.\d+){2,}(?!\d)")
+
+
+def versions_to_words(text: str) -> str:
+    """1.2.3 -> "1 point 2 point 3"; 0.7.0 -> "0 point 7 point 0".
+
+    A dotted version string has more than one decimal point, which
+    `decimals_to_words` can't handle — it splits only the first, leaving a stray
+    full stop mid-number ("0.7.0" -> "0 point 7.0"). Run this before it. Two-part
+    numbers are left untouched so ordinary decimals still read digit-by-digit,
+    and a trailing sentence stop (``upgrade to 1.2.3.``) is preserved.
+    """
+    return _VERSION.sub(lambda m: m.group(0).replace(".", " point "), 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."""
@@ -106,6 +122,28 @@ def apply_pronunciations(text: str, mapping: dict[str, str] | None) -> str:
     return text
 
 
+# Dev acronyms/terms espeak mispronounces — it reads them as a word ("CLI" ->
+# "kligh", "AWS" -> "awz", "URI" -> "yuri") instead of spelling them out.
+# Applied by default (dev_terms=True), whole-word and case-insensitive, so
+# lowercase "cli" is fixed too. Compound keys (ci/cd) precede their parts (ci)
+# so the specific form wins. Only terms espeak gets WRONG are here — API, URL,
+# JSON, YAML, HTTP, CRUD, nginx, etc. already voice correctly and are left alone.
+_DEV_PRONUNCIATIONS: dict[str, str] = {
+    "ci/cd": "C I C D",
+    "cli": "C L I",
+    "ci": "C I",
+    "ide": "I D E",
+    "aws": "A W S",
+    "uri": "U R I",
+    "iam": "I A M",
+    "saas": "sass",
+    "paas": "pass",
+    "tui": "T U I",
+    "postgresql": "postgres",
+    "kubectl": "kube control",
+}
+
+
 # --------------------------------------------------------------------------- #
 # Pauses                                                                      #
 # --------------------------------------------------------------------------- #
@@ -265,6 +303,7 @@ def _shape_paragraph(
     if expand_units_flag:  # units BEFORE decimals (see note above)
         text = expand_units(text, locale)
     if expand_numbers_flag:
+        text = versions_to_words(text)  # multi-dot versions BEFORE the decimal split
         text = decimals_to_words(text)
     return re.sub(r"[ \t]{2,}", " ", text).strip()
 
@@ -274,6 +313,7 @@ def normalize_for_speech(
     *,
     markdown: bool = True,
     pronunciations: dict[str, str] | None = None,
+    dev_terms: bool = True,
     expand_units: bool = True,
     expand_numbers: bool = True,
     pauses: bool = True,
@@ -285,6 +325,11 @@ def normalize_for_speech(
     """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
+    # Built-in dev-term fixes first; caller-supplied pronunciations override them
+    # (keyed case-insensitively, so a caller's "CLI" beats the default "cli").
+    effective_pronunciations: dict[str, str] = dict(_DEV_PRONUNCIATIONS) if dev_terms else {}
+    for written, spoken in (pronunciations or {}).items():
+        effective_pronunciations[written.lower()] = spoken
 
     if markdown:
         paragraphs = markdown_to_paragraphs(text, tables=tables, strip_emoji_flag=strip_emoji)
@@ -298,7 +343,7 @@ def normalize_for_speech(
     for para in paragraphs:
         shaped = _shape_paragraph(
             para,
-            pronunciations=pronunciations,
+            pronunciations=effective_pronunciations,
             expand_units_flag=expand_units_flag,
             expand_numbers_flag=expand_numbers_flag,
             pauses_flag=pauses,

{stackvox-0.7.0 → stackvox-0.9.0/stackvox.egg-info}/PKG-INFO

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

{stackvox-0.7.0 → stackvox-0.9.0}/tests/test_cli.py

@@ -128,6 +128,7 @@ def _norm_ns(text=None, file=None, **overrides):
         file=file,
         markdown=True,
         pronunciations=None,
+        dev_terms=True,
         expand_units=True,
         expand_numbers=True,
         pauses=True,
@@ -260,6 +261,9 @@ class TestCmdStatus:
         pid_path.read_text.return_value = "12345\n"
         mocker.patch.object(cli.daemon, "PID_PATH", pid_path)
         mocker.patch.object(cli.daemon, "SOCKET_PATH", "/tmp/x.sock")
+        # status now queries the running daemon's version; stub it so the test
+        # doesn't reach a real socket.
+        mocker.patch.object(cli.daemon, "version", return_value=(False, "n/a"))
 
         rc = cli._cmd_status(_ns())
 
@@ -268,6 +272,23 @@ class TestCmdStatus:
         assert "running" in out
         assert "12345" in out
 
+    def test_running_flags_daemon_version_skew(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "is_running", return_value=True)
+        pid_path = mocker.MagicMock()
+        pid_path.read_text.return_value = "1\n"
+        mocker.patch.object(cli.daemon, "PID_PATH", pid_path)
+        mocker.patch.object(cli.daemon, "SOCKET_PATH", "/tmp/x.sock")
+        mocker.patch.object(cli.daemon, "version", return_value=(True, "0.5.0"))
+        mocker.patch.object(cli.updates, "_current_version", return_value="0.8.0")
+        mocker.patch.object(cli.updates, "check_for_update", return_value=None)
+
+        rc = cli._cmd_status(_ns())
+
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "0.5.0" in out and "0.8.0" in out  # the skew is surfaced
+        assert "restart" in out.lower()
+
     def test_stopped_returns_one(self, mocker, capsys):
         mocker.patch.object(cli.daemon, "is_running", return_value=False)
         rc = cli._cmd_status(_ns())

{stackvox-0.7.0 → stackvox-0.9.0}/tests/test_daemon_protocol.py

@@ -76,6 +76,22 @@ def test_ping_returns_ok(server: ServerHarness):
     assert _roundtrip(server.sock, json.dumps({"command": "ping"}) + "\n") == "ok"
 
 
+def test_version_returns_installed_version(server: ServerHarness):
+    from stackvox import updates
+
+    reply = _roundtrip(server.sock, json.dumps({"command": "version"}) + "\n")
+    assert reply == updates._current_version()
+
+
+def test_version_client_helper_reports_running_version(server: ServerHarness, monkeypatch):
+    from stackvox import daemon, updates
+
+    monkeypatch.setattr(daemon, "SOCKET_PATH", server.sock)
+    got, resp = daemon.version()
+    assert got is True
+    assert resp == updates._current_version()
+
+
 def test_plain_text_is_treated_as_text_field(server: ServerHarness):
     """Non-JSON payloads are accepted and wrapped as `{"text": line}`."""
     import time

{stackvox-0.7.0 → stackvox-0.9.0}/tests/test_engine.py

@@ -35,7 +35,8 @@ def fake_kokoro(mocker, fake_ensure_models):
 
 @pytest.fixture
 def fake_audio(mocker):
-    """Mock the sounddevice surface used by Stackvox."""
+    """Mock the sounddevice surface used by Stackvox (streaming + speak_sequence)."""
+    mocker.patch.object(engine.sd, "OutputStream")
     mocker.patch.object(engine.sd, "play")
     mocker.patch.object(engine.sd, "wait")
     mocker.patch.object(engine.sd, "stop")
@@ -105,15 +106,35 @@ class TestSpeak:
 
         engine.Stackvox().speak("One sentence. Two sentence. Three here.")
 
-        # One synth + play cycle per sentence — that's what enables early audio.
+        # One synth per sentence (early audio), all streamed through a single
+        # output stream: a prime-silence write plus one write per sentence.
         assert fake_kokoro.return_value.create.call_count == 3
-        assert engine.sd.play.call_count == 3
-        assert engine.sd.wait.call_count == 3
+        engine.sd.OutputStream.assert_called_once()
+        stream = engine.sd.OutputStream.return_value
+        assert stream.write.call_count == 4  # 1 prime + 3 sentences
+        stream.close.assert_called_once()
 
     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
+        engine.sd.OutputStream.assert_called_once()
+        assert engine.sd.OutputStream.return_value.write.call_count == 2  # prime + 1 sentence
+
+    def test_primes_with_silence_before_first_audio(self, fake_kokoro, fake_audio):
+        # The lead-in silence lets the output device (e.g. Bluetooth) warm up
+        # before the first word, rather than crackling into it.
+        fake_kokoro.return_value.create.return_value = (np.ones(10, dtype=np.float32), 24000)
+        engine.Stackvox().speak("hello")
+        prime = engine.sd.OutputStream.return_value.write.call_args_list[0].args[0]
+        assert not prime.any()
+        assert len(prime) == int(24000 * engine._PRIME_SILENCE_SECONDS)
+
+    def test_first_audio_fades_in_from_zero(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.ones(1000, dtype=np.float32), 24000)
+        engine.Stackvox().speak("hello")
+        first_audio = engine.sd.OutputStream.return_value.write.call_args_list[1].args[0]
+        assert first_audio[0] == 0.0  # ramp starts at silence
+        assert first_audio[-1] == 1.0  # ramp completes, body untouched
 
     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)
@@ -123,7 +144,7 @@ class TestSpeak:
 
         assert tts._play_thread is not None
         tts._play_thread.join(timeout=5)
-        engine.sd.play.assert_called()
+        engine.sd.OutputStream.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)
@@ -177,7 +198,7 @@ class TestSpeak:
         tts = engine.Stackvox()
         tts.stop()
         tts.speak("hello world")
-        engine.sd.play.assert_called()
+        engine.sd.OutputStream.assert_called()
 
 
 class TestSplitSentences:

{stackvox-0.7.0 → stackvox-0.9.0}/tests/test_text.py

@@ -10,6 +10,7 @@ from stackvox.text import (
     shape_pauses,
     strip_emoji,
     strip_thousands_separators,
+    versions_to_words,
 )
 
 # --- numbers ---------------------------------------------------------------
@@ -28,6 +29,31 @@ def test_year_is_not_a_decimal():
     assert decimals_to_words("built in 2023") == "built in 2023"
 
 
+def test_semver_all_parts_spoken():
+    assert versions_to_words("0.7.0") == "0 point 7 point 0"
+    assert versions_to_words("1.2.3") == "1 point 2 point 3"
+
+
+def test_semver_multi_digit_component():
+    assert versions_to_words("1.20.3") == "1 point 20 point 3"
+
+
+def test_version_preserves_trailing_sentence_stop():
+    assert versions_to_words("upgrade to 1.2.3.") == "upgrade to 1 point 2 point 3."
+
+
+def test_two_part_number_is_left_for_the_decimal_pass():
+    # Only two components — an ordinary decimal, not a version.
+    assert versions_to_words("3.14") == "3.14"
+    assert decimals_to_words(versions_to_words("3.14")) == "3 point 1 4"
+
+
+def test_semver_normalizes_end_to_end():
+    out = normalize_for_speech("Upgraded to 0.7.0 today.", markdown=False)
+    assert "0 point 7 point 0" in out
+    assert "0 point 7.0" not in out
+
+
 # --- units -----------------------------------------------------------------
 
 
@@ -195,3 +221,28 @@ def test_speaklast_style_normalization():
 def test_plain_text_mode_splits_paragraphs():
     out = normalize_for_speech("First para.\n\nSecond para.", markdown=False)
     assert out == "First para.\nSecond para."
+
+
+def test_dev_acronyms_are_spelled_out():
+    assert normalize_for_speech("Use the CLI.", markdown=False) == "Use the C L I."
+    assert "C L I" in normalize_for_speech("the cli tool", markdown=False)  # lowercase too
+    assert "A W S" in normalize_for_speech("deploy to AWS", markdown=False)
+    assert "U R I" in normalize_for_speech("parse the URI", markdown=False)
+    assert "C I C D" in normalize_for_speech("the CI/CD pipeline", markdown=False)
+
+
+def test_dev_terms_leave_correctly_voiced_acronyms_alone():
+    out = normalize_for_speech("Send JSON over HTTP to the API.", markdown=False)
+    assert "JSON" in out
+    assert "HTTP" in out
+    assert "API" in out
+
+
+def test_dev_terms_can_be_disabled():
+    assert normalize_for_speech("Use the CLI.", markdown=False, dev_terms=False) == "Use the CLI."
+
+
+def test_caller_pronunciations_override_dev_terms():
+    out = normalize_for_speech("Use the CLI.", markdown=False, pronunciations={"CLI": "command line"})
+    assert "command line" in out
+    assert "C L I" not in out