stackvox 0.2.0__tar.gz → 0.3.0__tar.gz

{stackvox-0.2.0/stackvox.egg-info → stackvox-0.3.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.2.0
+Version: 0.3.0
 Summary: Offline TTS library using Kokoro-82M
-Author-email: "StackOne Technologies Ltd." <engineering@stackone.com>
+Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/StackOneHQ/stackvox
 Project-URL: Repository, https://github.com/StackOneHQ/stackvox
@@ -42,19 +42,26 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 
 ## Install
 
-Recommended — install globally with pipx so `stackvox` and `stackvox-say` end up on PATH:
+From PyPI — recommended for most users:
 
 ```bash
-pipx install git+https://github.com/StackOneHQ/stackvox.git
+pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+# or
+pip install stackvox     # use as a library
 ```
 
-Upgrade later with `pipx install --force git+https://github.com/StackOneHQ/stackvox.git` (pipx's `upgrade` doesn't always detect new commits on git installs).
+From git, if you want an unreleased commit:
+
+```bash
+pipx install git+https://github.com/StackOneHQ/stackvox.git
+# upgrade later with: pipx install --force git+https://github.com/StackOneHQ/stackvox.git
+```
 
 Dev install from a clone:
 
 ```bash
 python3 -m venv .venv && source .venv/bin/activate
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 Model + voice files auto-download to `~/.cache/stackvox/` on first use. Override with `STACKVOX_CACHE_DIR`.
@@ -67,6 +74,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):
@@ -174,6 +192,16 @@ Before each utterance the daemon resets PortAudio so it picks up the current sys
 - macOS or Linux
 - `nc` (BSD netcat — default on macOS, `netcat-openbsd` on Linux) for the bash helper
 
+## Security considerations
+
+stackvox doesn't open any network port. The daemon binds a unix socket under `~/.cache/stackvox/` (default file-mode `0600`, i.e. user-only per the OS defaults for files in `$HOME`). Any process running as the same local user can send text to the daemon — there's no per-message authentication on the socket itself. That's the trust boundary: stackvox assumes anything running as your UID is allowed to speak on your behalf.
+
+If you're exposing stackvox through a different surface (HTTP server, shared system service, container), authentication and rate-limiting are your responsibility at that layer.
+
+Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) GitHub release assets on first use and cached under `~/.cache/stackvox/`. If you operate in a restricted environment, pre-seed that directory offline.
+
+Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
+
 ## License & attributions
 
 stackvox itself is licensed under the **Apache License, Version 2.0** — see [`LICENSE`](./LICENSE). Third-party attributions are collected in [`NOTICE`](./NOTICE); the summary below is informational.

{stackvox-0.2.0 → stackvox-0.3.0}/README.md

@@ -9,19 +9,26 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 
 ## Install
 
-Recommended — install globally with pipx so `stackvox` and `stackvox-say` end up on PATH:
+From PyPI — recommended for most users:
 
 ```bash
-pipx install git+https://github.com/StackOneHQ/stackvox.git
+pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+# or
+pip install stackvox     # use as a library
 ```
 
-Upgrade later with `pipx install --force git+https://github.com/StackOneHQ/stackvox.git` (pipx's `upgrade` doesn't always detect new commits on git installs).
+From git, if you want an unreleased commit:
+
+```bash
+pipx install git+https://github.com/StackOneHQ/stackvox.git
+# upgrade later with: pipx install --force git+https://github.com/StackOneHQ/stackvox.git
+```
 
 Dev install from a clone:
 
 ```bash
 python3 -m venv .venv && source .venv/bin/activate
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 Model + voice files auto-download to `~/.cache/stackvox/` on first use. Override with `STACKVOX_CACHE_DIR`.
@@ -34,6 +41,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):
@@ -141,6 +159,16 @@ Before each utterance the daemon resets PortAudio so it picks up the current sys
 - macOS or Linux
 - `nc` (BSD netcat — default on macOS, `netcat-openbsd` on Linux) for the bash helper
 
+## Security considerations
+
+stackvox doesn't open any network port. The daemon binds a unix socket under `~/.cache/stackvox/` (default file-mode `0600`, i.e. user-only per the OS defaults for files in `$HOME`). Any process running as the same local user can send text to the daemon — there's no per-message authentication on the socket itself. That's the trust boundary: stackvox assumes anything running as your UID is allowed to speak on your behalf.
+
+If you're exposing stackvox through a different surface (HTTP server, shared system service, container), authentication and rate-limiting are your responsibility at that layer.
+
+Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) GitHub release assets on first use and cached under `~/.cache/stackvox/`. If you operate in a restricted environment, pre-seed that directory offline.
+
+Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
+
 ## License & attributions
 
 stackvox itself is licensed under the **Apache License, Version 2.0** — see [`LICENSE`](./LICENSE). Third-party attributions are collected in [`NOTICE`](./NOTICE); the summary below is informational.

{stackvox-0.2.0 → stackvox-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.2.0"
+version = "0.3.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
-authors = [{ name = "StackOne Technologies Ltd.", email = "engineering@stackone.com" }]
+authors = [{ name = "StackOne Technologies Ltd.", email = "support@stackone.com" }]
 keywords = ["tts", "kokoro", "onnx", "offline", "speech"]
 classifiers = [
     "Operating System :: MacOS",

{stackvox-0.2.0 → stackvox-0.3.0}/stackvox/cli.py

@@ -21,7 +21,58 @@ def _configure_logging() -> None:
     )
 
 
-SUBCOMMANDS = {"serve", "stop", "status", "say", "speak", "voices", "welcome"}
+SUBCOMMANDS = {"serve", "stop", "status", "say", "speak", "voices", "welcome", "completion"}
+
+_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" -- "$cur") )
+        return 0
+    fi
+
+    case "$prev" in
+        --file|--out)
+            COMPREPLY=( $(compgen -f -- "$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") )
+            ;;
+        *)
+            COMPREPLY=( $(compgen -W "--help" -- "$cur") )
+            ;;
+    esac
+}
+complete -F _stackvox_completion stackvox
+"""
 
 WELCOME_LINES = [
     ("bf_emma", "en-gb", "Welcome to stackvox."),
@@ -59,6 +110,9 @@ 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")
+
     return parser
 
 
@@ -69,11 +123,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 +212,24 @@ 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 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 +246,7 @@ def main() -> int:
         "status": _cmd_status,
         "voices": _cmd_voices,
         "welcome": _cmd_welcome,
+        "completion": _cmd_completion,
     }
     return handlers[args.cmd](args)
 

{stackvox-0.2.0 → stackvox-0.3.0}/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.0 → stackvox-0.3.0}/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.0 → stackvox-0.3.0/stackvox.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.2.0
+Version: 0.3.0
 Summary: Offline TTS library using Kokoro-82M
-Author-email: "StackOne Technologies Ltd." <engineering@stackone.com>
+Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/StackOneHQ/stackvox
 Project-URL: Repository, https://github.com/StackOneHQ/stackvox
@@ -42,19 +42,26 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 
 ## Install
 
-Recommended — install globally with pipx so `stackvox` and `stackvox-say` end up on PATH:
+From PyPI — recommended for most users:
 
 ```bash
-pipx install git+https://github.com/StackOneHQ/stackvox.git
+pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+# or
+pip install stackvox     # use as a library
 ```
 
-Upgrade later with `pipx install --force git+https://github.com/StackOneHQ/stackvox.git` (pipx's `upgrade` doesn't always detect new commits on git installs).
+From git, if you want an unreleased commit:
+
+```bash
+pipx install git+https://github.com/StackOneHQ/stackvox.git
+# upgrade later with: pipx install --force git+https://github.com/StackOneHQ/stackvox.git
+```
 
 Dev install from a clone:
 
 ```bash
 python3 -m venv .venv && source .venv/bin/activate
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 Model + voice files auto-download to `~/.cache/stackvox/` on first use. Override with `STACKVOX_CACHE_DIR`.
@@ -67,6 +74,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):
@@ -174,6 +192,16 @@ Before each utterance the daemon resets PortAudio so it picks up the current sys
 - macOS or Linux
 - `nc` (BSD netcat — default on macOS, `netcat-openbsd` on Linux) for the bash helper
 
+## Security considerations
+
+stackvox doesn't open any network port. The daemon binds a unix socket under `~/.cache/stackvox/` (default file-mode `0600`, i.e. user-only per the OS defaults for files in `$HOME`). Any process running as the same local user can send text to the daemon — there's no per-message authentication on the socket itself. That's the trust boundary: stackvox assumes anything running as your UID is allowed to speak on your behalf.
+
+If you're exposing stackvox through a different surface (HTTP server, shared system service, container), authentication and rate-limiting are your responsibility at that layer.
+
+Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) GitHub release assets on first use and cached under `~/.cache/stackvox/`. If you operate in a restricted environment, pre-seed that directory offline.
+
+Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
+
 ## License & attributions
 
 stackvox itself is licensed under the **Apache License, Version 2.0** — see [`LICENSE`](./LICENSE). Third-party attributions are collected in [`NOTICE`](./NOTICE); the summary below is informational.

stackvox-0.3.0/tests/test_cli.py

@@ -0,0 +1,91 @@
+"""CLI argument parsing — no engine loaded, no audio played."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from stackvox import cli
+
+
+@pytest.fixture(autouse=True)
+def _stdin_is_a_tty(mocker):
+    """Default tests to a TTY stdin so the new piped-stdin shortcut is off.
+
+    Tests that exercise the piped path opt in by patching isatty to False
+    and providing a real stdin StringIO.
+    """
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=True)
+
+
+def test_bare_text_routes_to_speak(mocker):
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello world"])
+    assert cli.main() == 0
+    args = speak.call_args.args[0]
+    assert args.cmd == "speak"
+    assert args.text == "hello world"
+
+
+def test_speak_subcommand_parses_voice_and_speed(mocker):
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "--voice", "bf_emma", "--speed", "1.2", "hi"])
+    assert cli.main() == 0
+    args = speak.call_args.args[0]
+    assert args.voice == "bf_emma"
+    assert args.speed == pytest.approx(1.2)
+    assert args.text == "hi"
+
+
+def test_no_subcommand_prints_help(mocker, capsys):
+    mocker.patch.object(cli.sys, "argv", ["stackvox"])
+    assert cli.main() == 1
+    captured = capsys.readouterr()
+    assert "usage: stackvox" in captured.out
+
+
+def test_unknown_subcommand_treated_as_speak_text(mocker):
+    """`stackvox foo` is treated as `stackvox speak foo`, not an error."""
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello"])
+    cli.main()
+    assert speak.call_args.args[0].text == "hello"
+
+
+def test_piped_stdin_with_no_args_routes_to_speak(mocker):
+    """`echo hi | stackvox` should default to speak."""
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox"])
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
+    mocker.patch.object(cli.sys, "stdin", io.StringIO("hello from stdin\n"))
+    assert cli.main() == 0
+    assert speak.call_args.args[0].cmd == "speak"
+
+
+def test_read_text_prefers_file_then_positional_then_stdin(mocker, tmp_path):
+    """_read_text precedence: --file > positional > piped stdin."""
+    file_arg = tmp_path / "src.txt"
+    file_arg.write_text("from-file", encoding="utf-8")
+
+    # Both --file and positional present → file wins.
+    args = mocker.MagicMock(file=file_arg, text="from-positional")
+    assert cli._read_text(args) == "from-file"
+
+    # No --file, positional present → positional wins.
+    args = mocker.MagicMock(file=None, text="from-positional")
+    assert cli._read_text(args) == "from-positional"
+
+    # No --file, no positional, stdin piped → stdin wins.
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
+    mocker.patch.object(cli.sys, "stdin", io.StringIO("from-stdin"))
+    args = mocker.MagicMock(file=None, text=None)
+    assert cli._read_text(args) == "from-stdin"
+
+
+def test_completion_bash_emits_complete_script(mocker, capsys):
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "completion", "bash"])
+    assert cli.main() == 0
+    captured = capsys.readouterr()
+    assert "_stackvox_completion()" in captured.out
+    assert "complete -F _stackvox_completion stackvox" in captured.out

{stackvox-0.2.0 → stackvox-0.3.0}/tests/test_daemon_protocol.py

@@ -107,18 +107,42 @@ def test_full_queue_returns_busy(server: ServerHarness):
     assert reply in {"ok", "busy"}
 
 
-def test_worker_refreshes_audio_devices_before_each_play(server: ServerHarness):
-    """PortAudio is reset before every play so device switches are picked up."""
+def test_worker_refreshes_audio_only_when_dirty(server: ServerHarness):
+    """PortAudio is refreshed once per dirty cycle, not before every play.
+
+    Initial dirty state at startup → first playback refreshes. A second
+    playback with no device change → no extra refresh. Re-marking dirty
+    (simulating a default-output-device change) → next playback refreshes
+    again.
+    """
     import time
 
+    from stackvox import daemon
+
+    # Ensure a known starting state regardless of prior-test ordering: dirty
+    # so the first playback in this test refreshes once.
+    daemon._audio_dirty.set()
+
+    def wait_for_speak_count(target: int) -> None:
+        deadline = time.monotonic() + 1.0
+        while server.tts.speak.call_count < target and time.monotonic() < deadline:
+            time.sleep(0.01)
+
+    # First playback consumes the dirty flag.
     assert _roundtrip(server.sock, json.dumps({"text": "a"}) + "\n") == "ok"
+    wait_for_speak_count(1)
+    assert server.refresh.call_count == 1
+
+    # Second playback with no device change → no additional refresh.
     assert _roundtrip(server.sock, json.dumps({"text": "b"}) + "\n") == "ok"
+    wait_for_speak_count(2)
+    assert server.refresh.call_count == 1
 
-    deadline = time.monotonic() + 1.0
-    while server.tts.speak.call_count < 2 and time.monotonic() < deadline:
-        time.sleep(0.01)
+    # Simulate a real device change.
+    daemon._audio_dirty.set()
 
-    assert server.tts.speak.call_count == 2
+    assert _roundtrip(server.sock, json.dumps({"text": "c"}) + "\n") == "ok"
+    wait_for_speak_count(3)
     assert server.refresh.call_count == 2
 
 

stackvox-0.2.0/tests/test_cli.py

@@ -1,41 +0,0 @@
-"""CLI argument parsing — no engine loaded, no audio played."""
-
-from __future__ import annotations
-
-import pytest
-
-from stackvox import cli
-
-
-def test_bare_text_routes_to_speak(mocker):
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello world"])
-    assert cli.main() == 0
-    args = speak.call_args.args[0]
-    assert args.cmd == "speak"
-    assert args.text == "hello world"
-
-
-def test_speak_subcommand_parses_voice_and_speed(mocker):
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "--voice", "bf_emma", "--speed", "1.2", "hi"])
-    assert cli.main() == 0
-    args = speak.call_args.args[0]
-    assert args.voice == "bf_emma"
-    assert args.speed == pytest.approx(1.2)
-    assert args.text == "hi"
-
-
-def test_no_subcommand_prints_help(mocker, capsys):
-    mocker.patch.object(cli.sys, "argv", ["stackvox"])
-    assert cli.main() == 1
-    captured = capsys.readouterr()
-    assert "usage: stackvox" in captured.out
-
-
-def test_unknown_subcommand_treated_as_speak_text(mocker):
-    """`stackvox foo` is treated as `stackvox speak foo`, not an error."""
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello"])
-    cli.main()
-    assert speak.call_args.args[0].text == "hello"