stackvox 0.2.1__tar.gz → 0.3.1__tar.gz

{stackvox-0.2.1/stackvox.egg-info → stackvox-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.2.1
+Version: 0.3.1
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -45,11 +45,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash
@@ -74,6 +83,17 @@ stackvox speak "Hi" --voice bf_emma # same, explicit subcommand
 stackvox speak "save" --out a.wav   # write wav instead of playing
 stackvox welcome                    # multilingual welcome (6 languages)
 stackvox voices                     # list all voice ids
+echo "from a pipe" | stackvox       # piped stdin works for speak/say
+stackvox speak --file message.txt   # read a whole file
+```
+
+Bash completion:
+
+```bash
+eval "$(stackvox completion bash)"  # current shell
+# or persist:
+stackvox completion bash > ~/.stackvox-completion.bash
+echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
 Daemon mode (keeps the model resident so each subsequent call is instant):

{stackvox-0.2.1 → stackvox-0.3.1}/README.md

@@ -12,11 +12,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash
@@ -41,6 +50,17 @@ stackvox speak "Hi" --voice bf_emma # same, explicit subcommand
 stackvox speak "save" --out a.wav   # write wav instead of playing
 stackvox welcome                    # multilingual welcome (6 languages)
 stackvox voices                     # list all voice ids
+echo "from a pipe" | stackvox       # piped stdin works for speak/say
+stackvox speak --file message.txt   # read a whole file
+```
+
+Bash completion:
+
+```bash
+eval "$(stackvox completion bash)"  # current shell
+# or persist:
+stackvox completion bash > ~/.stackvox-completion.bash
+echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
 Daemon mode (keeps the model resident so each subsequent call is instant):

{stackvox-0.2.1 → stackvox-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.2.1"
+version = "0.3.1"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,15 +45,16 @@ Issues = "https://github.com/StackOneHQ/stackvox/issues"
 [project.scripts]
 stackvox = "stackvox.cli:main"
 
-[tool.setuptools]
-script-files = ["bin/stackvox-say"]
-
 [tool.setuptools.packages.find]
 include = ["stackvox*"]
 
 [tool.setuptools.package-data]
-# Ship the PEP 561 marker so downstream type checkers trust our inline hints.
-stackvox = ["py.typed"]
+# Ship the PEP 561 marker so downstream type checkers trust our inline hints,
+# and the bash helper as package data — extracted onto PATH by
+# `stackvox install-helper`. (We deliberately don't use [tool.setuptools]
+# script-files = [...]: it's discouraged, has no PEP 621 equivalent, and
+# doesn't round-trip through hatchling/uv if we ever migrate build backends.)
+stackvox = ["py.typed", "data/stackvox-say"]
 
 [tool.ruff]
 line-length = 110

{stackvox-0.2.1 → stackvox-0.3.1}/stackvox/cli.py

@@ -21,7 +21,77 @@ def _configure_logging() -> None:
     )
 
 
-SUBCOMMANDS = {"serve", "stop", "status", "say", "speak", "voices", "welcome"}
+SUBCOMMANDS = {
+    "serve",
+    "stop",
+    "status",
+    "say",
+    "speak",
+    "voices",
+    "welcome",
+    "completion",
+    "install-helper",
+}
+
+DEFAULT_HELPER_PREFIX = Path.home() / ".local" / "bin"
+
+_BASH_COMPLETION = r"""# stackvox bash completion. Install with one of:
+#   eval "$(stackvox completion bash)"          # current shell
+#   stackvox completion bash > ~/.stackvox-completion.bash && \
+#     echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
+_stackvox_completion() {
+    local cur prev subcommand
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    subcommand="${COMP_WORDS[1]:-}"
+
+    if [[ ${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "speak say serve stop status voices welcome completion install-helper" -- "$cur") )
+        return 0
+    fi
+
+    case "$prev" in
+        --file|--out)
+            COMPREPLY=( $(compgen -f -- "$cur") )
+            return 0
+            ;;
+        --prefix)
+            COMPREPLY=( $(compgen -d -- "$cur") )
+            return 0
+            ;;
+        --speed)
+            COMPREPLY=( $(compgen -W "0.8 0.9 1.0 1.1 1.2 1.5" -- "$cur") )
+            return 0
+            ;;
+        --lang)
+            COMPREPLY=( $(compgen -W "en-us en-gb fr-fr it hi pt-br es ja zh" -- "$cur") )
+            return 0
+            ;;
+    esac
+
+    case "$subcommand" in
+        speak)
+            COMPREPLY=( $(compgen -W "--voice --speed --lang --file --out --help" -- "$cur") )
+            ;;
+        say)
+            COMPREPLY=( $(compgen -W "--voice --speed --lang --file --fallback-say --help" -- "$cur") )
+            ;;
+        serve)
+            COMPREPLY=( $(compgen -W "--voice --speed --lang --help" -- "$cur") )
+            ;;
+        completion)
+            COMPREPLY=( $(compgen -W "bash" -- "$cur") )
+            ;;
+        install-helper)
+            COMPREPLY=( $(compgen -W "--prefix --help" -- "$cur") )
+            ;;
+        *)
+            COMPREPLY=( $(compgen -W "--help" -- "$cur") )
+            ;;
+    esac
+}
+complete -F _stackvox_completion stackvox
+"""
 
 WELCOME_LINES = [
     ("bf_emma", "en-gb", "Welcome to stackvox."),
@@ -59,6 +129,20 @@ def _build_parser() -> argparse.ArgumentParser:
     sub.add_parser("voices", help="List available voices")
     sub.add_parser("welcome", help="Play a multilingual welcome message")
 
+    p_completion = sub.add_parser("completion", help="Print a shell completion script")
+    p_completion.add_argument("shell", choices=["bash"], help="Shell to generate completion for")
+
+    p_install_helper = sub.add_parser(
+        "install-helper",
+        help="Copy the stackvox-say bash helper onto PATH (default: ~/.local/bin)",
+    )
+    p_install_helper.add_argument(
+        "--prefix",
+        type=Path,
+        default=DEFAULT_HELPER_PREFIX,
+        help=f"Install directory (default: {DEFAULT_HELPER_PREFIX})",
+    )
+
     return parser
 
 
@@ -69,11 +153,20 @@ def _add_voice_args(parser: argparse.ArgumentParser) -> None:
 
 
 def _read_text(args: argparse.Namespace) -> str | None:
+    """Resolve the text to speak from --file, the positional, or piped stdin.
+
+    Precedence: --file > positional text > stdin (when piped, not a TTY).
+    """
     file: Path | None = getattr(args, "file", None)
     if file is not None:
         return file.read_text(encoding="utf-8")
     text: str | None = getattr(args, "text", None)
-    return text
+    if text is not None:
+        return text
+    if not sys.stdin.isatty():
+        piped = sys.stdin.read()
+        return piped if piped.strip() else None
+    return None
 
 
 def _cmd_speak(args: argparse.Namespace) -> int:
@@ -149,12 +242,60 @@ def _cmd_welcome(_: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_completion(args: argparse.Namespace) -> int:
+    if args.shell == "bash":
+        print(_BASH_COMPLETION)
+        return 0
+    # argparse `choices=` should prevent reaching here; defensive only.
+    print(f"unsupported shell: {args.shell}", file=sys.stderr)
+    return 1
+
+
+def _cmd_install_helper(args: argparse.Namespace) -> int:
+    """Copy the bundled `stackvox-say` bash helper onto PATH.
+
+    The helper is shipped as package data (`stackvox/data/stackvox-say`) rather
+    than installed automatically by setuptools — `script-files` is discouraged
+    and doesn't round-trip through modern build backends. This subcommand is
+    the explicit one-time install step.
+    """
+    import os
+    import shutil
+    import stat
+    from importlib.resources import as_file, files
+
+    prefix = Path(args.prefix).expanduser()
+    prefix.mkdir(parents=True, exist_ok=True)
+    dest = prefix / "stackvox-say"
+
+    src = files("stackvox").joinpath("data/stackvox-say")
+    with as_file(src) as src_path:
+        shutil.copy2(src_path, dest)
+
+    # Ensure executable bits regardless of how the wheel preserved them.
+    dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    print(f"Installed stackvox-say to {dest}", file=sys.stderr)
+
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    if str(prefix) not in path_dirs:
+        print(
+            f"Note: {prefix} is not on your PATH. Either add it to PATH or invoke "
+            f"the helper via its full path: {dest}",
+            file=sys.stderr,
+        )
+    return 0
+
+
 def main() -> int:
     _configure_logging()
     argv = sys.argv[1:]
     # Back-compat: `stackvox "text"` with no subcommand → speak.
+    # Same shortcut for piped stdin: `echo hi | stackvox` → speak.
     if argv and argv[0] not in SUBCOMMANDS and not argv[0].startswith("-"):
         argv = ["speak", *argv]
+    elif not argv and not sys.stdin.isatty():
+        argv = ["speak"]
 
     parser = _build_parser()
     args = parser.parse_args(argv)
@@ -171,6 +312,8 @@ def main() -> int:
         "status": _cmd_status,
         "voices": _cmd_voices,
         "welcome": _cmd_welcome,
+        "completion": _cmd_completion,
+        "install-helper": _cmd_install_helper,
     }
     return handlers[args.cmd](args)
 

{stackvox-0.2.1 → stackvox-0.3.1}/stackvox/daemon.py

@@ -13,6 +13,8 @@ Replies: "ok", "busy", "err: <msg>".
 
 from __future__ import annotations
 
+import ctypes
+import ctypes.util
 import json
 import logging
 import os
@@ -20,7 +22,9 @@ import queue
 import signal
 import socket
 import socketserver
+import sys
 import threading
+from typing import Any
 
 import sounddevice as sd
 
@@ -38,6 +42,18 @@ PING_TIMEOUT_SECONDS = 0.5
 RECV_BYTES = 1024
 
 
+# Set when PortAudio's cached default-output device is suspected stale and
+# needs Pa_Terminate / Pa_Initialize before the next playback. Initial state
+# is True so the first playback always refreshes; the macOS device watcher
+# re-sets it on real device changes; the worker also re-sets on playback
+# failure as a belt-and-suspenders retry path.
+_audio_dirty = threading.Event()
+_audio_dirty.set()
+
+# Holds CoreAudio callback references so they aren't garbage collected.
+_ca_refs: list[Any] = []
+
+
 def _refresh_audio_devices() -> None:
     """Reset PortAudio so the next play picks up the current system default.
 
@@ -45,7 +61,7 @@ def _refresh_audio_devices() -> None:
     daemon keeps playing to whatever was default when it started (e.g. the
     built-in speakers after the user swapped to Bluetooth). Terminating and
     re-initialising is the only portable way to refresh that cache. Costs
-    ~10-50ms per call, which is invisible next to synthesis time.
+    ~10-50ms per call.
     """
     try:
         sd._terminate()
@@ -54,6 +70,94 @@ def _refresh_audio_devices() -> None:
         logger.exception("failed to refresh audio devices")
 
 
+def _start_device_watcher() -> None:
+    """macOS only: mark `_audio_dirty` when the default output device changes.
+
+    Avoids reinitialising PortAudio on every playback (the simpler approach,
+    which adds 10-50ms of latency before each speech). macOS notifies the
+    property listener on more than just real device changes — playback start,
+    volume changes, and other side effects all fire it — so we compare the
+    current default-output device ID against the last seen one and only mark
+    dirty on actual changes.
+
+    No-ops on non-macOS; the dirty flag stays at its initial state (set), so
+    the first playback refreshes once and subsequent playbacks reuse the
+    PortAudio context. Device changes on those platforms are handled by the
+    worker's failure-retry path.
+    """
+    if sys.platform != "darwin":
+        return
+    try:
+        ca = ctypes.CDLL(ctypes.util.find_library("CoreAudio") or "")
+        cf = ctypes.CDLL(ctypes.util.find_library("CoreFoundation") or "")
+    except Exception:
+        logger.debug("CoreAudio unavailable; device watcher disabled")
+        return
+
+    class _PropAddr(ctypes.Structure):
+        _fields_ = [
+            ("mSelector", ctypes.c_uint32),
+            ("mScope", ctypes.c_uint32),
+            ("mElement", ctypes.c_uint32),
+        ]
+
+    _ListenerProc = ctypes.CFUNCTYPE(
+        ctypes.c_int32,
+        ctypes.c_uint32,  # inObjectID
+        ctypes.c_uint32,  # inNumberAddresses
+        ctypes.POINTER(_PropAddr),
+        ctypes.c_void_p,
+    )
+
+    prop = _PropAddr(
+        0x644F7574,  # kAudioHardwarePropertyDefaultOutputDevice  'dOut'
+        0x676C6F62,  # kAudioObjectPropertyScopeGlobal             'glob'
+        0,  # kAudioObjectPropertyElementMain
+    )
+
+    def _read_default_device() -> int:
+        device = ctypes.c_uint32(0)
+        size = ctypes.c_uint32(ctypes.sizeof(device))
+        status = ca.AudioObjectGetPropertyData(
+            1,  # kAudioObjectSystemObject
+            ctypes.byref(prop),
+            0,
+            None,
+            ctypes.byref(size),
+            ctypes.byref(device),
+        )
+        return device.value if status == 0 else 0
+
+    last_device = [_read_default_device()]
+
+    def _on_device_change(obj_id: int, n: int, addrs, data) -> int:
+        try:
+            current = _read_default_device()
+            if current and current != last_device[0]:
+                last_device[0] = current
+                _audio_dirty.set()
+        except Exception:
+            logger.debug("device-change callback error", exc_info=True)
+        return 0
+
+    cb = _ListenerProc(_on_device_change)
+    _ca_refs.append(cb)  # prevent GC
+    status = ca.AudioObjectAddPropertyListener(1, ctypes.byref(prop), cb, None)
+    if status != 0:
+        # If registration silently fails the watcher would never fire and
+        # device switches would only recover via the worker's failure-retry
+        # path. Surface it so the failure mode is observable.
+        logger.warning("AudioObjectAddPropertyListener failed (status=%d); device watcher inactive", status)
+        return
+
+    threading.Thread(
+        target=cf.CFRunLoopRun,
+        daemon=True,
+        name="audio-device-watcher",
+    ).start()
+    logger.debug("audio device watcher started")
+
+
 class _DaemonState:
     def __init__(self, voice: str, speed: float, lang: str) -> None:
         self.tts = Stackvox(voice=voice, speed=speed, lang=lang)
@@ -61,6 +165,7 @@ class _DaemonState:
         self.stop_event = threading.Event()
         self.worker = threading.Thread(target=self._worker, daemon=True)
         self.worker.start()
+        _start_device_watcher()
 
     def _worker(self) -> None:
         while not self.stop_event.is_set():
@@ -68,7 +173,9 @@ class _DaemonState:
                 req = self.queue.get(timeout=WORKER_POLL_SECONDS)
             except queue.Empty:
                 continue
-            _refresh_audio_devices()
+            if _audio_dirty.is_set():
+                _refresh_audio_devices()
+                _audio_dirty.clear()
             try:
                 self.tts.speak(
                     req["text"],
@@ -78,6 +185,9 @@ class _DaemonState:
                 )
             except Exception:
                 logger.exception("playback error")
+                # Failed playback might be a stale audio context; mark dirty
+                # so the next request refreshes before trying again.
+                _audio_dirty.set()
 
     def submit(self, req: dict) -> bool:
         try:

{stackvox-0.2.1 → stackvox-0.3.1}/stackvox/engine.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import logging
+import sys
+import threading
 import urllib.request
 from pathlib import Path
 
@@ -22,6 +24,40 @@ _MODEL_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/mode
 _VOICES_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin"
 
 
+def _download_with_progress(url: str, dest: Path) -> None:
+    """Stream a URL to a file, printing percentage updates to stderr.
+
+    The ~340 MB Kokoro model takes long enough on first run that a silent
+    download looks like a hang; this gives users feedback without pulling
+    in tqdm. Falls back to a single line when the server doesn't report
+    Content-Length.
+    """
+    last_pct = -1
+    label = dest.name
+
+    def hook(blocks: int, blocksize: int, totalsize: int) -> None:
+        nonlocal last_pct
+        if totalsize <= 0:
+            return
+        pct = min(100, int(blocks * blocksize * 100 / totalsize))
+        if pct != last_pct:
+            mb_total = totalsize / 1_000_000
+            print(
+                f"\r[stackvox] downloading {label} {pct:3d}% ({mb_total:.0f} MB)",
+                end="",
+                file=sys.stderr,
+                flush=True,
+            )
+            last_pct = pct
+
+    urllib.request.urlretrieve(url, dest, reporthook=hook)
+    if last_pct >= 0 and sys.stderr.isatty():
+        # Finish the carriage-returned line so subsequent output starts on
+        # its own line. On non-TTY (e.g. CI logs) stderr is line-buffered
+        # and the \r writes already land on separate lines.
+        print("", file=sys.stderr, flush=True)
+
+
 def _ensure_models(cache_dir: Path) -> tuple[Path, Path]:
     cache_dir.mkdir(parents=True, exist_ok=True)
     model_path = cache_dir / "kokoro-v1.0.onnx"
@@ -29,8 +65,7 @@ def _ensure_models(cache_dir: Path) -> tuple[Path, Path]:
     for path, url in [(model_path, _MODEL_URL), (voices_path, _VOICES_URL)]:
         if path.exists():
             continue
-        logger.info("downloading %s...", path.name)
-        urllib.request.urlretrieve(url, path)
+        _download_with_progress(url, path)
     return model_path, voices_path
 
 
@@ -134,12 +169,22 @@ class Stackvox:
 
 
 _default: Stackvox | None = None
+_default_lock = threading.Lock()
 
 
 def _get_default() -> Stackvox:
+    """Lazily build a module-level engine, safe under concurrent first calls.
+
+    Without the lock, two threads racing to call speak() / synthesize() at
+    process start could each instantiate Stackvox — meaning two 340 MB model
+    loads. Double-checked locking keeps the fast path lock-free once
+    initialised.
+    """
     global _default
     if _default is None:
-        _default = Stackvox()
+        with _default_lock:
+            if _default is None:
+                _default = Stackvox()
     return _default
 
 

{stackvox-0.2.1 → stackvox-0.3.1/stackvox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.2.1
+Version: 0.3.1
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -45,11 +45,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash
@@ -74,6 +83,17 @@ stackvox speak "Hi" --voice bf_emma # same, explicit subcommand
 stackvox speak "save" --out a.wav   # write wav instead of playing
 stackvox welcome                    # multilingual welcome (6 languages)
 stackvox voices                     # list all voice ids
+echo "from a pipe" | stackvox       # piped stdin works for speak/say
+stackvox speak --file message.txt   # read a whole file
+```
+
+Bash completion:
+
+```bash
+eval "$(stackvox completion bash)"  # current shell
+# or persist:
+stackvox completion bash > ~/.stackvox-completion.bash
+echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
 Daemon mode (keeps the model resident so each subsequent call is instant):

{stackvox-0.2.1 → stackvox-0.3.1}/stackvox.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 NOTICE
 README.md
 pyproject.toml
-bin/stackvox-say
 stackvox/__init__.py
 stackvox/__main__.py
 stackvox/cli.py
@@ -16,6 +15,9 @@ stackvox.egg-info/dependency_links.txt
 stackvox.egg-info/entry_points.txt
 stackvox.egg-info/requires.txt
 stackvox.egg-info/top_level.txt
+stackvox/data/stackvox-say
 tests/test_cli.py
+tests/test_daemon.py
 tests/test_daemon_protocol.py
+tests/test_engine.py
 tests/test_paths.py