stackvox 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.0
+Version: 0.4.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Dist: kokoro-onnx>=0.4.0
 Requires-Dist: soundfile>=0.12.1
 Requires-Dist: sounddevice>=0.4.6
 Requires-Dist: numpy>=1.24
+Requires-Dist: tomli>=2.0; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
@@ -40,16 +41,27 @@ Dynamic: license-file
 
 Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx). Apache 2.0 model, ~340MB, CPU real-time, plays straight to system audio. Designed to be importable as a Python library, drivable as a CLI, or poked via a unix socket for ~13ms speech requests from shell scripts.
 
+🔊 **Hear it:** [docs/demo.wav](./docs/demo.wav) — five seconds of two voices speaking the tagline (`af_heart` then `bf_emma`).
+
 ## Install
 
 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
@@ -87,7 +99,22 @@ stackvox completion bash > ~/.stackvox-completion.bash
 echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
-Daemon mode (keeps the model resident so each subsequent call is instant):
+## Configuration
+
+stackvox reads per-user defaults from a TOML file, so you don't need to repeat `--voice bf_emma --speed 1.1` on every invocation. Set values in `~/.config/stackvox/config.toml` (or `$XDG_CONFIG_HOME/stackvox/config.toml`, or wherever `STACKVOX_CONFIG` points):
+
+```toml
+[defaults]
+voice = "bf_emma"
+speed = 1.1
+lang = "en-gb"
+```
+
+CLI flags always win over config values, and config values always win over the built-in defaults. A missing file is fine — built-ins apply. A malformed file logs a warning and is ignored.
+
+## Daemon mode
+
+Keeps the model resident so each subsequent call is instant:
 
 ```bash
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
@@ -202,6 +229,23 @@ Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [
 
 Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
 
+## How does this compare to other TTS?
+
+stackvox is a fairly opinionated narrow slice of the TTS space. Here's where it sits next to the obvious neighbours:
+
+| Tool | Offline? | Quality | Latency (typical) | License | Best for |
+|---|---|---|---|---|---|
+| **stackvox** (Kokoro-82M) | ✅ | High (24kHz, 50+ voices, 9 languages) | ~300ms in-process · ~13ms via daemon helper | Apache 2.0 | Local apps, shell hooks, anything that wants natural voice without the cloud |
+| macOS `say` | ✅ | OK | ~50ms | macOS only | macOS-only scripts, "good enough" voice |
+| `espeak-ng` | ✅ | Robotic | ~10ms | GPL-3.0 | Accessibility, screen readers, embedded |
+| [Piper](https://github.com/rhasspy/piper) | ✅ | High | ~100ms | MIT | Similar use-case to stackvox; ONNX-based, more voices in some languages |
+| [Coqui TTS](https://github.com/coqui-ai/TTS) | ✅ | Very high (research models) | seconds | MPL-2.0 | Research, fine-tuning, voice cloning |
+| OpenAI / ElevenLabs / etc. | ❌ | Highest | network-bound | Proprietary | Production apps that can pay per-call and accept network dependency |
+
+Where stackvox tries to be different from Piper specifically: a **resident daemon + bash helper** path that gets you sub-15ms speech requests from shell scripts (CI hooks, terminal notifications, status announcements) without paying Python's startup cost on every call. That's basically the point — voice quality alone wouldn't be enough to switch off Piper, but the IPC story makes a difference for shell-driven workflows.
+
+Pick stackvox if you want **good voices, fully offline, with a fast shell-friendly API**.
+
 ## 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 → stackvox-0.4.0}/README.md

@@ -7,16 +7,27 @@
 
 Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx). Apache 2.0 model, ~340MB, CPU real-time, plays straight to system audio. Designed to be importable as a Python library, drivable as a CLI, or poked via a unix socket for ~13ms speech requests from shell scripts.
 
+🔊 **Hear it:** [docs/demo.wav](./docs/demo.wav) — five seconds of two voices speaking the tagline (`af_heart` then `bf_emma`).
+
 ## Install
 
 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
@@ -54,7 +65,22 @@ stackvox completion bash > ~/.stackvox-completion.bash
 echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
-Daemon mode (keeps the model resident so each subsequent call is instant):
+## Configuration
+
+stackvox reads per-user defaults from a TOML file, so you don't need to repeat `--voice bf_emma --speed 1.1` on every invocation. Set values in `~/.config/stackvox/config.toml` (or `$XDG_CONFIG_HOME/stackvox/config.toml`, or wherever `STACKVOX_CONFIG` points):
+
+```toml
+[defaults]
+voice = "bf_emma"
+speed = 1.1
+lang = "en-gb"
+```
+
+CLI flags always win over config values, and config values always win over the built-in defaults. A missing file is fine — built-ins apply. A malformed file logs a warning and is ignored.
+
+## Daemon mode
+
+Keeps the model resident so each subsequent call is instant:
 
 ```bash
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
@@ -169,6 +195,23 @@ Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [
 
 Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
 
+## How does this compare to other TTS?
+
+stackvox is a fairly opinionated narrow slice of the TTS space. Here's where it sits next to the obvious neighbours:
+
+| Tool | Offline? | Quality | Latency (typical) | License | Best for |
+|---|---|---|---|---|---|
+| **stackvox** (Kokoro-82M) | ✅ | High (24kHz, 50+ voices, 9 languages) | ~300ms in-process · ~13ms via daemon helper | Apache 2.0 | Local apps, shell hooks, anything that wants natural voice without the cloud |
+| macOS `say` | ✅ | OK | ~50ms | macOS only | macOS-only scripts, "good enough" voice |
+| `espeak-ng` | ✅ | Robotic | ~10ms | GPL-3.0 | Accessibility, screen readers, embedded |
+| [Piper](https://github.com/rhasspy/piper) | ✅ | High | ~100ms | MIT | Similar use-case to stackvox; ONNX-based, more voices in some languages |
+| [Coqui TTS](https://github.com/coqui-ai/TTS) | ✅ | Very high (research models) | seconds | MPL-2.0 | Research, fine-tuning, voice cloning |
+| OpenAI / ElevenLabs / etc. | ❌ | Highest | network-bound | Proprietary | Production apps that can pay per-call and accept network dependency |
+
+Where stackvox tries to be different from Piper specifically: a **resident daemon + bash helper** path that gets you sub-15ms speech requests from shell scripts (CI hooks, terminal notifications, status announcements) without paying Python's startup cost on every call. That's basically the point — voice quality alone wouldn't be enough to switch off Piper, but the IPC story makes a difference for shell-driven workflows.
+
+Pick stackvox if you want **good voices, fully offline, with a fast shell-friendly API**.
+
 ## 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 → stackvox-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.3.0"
+version = "0.4.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ dependencies = [
     "soundfile>=0.12.1",
     "sounddevice>=0.4.6",
     "numpy>=1.24",
+    "tomli>=2.0;python_version<'3.11'",
 ]
 
 [project.optional-dependencies]
@@ -45,15 +46,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
@@ -105,15 +107,18 @@ warn_redundant_casts = true
 warn_return_any = true
 check_untyped_defs = true
 no_implicit_optional = true
+disallow_untyped_defs = true
 
 [[tool.mypy.overrides]]
-# Third-party deps without inline type stubs.
-module = ["kokoro_onnx", "sounddevice", "soundfile"]
+# Third-party deps without inline type stubs (or, for `tomli`, a 3.10-only
+# fallback that's not installed on the typechecker's Python).
+module = ["kokoro_onnx", "sounddevice", "soundfile", "tomli"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-# Tests use pytest-mock's mocker.patch which returns Any-heavy values; don't
-# require full strictness there.
+# Tests rely on pytest-mock's `mocker` (Any-heavy) and pytest fixtures with
+# implicit Any-typed kwargs. Strict untyped-def bans buy little here, so
+# tests stay on the looser config.
 module = "tests.*"
 disallow_untyped_defs = false
 

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

@@ -9,8 +9,8 @@ from pathlib import Path
 
 import soundfile as sf
 
-from stackvox import daemon
-from stackvox.engine import DEFAULT_LANG, DEFAULT_SPEED, DEFAULT_VOICE, Stackvox
+from stackvox import config, daemon
+from stackvox.engine import Stackvox
 
 
 def _configure_logging() -> None:
@@ -21,7 +21,19 @@ def _configure_logging() -> None:
     )
 
 
-SUBCOMMANDS = {"serve", "stop", "status", "say", "speak", "voices", "welcome", "completion"}
+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
@@ -34,7 +46,7 @@ _stackvox_completion() {
     subcommand="${COMP_WORDS[1]:-}"
 
     if [[ ${COMP_CWORD} -eq 1 ]]; then
-        COMPREPLY=( $(compgen -W "speak say serve stop status voices welcome completion" -- "$cur") )
+        COMPREPLY=( $(compgen -W "speak say serve stop status voices welcome completion install-helper" -- "$cur") )
         return 0
     fi
 
@@ -43,6 +55,10 @@ _stackvox_completion() {
             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
@@ -66,6 +82,9 @@ _stackvox_completion() {
         completion)
             COMPREPLY=( $(compgen -W "bash" -- "$cur") )
             ;;
+        install-helper)
+            COMPREPLY=( $(compgen -W "--prefix --help" -- "$cur") )
+            ;;
         *)
             COMPREPLY=( $(compgen -W "--help" -- "$cur") )
             ;;
@@ -84,18 +103,20 @@ WELCOME_LINES = [
 ]
 
 
-def _build_parser() -> argparse.ArgumentParser:
+def _build_parser(defaults: config.Defaults | None = None) -> argparse.ArgumentParser:
+    if defaults is None:
+        defaults = config.Defaults()
     parser = argparse.ArgumentParser(prog="stackvox", description="Kokoro-82M TTS")
     sub = parser.add_subparsers(dest="cmd")
 
     p_speak = sub.add_parser("speak", help="Synthesize and play in-process (loads model each run)")
-    _add_voice_args(p_speak)
+    _add_voice_args(p_speak, defaults)
     p_speak.add_argument("text", nargs="?")
     p_speak.add_argument("--file", type=Path)
     p_speak.add_argument("--out", type=Path, help="Write wav instead of playing")
 
     p_say = sub.add_parser("say", help="Send text to daemon (fast; fails if daemon not running)")
-    _add_voice_args(p_say)
+    _add_voice_args(p_say, defaults)
     p_say.add_argument("text", nargs="?")
     p_say.add_argument("--file", type=Path)
     p_say.add_argument(
@@ -103,7 +124,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
 
     p_serve = sub.add_parser("serve", help="Run the daemon in the foreground")
-    _add_voice_args(p_serve)
+    _add_voice_args(p_serve, defaults)
 
     sub.add_parser("stop", help="Stop the running daemon")
     sub.add_parser("status", help="Print daemon status")
@@ -113,13 +134,24 @@ def _build_parser() -> argparse.ArgumentParser:
     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
 
 
-def _add_voice_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--voice", default=DEFAULT_VOICE)
-    parser.add_argument("--speed", type=float, default=DEFAULT_SPEED)
-    parser.add_argument("--lang", default=DEFAULT_LANG)
+def _add_voice_args(parser: argparse.ArgumentParser, defaults: config.Defaults) -> None:
+    parser.add_argument("--voice", default=defaults.voice)
+    parser.add_argument("--speed", type=float, default=defaults.speed)
+    parser.add_argument("--lang", default=defaults.lang)
 
 
 def _read_text(args: argparse.Namespace) -> str | None:
@@ -221,6 +253,42 @@ def _cmd_completion(args: argparse.Namespace) -> int:
     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:]
@@ -231,7 +299,7 @@ def main() -> int:
     elif not argv and not sys.stdin.isatty():
         argv = ["speak"]
 
-    parser = _build_parser()
+    parser = _build_parser(config.load_defaults())
     args = parser.parse_args(argv)
 
     if not args.cmd:
@@ -247,6 +315,7 @@ def main() -> int:
         "voices": _cmd_voices,
         "welcome": _cmd_welcome,
         "completion": _cmd_completion,
+        "install-helper": _cmd_install_helper,
     }
     return handlers[args.cmd](args)
 

stackvox-0.4.0/stackvox/config.py

@@ -0,0 +1,80 @@
+"""User config file: per-user defaults for voice / speed / lang.
+
+Lives at `$XDG_CONFIG_HOME/stackvox/config.toml` (falling back to
+`~/.config/stackvox/config.toml`), or wherever `STACKVOX_CONFIG` points if set.
+A missing file is fine — defaults from `stackvox.engine` apply. A malformed
+file logs a warning and is otherwise ignored.
+
+File format::
+
+    [defaults]
+    voice = "bf_emma"
+    speed = 1.1
+    lang = "en-gb"
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - covered by 3.10 CI
+    import tomli as tomllib
+
+from stackvox.engine import DEFAULT_LANG, DEFAULT_SPEED, DEFAULT_VOICE
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Defaults:
+    """Resolved default values for synthesis parameters."""
+
+    voice: str = DEFAULT_VOICE
+    speed: float = DEFAULT_SPEED
+    lang: str = DEFAULT_LANG
+
+
+def config_path() -> Path:
+    """Resolve where the config file lives.
+
+    Honours `STACKVOX_CONFIG` first; otherwise XDG (`$XDG_CONFIG_HOME` →
+    `~/.config`).
+    """
+    override = os.environ.get("STACKVOX_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "stackvox" / "config.toml"
+
+
+def load_defaults(path: Path | None = None) -> Defaults:
+    """Read the config file and return resolved defaults.
+
+    Missing file → built-in defaults. Malformed file → warning logged,
+    built-in defaults used. Per-key fallback so a config that only sets
+    `voice` keeps the built-in `speed` and `lang`.
+    """
+    p = path or config_path()
+    if not p.is_file():
+        return Defaults()
+    try:
+        data = tomllib.loads(p.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        logger.warning("ignoring malformed stackvox config at %s: %s", p, exc)
+        return Defaults()
+    section = data.get("defaults", {})
+    if not isinstance(section, dict):
+        logger.warning("config %s: [defaults] must be a table; ignoring", p)
+        return Defaults()
+    return Defaults(
+        voice=str(section.get("voice", DEFAULT_VOICE)),
+        speed=float(section.get("speed", DEFAULT_SPEED)),
+        lang=str(section.get("lang", DEFAULT_LANG)),
+    )

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

@@ -130,7 +130,10 @@ def _start_device_watcher() -> None:
 
     last_device = [_read_default_device()]
 
-    def _on_device_change(obj_id: int, n: int, addrs, data) -> int:
+    def _on_device_change(obj_id: int, n: int, addrs: Any, data: Any) -> int:
+        # `addrs` is a ctypes.POINTER(_PropAddr); `data` is a c_void_p — neither
+        # is needed because we already know which property fired (only one is
+        # registered) and we re-read the device ID directly.
         try:
             current = _read_default_device()
             if current and current != last_device[0]:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.0
+Version: 0.4.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Dist: kokoro-onnx>=0.4.0
 Requires-Dist: soundfile>=0.12.1
 Requires-Dist: sounddevice>=0.4.6
 Requires-Dist: numpy>=1.24
+Requires-Dist: tomli>=2.0; python_version < "3.11"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
@@ -40,16 +41,27 @@ Dynamic: license-file
 
 Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx). Apache 2.0 model, ~340MB, CPU real-time, plays straight to system audio. Designed to be importable as a Python library, drivable as a CLI, or poked via a unix socket for ~13ms speech requests from shell scripts.
 
+🔊 **Hear it:** [docs/demo.wav](./docs/demo.wav) — five seconds of two voices speaking the tagline (`af_heart` then `bf_emma`).
+
 ## Install
 
 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
@@ -87,7 +99,22 @@ stackvox completion bash > ~/.stackvox-completion.bash
 echo 'source ~/.stackvox-completion.bash' >> ~/.bashrc
 ```
 
-Daemon mode (keeps the model resident so each subsequent call is instant):
+## Configuration
+
+stackvox reads per-user defaults from a TOML file, so you don't need to repeat `--voice bf_emma --speed 1.1` on every invocation. Set values in `~/.config/stackvox/config.toml` (or `$XDG_CONFIG_HOME/stackvox/config.toml`, or wherever `STACKVOX_CONFIG` points):
+
+```toml
+[defaults]
+voice = "bf_emma"
+speed = 1.1
+lang = "en-gb"
+```
+
+CLI flags always win over config values, and config values always win over the built-in defaults. A missing file is fine — built-ins apply. A malformed file logs a warning and is ignored.
+
+## Daemon mode
+
+Keeps the model resident so each subsequent call is instant:
 
 ```bash
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
@@ -202,6 +229,23 @@ Model weights (`kokoro-v1.0.onnx`, ~340 MB) and voices are downloaded from the [
 
 Security issues themselves should not be filed as public GitHub issues — see [`SECURITY.md`](./SECURITY.md) for the disclosure process.
 
+## How does this compare to other TTS?
+
+stackvox is a fairly opinionated narrow slice of the TTS space. Here's where it sits next to the obvious neighbours:
+
+| Tool | Offline? | Quality | Latency (typical) | License | Best for |
+|---|---|---|---|---|---|
+| **stackvox** (Kokoro-82M) | ✅ | High (24kHz, 50+ voices, 9 languages) | ~300ms in-process · ~13ms via daemon helper | Apache 2.0 | Local apps, shell hooks, anything that wants natural voice without the cloud |
+| macOS `say` | ✅ | OK | ~50ms | macOS only | macOS-only scripts, "good enough" voice |
+| `espeak-ng` | ✅ | Robotic | ~10ms | GPL-3.0 | Accessibility, screen readers, embedded |
+| [Piper](https://github.com/rhasspy/piper) | ✅ | High | ~100ms | MIT | Similar use-case to stackvox; ONNX-based, more voices in some languages |
+| [Coqui TTS](https://github.com/coqui-ai/TTS) | ✅ | Very high (research models) | seconds | MPL-2.0 | Research, fine-tuning, voice cloning |
+| OpenAI / ElevenLabs / etc. | ❌ | Highest | network-bound | Proprietary | Production apps that can pay per-call and accept network dependency |
+
+Where stackvox tries to be different from Piper specifically: a **resident daemon + bash helper** path that gets you sub-15ms speech requests from shell scripts (CI hooks, terminal notifications, status announcements) without paying Python's startup cost on every call. That's basically the point — voice quality alone wouldn't be enough to switch off Piper, but the IPC story makes a difference for shell-driven workflows.
+
+Pick stackvox if you want **good voices, fully offline, with a fast shell-friendly API**.
+
 ## 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 → stackvox-0.4.0}/stackvox.egg-info/SOURCES.txt

@@ -2,10 +2,10 @@ LICENSE
 NOTICE
 README.md
 pyproject.toml
-bin/stackvox-say
 stackvox/__init__.py
 stackvox/__main__.py
 stackvox/cli.py
+stackvox/config.py
 stackvox/daemon.py
 stackvox/engine.py
 stackvox/paths.py
@@ -16,6 +16,10 @@ 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_config.py
+tests/test_daemon.py
 tests/test_daemon_protocol.py
+tests/test_engine.py
 tests/test_paths.py

{stackvox-0.3.0 → stackvox-0.4.0}/stackvox.egg-info/requires.txt

@@ -3,6 +3,9 @@ soundfile>=0.12.1
 sounddevice>=0.4.6
 numpy>=1.24
 
+[:python_version < "3.11"]
+tomli>=2.0
+
 [dev]
 pytest>=8.0
 pytest-mock>=3.12