stackvox 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.1
+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,6 +41,8 @@ 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:
@@ -96,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
@@ -211,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.1 → stackvox-0.4.0}/README.md

@@ -7,6 +7,8 @@
 
 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:
@@ -63,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
@@ -178,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.1 → stackvox-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.3.1"
+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]
@@ -106,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.1 → 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:
@@ -103,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(
@@ -122,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")
@@ -146,10 +148,10 @@ def _build_parser() -> argparse.ArgumentParser:
     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:
@@ -297,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:

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.1 → 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.1 → stackvox-0.4.0/stackvox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.1
+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,6 +41,8 @@ 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:
@@ -96,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
@@ -211,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.1 → stackvox-0.4.0}/stackvox.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 stackvox/__init__.py
 stackvox/__main__.py
 stackvox/cli.py
+stackvox/config.py
 stackvox/daemon.py
 stackvox/engine.py
 stackvox/paths.py
@@ -17,6 +18,7 @@ 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

{stackvox-0.3.1 → 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

stackvox-0.4.0/tests/test_config.py

@@ -0,0 +1,110 @@
+"""Config loader tests — pure file/env logic, no engine touched."""
+
+from __future__ import annotations
+
+import logging
+
+from stackvox import config
+from stackvox.engine import DEFAULT_LANG, DEFAULT_SPEED, DEFAULT_VOICE
+
+
+class TestConfigPath:
+    def test_stackvox_config_env_takes_priority(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("STACKVOX_CONFIG", str(tmp_path / "elsewhere.toml"))
+        assert config.config_path() == tmp_path / "elsewhere.toml"
+
+    def test_xdg_config_home_when_set(self, monkeypatch, tmp_path):
+        monkeypatch.delenv("STACKVOX_CONFIG", raising=False)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+        assert config.config_path() == tmp_path / "xdg" / "stackvox" / "config.toml"
+
+    def test_falls_back_to_home_dotconfig(self, monkeypatch):
+        monkeypatch.delenv("STACKVOX_CONFIG", raising=False)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+        from pathlib import Path
+
+        assert config.config_path() == Path.home() / ".config" / "stackvox" / "config.toml"
+
+
+class TestLoadDefaults:
+    def test_missing_file_returns_built_in_defaults(self, tmp_path):
+        actual = config.load_defaults(tmp_path / "absent.toml")
+        assert actual == config.Defaults()
+        assert actual.voice == DEFAULT_VOICE
+        assert actual.speed == DEFAULT_SPEED
+        assert actual.lang == DEFAULT_LANG
+
+    def test_full_config_overrides_all_three(self, tmp_path):
+        path = tmp_path / "config.toml"
+        path.write_text('[defaults]\nvoice = "bf_emma"\nspeed = 1.25\nlang = "en-gb"\n', encoding="utf-8")
+        actual = config.load_defaults(path)
+        assert actual.voice == "bf_emma"
+        assert actual.speed == 1.25
+        assert actual.lang == "en-gb"
+
+    def test_partial_config_keeps_built_in_for_missing_keys(self, tmp_path):
+        path = tmp_path / "config.toml"
+        path.write_text('[defaults]\nvoice = "bf_emma"\n', encoding="utf-8")
+        actual = config.load_defaults(path)
+        assert actual.voice == "bf_emma"
+        # speed and lang come from the engine defaults.
+        assert actual.speed == DEFAULT_SPEED
+        assert actual.lang == DEFAULT_LANG
+
+    def test_empty_file_returns_built_in_defaults(self, tmp_path):
+        path = tmp_path / "config.toml"
+        path.write_text("", encoding="utf-8")
+        assert config.load_defaults(path) == config.Defaults()
+
+    def test_malformed_toml_logs_warning_and_returns_defaults(self, tmp_path, caplog):
+        path = tmp_path / "config.toml"
+        path.write_text("this is not valid = toml\n[defaults\nvoice =", encoding="utf-8")
+        with caplog.at_level(logging.WARNING, logger="stackvox.config"):
+            actual = config.load_defaults(path)
+        assert actual == config.Defaults()
+        assert any("malformed stackvox config" in r.message for r in caplog.records)
+
+    def test_defaults_section_must_be_a_table(self, tmp_path, caplog):
+        """`defaults = "string"` is parseable TOML but the wrong shape — log and ignore."""
+        path = tmp_path / "config.toml"
+        path.write_text('defaults = "not-a-table"\n', encoding="utf-8")
+        with caplog.at_level(logging.WARNING, logger="stackvox.config"):
+            actual = config.load_defaults(path)
+        assert actual == config.Defaults()
+        assert any("must be a table" in r.message for r in caplog.records)
+
+
+class TestCLIPicksUpConfig:
+    """Smoke test: argparse defaults reflect the user's config file."""
+
+    def test_voice_default_comes_from_config(self, mocker, monkeypatch, tmp_path):
+        path = tmp_path / "config.toml"
+        path.write_text('[defaults]\nvoice = "bf_emma"\nspeed = 1.3\n', encoding="utf-8")
+        monkeypatch.setenv("STACKVOX_CONFIG", str(path))
+
+        from stackvox import cli
+
+        speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+        mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "hello"])
+        mocker.patch.object(cli.sys.stdin, "isatty", return_value=True)
+
+        assert cli.main() == 0
+        args = speak.call_args.args[0]
+        assert args.voice == "bf_emma"
+        assert args.speed == 1.3
+        # Lang wasn't in config; should fall through to built-in default.
+        assert args.lang == DEFAULT_LANG
+
+    def test_explicit_flag_overrides_config(self, mocker, monkeypatch, tmp_path):
+        path = tmp_path / "config.toml"
+        path.write_text('[defaults]\nvoice = "bf_emma"\n', encoding="utf-8")
+        monkeypatch.setenv("STACKVOX_CONFIG", str(path))
+
+        from stackvox import cli
+
+        speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+        mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "--voice", "af_sarah", "hello"])
+        mocker.patch.object(cli.sys.stdin, "isatty", return_value=True)
+
+        assert cli.main() == 0
+        assert speak.call_args.args[0].voice == "af_sarah"