stackvox 0.12.0__tar.gz → 0.14.0__tar.gz

{stackvox-0.12.0 → stackvox-0.14.0}/NOTICE

@@ -60,3 +60,28 @@ phonemizer-fork
   runtime. Downstream users who distribute a combined work that includes
   phonemizer-fork should review GPL-3.0 obligations for their own
   distribution.
+
+--------------------------------------------------------------------------------
+Optional MLX backend (`stackvox[mlx]`)
+--------------------------------------------------------------------------------
+
+The components below are used only when the optional MLX backend is installed
+and selected. stackvox does not download, bundle, modify, or redistribute any
+MLX model; the user supplies a local model directory, and that model's own
+license governs its use.
+
+mlx-audio
+  Copyright (c) 2024 Prince Canuma
+  Licensed under the MIT License
+  https://github.com/Blaizzy/mlx-audio
+
+mlx and mlx-lm
+  Copyright © 2023 Apple Inc.
+  Licensed under the MIT License
+  https://github.com/ml-explore/mlx
+  https://github.com/ml-explore/mlx-lm
+
+transformers
+  Copyright 2018- The Hugging Face team. All rights reserved.
+  Licensed under the Apache License, Version 2.0
+  https://github.com/huggingface/transformers

{stackvox-0.12.0/stackvox.egg-info → stackvox-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.12.0
+Version: 0.14.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -18,10 +18,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: kokoro-onnx>=0.4.0
+Requires-Dist: onnxruntime>=1.20.1
 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: mlx
+Requires-Dist: mlx-audio<0.5,>=0.4.5; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12; extra == "dev"
@@ -103,10 +106,12 @@ stackvox speak --normalize --file post.md       # normalize, then synthesize
 stackvox say   --normalize "**Shipped** 1,198.9 MPG"   # normalize, then send to daemon
 ```
 
-`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-abbreviations`, `--no-filenames`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
 
 **Dev-output handling** (on by default; `--no-dev-terms` to disable) covers two things espeak reads badly: acronyms it says as words (`CLI` → "C L I", `AWS`, `URI`, `IAM`, …) and file-line references, which it voices literally as "dot py colon". A `file.ext:line` ref is re-spoken lead-with-the-line: `engine.py:42` → "line 42 of engine py", `cli.py:100-118` → "lines 100 to 118 of cli py", `foo.ts:666:10` → "line 666, column 10 of foo ts". Times, ratios, and versions (`12:30`, `3:1`, `1.2.3`) are left alone.
 
+**Chat shorthand** (on by default; `--no-abbreviations` to disable) is expanded to the words it stands for, so a response that reads "lmk" is spoken as "let me know": `lmk`, `iirc`, `afaik`, `idk`, `tbh`, `imo`, `btw`, `fyi`, `asap`, `wrt`, `tl;dr`/`tldr`. Whole-word and case-insensitive. Shorthand that doubles as a real word or is already voiced correctly (`rn`, `eta`, `aka`) is deliberately left alone; a `--pronunciations` entry overrides any of these.
+
 Fenced code blocks are dropped by default. `--code-blocks placeholder` instead speaks a short stand-in so a skipped block doesn't sound disjointed (ChatGPT-style) — set the wording with `--code-placeholder` (e.g. `--code-blocks placeholder --code-placeholder "you can see the code in the chat history"`); consecutive blocks collapse to one.
 
 Bash completion:
@@ -129,7 +134,7 @@ 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.
+CLI flags always win over config values, and config values always win over the built-in defaults. The one thing between a flag and the config is a [voice mix](#voice-mixes)'s own `lang` and `speed`, so `--voice chip` stays transatlantic even when `[defaults]` sets `lang = "en-us"`. A missing file is fine — built-ins apply. A malformed file logs a warning and is ignored.
 
 ## Daemon mode
 
@@ -139,7 +144,7 @@ Keeps the model resident so each subsequent call is instant:
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
 stackvox status        # is the daemon up? also shows version + any pending PyPI update
 stackvox say "Hello"   # send text to the daemon (fails if not running)
-stackvox stop          # graceful shutdown
+stackvox stop          # graceful shutdown, force-killed if it acknowledges but is still up after 5s
 ```
 
 stackvox checks PyPI for newer versions but only at two moments — when you run `stackvox status` and at daemon startup. The script-heavy paths (`say`, `speak`, `stackvox-say`, hooks, CI) never make a network call. To see notices on every invocation set `STACKVOX_UPDATE_NOTICE=1`. To disable the check entirely set `STACKVOX_NO_UPDATE_CHECK=1`. The check is auto-skipped when common CI env vars (`CI`, `GITHUB_ACTIONS`, etc.) are set so build logs stay clean.
@@ -159,7 +164,7 @@ Exit codes: `0` ok, `2` daemon unreachable (unless `--fallback-say` was given).
 ## Python library
 
 ```python
-from stackvox import Stackvox, speak, synthesize
+from stackvox import Stackvox, speak, synthesize, synthesize_stream
 
 # One-shot — model loads on first call, reused for subsequent calls.
 speak("Hello world")
@@ -169,6 +174,10 @@ tts = Stackvox(voice="af_bella")
 tts.speak("First line")
 tts.speak("Faster", speed=1.2)
 
+# Cap ONNX Runtime's thread pools — it otherwise sizes them from the host's core
+# count, which oversubscribes inside a container with a smaller CPU quota.
+tts = Stackvox(threads=4)
+
 # Non-blocking playback.
 tts.speak("async", blocking=False)
 tts.stop()
@@ -176,6 +185,11 @@ tts.stop()
 # Raw samples for custom processing.
 samples, sr = tts.synthesize("give me the array")
 
+# Streaming: one chunk per sentence, yielded as soon as it is synthesized, so
+# a caller encoding audio itself waits one sentence rather than the whole text.
+for chunk, sr in tts.synthesize_stream("First sentence. Second sentence."):
+    encode_and_send(chunk, sr)
+
 # Gapless multi-line playback with concurrent synthesis.
 tts.speak_sequence([
     {"text": "Hello", "voice": "af_heart", "lang": "en-us"},
@@ -193,6 +207,100 @@ if daemon.is_running():
     daemon.stop()
 ```
 
+## Local MLX models (Apple Silicon)
+
+The optional `mlx` backend runs any text-to-speech model that
+[MLX Audio](https://github.com/Blaizzy/mlx-audio) can load from a local
+directory, including ones that support voice cloning and style instructions.
+Kokoro (ONNX) remains the default backend and dependency set.
+
+```bash
+pip install 'stackvox[mlx]'
+
+stackvox speak \
+  --backend mlx \
+  --model-dir /path/to/model \
+  --reference-audio /path/to/reference.wav \
+  --reference-text "The exact transcript of the reference audio." \
+  --out cloned.wav \
+  "Hello from a local MLX model."
+```
+
+> **Model licenses:** stackvox never downloads, bundles, or recommends MLX
+> models. You supply the model directory, and its license (which may restrict
+> commercial use) applies to your use of it. Some models also need their own
+> extra Python packages; MLX Audio names them if they are missing.
+
+Keep a large model resident for repeated requests by selecting it when the
+daemon starts. The backend and model cannot be changed without restarting the
+daemon. Generation options given to `serve` become the daemon's defaults, and
+any `say` request can override them:
+
+```bash
+stackvox serve --backend mlx --model-dir /path/to/model
+
+stackvox say \
+  --reference-audio /path/to/reference.wav \
+  --reference-text "The exact transcript of the reference audio." \
+  "This request uses the resident model."
+```
+
+Generation options (`--reference-audio`, `--reference-text`, `--instruct`,
+`--temperature`, `--top-p`, `--top-k`) are forwarded only when set, so each
+model's own defaults apply otherwise; which ones a model honours depends on
+the model. They are rejected with an error unless the `mlx` backend is in use,
+both by `speak` and by a daemon running Kokoro. `--voice` and `--lang` apply to
+Kokoro only. Playback streams in chunks of about two sentences (up to ~170
+characters), so the first audio arrives once the first chunk is generated;
+short chunks also stop models drifting off-script on long text. Models slower
+than real time will pause between chunks.
+
+### Model adapters
+
+Some models need custom loading, such as renamed weights, a codec path, or a
+tokenizer quirk. Rather than carrying model-specific code, stackvox accepts an
+adapter script that you write and keep locally, for example under
+`~/.config/stackvox/adapters/`:
+
+```python
+# my_adapter.py
+from pathlib import Path
+from stackvox.mlx_backend import swapped
+
+
+def load(model_dir: Path, load_model):
+    # Patch whatever the model needs for the duration of the load, then
+    # delegate to MLX Audio's loader (or replace it entirely).
+    from some_library import SomeClass
+
+    with swapped(SomeClass, "some_method", lambda *args, **kwargs: ...):
+        return load_model(model_dir)
+```
+
+```bash
+stackvox speak --backend mlx --model-dir /path/to/model \
+  --model-adapter ~/.config/stackvox/adapters/my_adapter.py "Hello"
+```
+
+`load(model_dir, load_model)` must return the loaded model. `swapped` patches
+an attribute and restores it afterwards, even on error. Adapters run as normal
+Python with your privileges and are only used when passed explicitly; nothing
+is picked up from a model directory.
+
+The Python API uses the same waveform contract as Kokoro:
+
+```python
+from pathlib import Path
+from stackvox import Stackvox
+
+tts = Stackvox(backend="mlx", model_dir=Path("/path/to/model"))
+samples, sample_rate = tts.synthesize(
+    "A calm and natural delivery.",
+    reference_audio=Path("reference.wav"),
+    reference_text="The reference transcript.",
+)
+```
+
 ## Voices
 
 Kokoro ships voices across several languages. Voice prefix encodes gender + language:
@@ -209,7 +317,34 @@ Kokoro ships voices across several languages. Voice prefix encodes gender + lang
 | `jf_*`, `jm_*` | Japanese         | `jf_alpha`               |
 | `zf_*`, `zm_*` | Mandarin Chinese | `zf_xiaoxiao`            |
 
-Run `stackvox voices` for the authoritative list.
+Run `stackvox voices` for the authoritative list, which includes the voice mixes below.
+
+### Voice mixes
+
+Each Kokoro voice is a style vector, so a weighted blend of several makes a new voice between them. A mix is named, and the name works anywhere a voice id does: `--voice`, `Stackvox(voice=...)`, and the daemon's socket protocol. It also carries the `lang` and `speed` it was tuned with, which apply unless you pass your own.
+
+Two ship built in, a transatlantic newsreader pair (American delivery, British vowels):
+
+| Name     | Mix                                                   | lang    | speed |
+| -------- | ----------------------------------------------------- | ------- | ----- |
+| `chip`   | `am_liam` 0.6, `bm_daniel` 0.4                        | `en-gb` | 1.0   |
+| `ramona` | `af_aoede` 0.5, `af_bella` 0.2, `bf_emma` 0.3         | `en-gb` | 1.0   |
+
+```bash
+stackvox speak --voice chip "Good evening, and welcome to the news."
+stackvox say --voice ramona "Thanks Chip."
+```
+
+Define your own in the config file. Weights needn't sum to 1, and a table named after a built-in replaces it:
+
+```toml
+[voices.narrator]
+mix = { am_michael = 0.6, bm_george = 0.4 }
+lang = "en-gb"   # optional
+speed = 1.0      # optional
+```
+
+The daemon reads mixes when it starts, so restart it (`stackvox stop`, then `stackvox serve`) after editing them.
 
 ## Architecture
 
@@ -232,6 +367,8 @@ Socket lives at `~/.cache/stackvox/daemon.sock` (override with `STACKVOX_SOCKET`
 
 Queue depth is 2 — rapid-fire requests beyond that get `busy` rather than piling up.
 
+If playback hangs the daemon exits rather than answering `busy` forever. Each utterance gets 60s plus half a second per character, slower than any voice reads it even at speed 0.5. Past that the daemon removes its socket and exits with status 70, so `say` reports it isn't running and anything that starts the daemon on demand gets a fresh one. On macOS this has been PortAudio deadlocked stopping a stream, or stuck writing to an output device that stopped taking audio, and `cancel` can't break either.
+
 Before each utterance the daemon resets PortAudio so it picks up the current system default output device. Swap from speakers to Bluetooth headphones mid-session and the next `say` follows you — no daemon restart needed. The refresh costs ~10–50ms per play, which is invisible next to synthesis time.
 
 ## Requirements
@@ -275,4 +412,6 @@ stackvox itself is licensed under the **Apache License, Version 2.0** — see [`
 
 **Runtime dependencies.** [`kokoro-onnx`](https://github.com/thewh1teagle/kokoro-onnx) (MIT, © thewh1teagle), [`onnxruntime`](https://github.com/microsoft/onnxruntime) (MIT, © Microsoft), [`sounddevice`](https://python-sounddevice.readthedocs.io/) (MIT, © Matthias Geier), [`soundfile`](https://github.com/bastibe/python-soundfile) (BSD-3, © Bastian Bechtold), [`numpy`](https://numpy.org/) (BSD-3).
 
+**Optional MLX backend.** `stackvox[mlx]` runs on [`mlx-audio`](https://github.com/Blaizzy/mlx-audio) (MIT, © Prince Canuma), [`mlx`](https://github.com/ml-explore/mlx) and [`mlx-lm`](https://github.com/ml-explore/mlx-lm) (MIT, © Apple), and [`transformers`](https://github.com/huggingface/transformers) (Apache 2.0, © Hugging Face). stackvox does not download, bundle, or redistribute any MLX model; the license of whichever model you supply governs your use of it.
+
 **GPL note.** `kokoro-onnx` pulls in [`phonemizer-fork`](https://github.com/bootphon/phonemizer) as a transitive runtime dependency; it is licensed under **GPL-3.0**. stackvox does not bundle, modify, or statically link it — pip installs it alongside stackvox and the two communicate through phonemizer's published Python API at runtime. If you redistribute a combined work (e.g. a frozen binary, container image, or vendored wheel set) that includes phonemizer-fork, review GPL-3.0 obligations for that distribution.

{stackvox-0.12.0 → stackvox-0.14.0}/README.md

@@ -69,10 +69,12 @@ stackvox speak --normalize --file post.md       # normalize, then synthesize
 stackvox say   --normalize "**Shipped** 1,198.9 MPG"   # normalize, then send to daemon
 ```
 
-`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-abbreviations`, `--no-filenames`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
 
 **Dev-output handling** (on by default; `--no-dev-terms` to disable) covers two things espeak reads badly: acronyms it says as words (`CLI` → "C L I", `AWS`, `URI`, `IAM`, …) and file-line references, which it voices literally as "dot py colon". A `file.ext:line` ref is re-spoken lead-with-the-line: `engine.py:42` → "line 42 of engine py", `cli.py:100-118` → "lines 100 to 118 of cli py", `foo.ts:666:10` → "line 666, column 10 of foo ts". Times, ratios, and versions (`12:30`, `3:1`, `1.2.3`) are left alone.
 
+**Chat shorthand** (on by default; `--no-abbreviations` to disable) is expanded to the words it stands for, so a response that reads "lmk" is spoken as "let me know": `lmk`, `iirc`, `afaik`, `idk`, `tbh`, `imo`, `btw`, `fyi`, `asap`, `wrt`, `tl;dr`/`tldr`. Whole-word and case-insensitive. Shorthand that doubles as a real word or is already voiced correctly (`rn`, `eta`, `aka`) is deliberately left alone; a `--pronunciations` entry overrides any of these.
+
 Fenced code blocks are dropped by default. `--code-blocks placeholder` instead speaks a short stand-in so a skipped block doesn't sound disjointed (ChatGPT-style) — set the wording with `--code-placeholder` (e.g. `--code-blocks placeholder --code-placeholder "you can see the code in the chat history"`); consecutive blocks collapse to one.
 
 Bash completion:
@@ -95,7 +97,7 @@ 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.
+CLI flags always win over config values, and config values always win over the built-in defaults. The one thing between a flag and the config is a [voice mix](#voice-mixes)'s own `lang` and `speed`, so `--voice chip` stays transatlantic even when `[defaults]` sets `lang = "en-us"`. A missing file is fine — built-ins apply. A malformed file logs a warning and is ignored.
 
 ## Daemon mode
 
@@ -105,7 +107,7 @@ Keeps the model resident so each subsequent call is instant:
 stackvox serve         # foreground; run with `nohup stackvox serve &` to background
 stackvox status        # is the daemon up? also shows version + any pending PyPI update
 stackvox say "Hello"   # send text to the daemon (fails if not running)
-stackvox stop          # graceful shutdown
+stackvox stop          # graceful shutdown, force-killed if it acknowledges but is still up after 5s
 ```
 
 stackvox checks PyPI for newer versions but only at two moments — when you run `stackvox status` and at daemon startup. The script-heavy paths (`say`, `speak`, `stackvox-say`, hooks, CI) never make a network call. To see notices on every invocation set `STACKVOX_UPDATE_NOTICE=1`. To disable the check entirely set `STACKVOX_NO_UPDATE_CHECK=1`. The check is auto-skipped when common CI env vars (`CI`, `GITHUB_ACTIONS`, etc.) are set so build logs stay clean.
@@ -125,7 +127,7 @@ Exit codes: `0` ok, `2` daemon unreachable (unless `--fallback-say` was given).
 ## Python library
 
 ```python
-from stackvox import Stackvox, speak, synthesize
+from stackvox import Stackvox, speak, synthesize, synthesize_stream
 
 # One-shot — model loads on first call, reused for subsequent calls.
 speak("Hello world")
@@ -135,6 +137,10 @@ tts = Stackvox(voice="af_bella")
 tts.speak("First line")
 tts.speak("Faster", speed=1.2)
 
+# Cap ONNX Runtime's thread pools — it otherwise sizes them from the host's core
+# count, which oversubscribes inside a container with a smaller CPU quota.
+tts = Stackvox(threads=4)
+
 # Non-blocking playback.
 tts.speak("async", blocking=False)
 tts.stop()
@@ -142,6 +148,11 @@ tts.stop()
 # Raw samples for custom processing.
 samples, sr = tts.synthesize("give me the array")
 
+# Streaming: one chunk per sentence, yielded as soon as it is synthesized, so
+# a caller encoding audio itself waits one sentence rather than the whole text.
+for chunk, sr in tts.synthesize_stream("First sentence. Second sentence."):
+    encode_and_send(chunk, sr)
+
 # Gapless multi-line playback with concurrent synthesis.
 tts.speak_sequence([
     {"text": "Hello", "voice": "af_heart", "lang": "en-us"},
@@ -159,6 +170,100 @@ if daemon.is_running():
     daemon.stop()
 ```
 
+## Local MLX models (Apple Silicon)
+
+The optional `mlx` backend runs any text-to-speech model that
+[MLX Audio](https://github.com/Blaizzy/mlx-audio) can load from a local
+directory, including ones that support voice cloning and style instructions.
+Kokoro (ONNX) remains the default backend and dependency set.
+
+```bash
+pip install 'stackvox[mlx]'
+
+stackvox speak \
+  --backend mlx \
+  --model-dir /path/to/model \
+  --reference-audio /path/to/reference.wav \
+  --reference-text "The exact transcript of the reference audio." \
+  --out cloned.wav \
+  "Hello from a local MLX model."
+```
+
+> **Model licenses:** stackvox never downloads, bundles, or recommends MLX
+> models. You supply the model directory, and its license (which may restrict
+> commercial use) applies to your use of it. Some models also need their own
+> extra Python packages; MLX Audio names them if they are missing.
+
+Keep a large model resident for repeated requests by selecting it when the
+daemon starts. The backend and model cannot be changed without restarting the
+daemon. Generation options given to `serve` become the daemon's defaults, and
+any `say` request can override them:
+
+```bash
+stackvox serve --backend mlx --model-dir /path/to/model
+
+stackvox say \
+  --reference-audio /path/to/reference.wav \
+  --reference-text "The exact transcript of the reference audio." \
+  "This request uses the resident model."
+```
+
+Generation options (`--reference-audio`, `--reference-text`, `--instruct`,
+`--temperature`, `--top-p`, `--top-k`) are forwarded only when set, so each
+model's own defaults apply otherwise; which ones a model honours depends on
+the model. They are rejected with an error unless the `mlx` backend is in use,
+both by `speak` and by a daemon running Kokoro. `--voice` and `--lang` apply to
+Kokoro only. Playback streams in chunks of about two sentences (up to ~170
+characters), so the first audio arrives once the first chunk is generated;
+short chunks also stop models drifting off-script on long text. Models slower
+than real time will pause between chunks.
+
+### Model adapters
+
+Some models need custom loading, such as renamed weights, a codec path, or a
+tokenizer quirk. Rather than carrying model-specific code, stackvox accepts an
+adapter script that you write and keep locally, for example under
+`~/.config/stackvox/adapters/`:
+
+```python
+# my_adapter.py
+from pathlib import Path
+from stackvox.mlx_backend import swapped
+
+
+def load(model_dir: Path, load_model):
+    # Patch whatever the model needs for the duration of the load, then
+    # delegate to MLX Audio's loader (or replace it entirely).
+    from some_library import SomeClass
+
+    with swapped(SomeClass, "some_method", lambda *args, **kwargs: ...):
+        return load_model(model_dir)
+```
+
+```bash
+stackvox speak --backend mlx --model-dir /path/to/model \
+  --model-adapter ~/.config/stackvox/adapters/my_adapter.py "Hello"
+```
+
+`load(model_dir, load_model)` must return the loaded model. `swapped` patches
+an attribute and restores it afterwards, even on error. Adapters run as normal
+Python with your privileges and are only used when passed explicitly; nothing
+is picked up from a model directory.
+
+The Python API uses the same waveform contract as Kokoro:
+
+```python
+from pathlib import Path
+from stackvox import Stackvox
+
+tts = Stackvox(backend="mlx", model_dir=Path("/path/to/model"))
+samples, sample_rate = tts.synthesize(
+    "A calm and natural delivery.",
+    reference_audio=Path("reference.wav"),
+    reference_text="The reference transcript.",
+)
+```
+
 ## Voices
 
 Kokoro ships voices across several languages. Voice prefix encodes gender + language:
@@ -175,7 +280,34 @@ Kokoro ships voices across several languages. Voice prefix encodes gender + lang
 | `jf_*`, `jm_*` | Japanese         | `jf_alpha`               |
 | `zf_*`, `zm_*` | Mandarin Chinese | `zf_xiaoxiao`            |
 
-Run `stackvox voices` for the authoritative list.
+Run `stackvox voices` for the authoritative list, which includes the voice mixes below.
+
+### Voice mixes
+
+Each Kokoro voice is a style vector, so a weighted blend of several makes a new voice between them. A mix is named, and the name works anywhere a voice id does: `--voice`, `Stackvox(voice=...)`, and the daemon's socket protocol. It also carries the `lang` and `speed` it was tuned with, which apply unless you pass your own.
+
+Two ship built in, a transatlantic newsreader pair (American delivery, British vowels):
+
+| Name     | Mix                                                   | lang    | speed |
+| -------- | ----------------------------------------------------- | ------- | ----- |
+| `chip`   | `am_liam` 0.6, `bm_daniel` 0.4                        | `en-gb` | 1.0   |
+| `ramona` | `af_aoede` 0.5, `af_bella` 0.2, `bf_emma` 0.3         | `en-gb` | 1.0   |
+
+```bash
+stackvox speak --voice chip "Good evening, and welcome to the news."
+stackvox say --voice ramona "Thanks Chip."
+```
+
+Define your own in the config file. Weights needn't sum to 1, and a table named after a built-in replaces it:
+
+```toml
+[voices.narrator]
+mix = { am_michael = 0.6, bm_george = 0.4 }
+lang = "en-gb"   # optional
+speed = 1.0      # optional
+```
+
+The daemon reads mixes when it starts, so restart it (`stackvox stop`, then `stackvox serve`) after editing them.
 
 ## Architecture
 
@@ -198,6 +330,8 @@ Socket lives at `~/.cache/stackvox/daemon.sock` (override with `STACKVOX_SOCKET`
 
 Queue depth is 2 — rapid-fire requests beyond that get `busy` rather than piling up.
 
+If playback hangs the daemon exits rather than answering `busy` forever. Each utterance gets 60s plus half a second per character, slower than any voice reads it even at speed 0.5. Past that the daemon removes its socket and exits with status 70, so `say` reports it isn't running and anything that starts the daemon on demand gets a fresh one. On macOS this has been PortAudio deadlocked stopping a stream, or stuck writing to an output device that stopped taking audio, and `cancel` can't break either.
+
 Before each utterance the daemon resets PortAudio so it picks up the current system default output device. Swap from speakers to Bluetooth headphones mid-session and the next `say` follows you — no daemon restart needed. The refresh costs ~10–50ms per play, which is invisible next to synthesis time.
 
 ## Requirements
@@ -241,4 +375,6 @@ stackvox itself is licensed under the **Apache License, Version 2.0** — see [`
 
 **Runtime dependencies.** [`kokoro-onnx`](https://github.com/thewh1teagle/kokoro-onnx) (MIT, © thewh1teagle), [`onnxruntime`](https://github.com/microsoft/onnxruntime) (MIT, © Microsoft), [`sounddevice`](https://python-sounddevice.readthedocs.io/) (MIT, © Matthias Geier), [`soundfile`](https://github.com/bastibe/python-soundfile) (BSD-3, © Bastian Bechtold), [`numpy`](https://numpy.org/) (BSD-3).
 
+**Optional MLX backend.** `stackvox[mlx]` runs on [`mlx-audio`](https://github.com/Blaizzy/mlx-audio) (MIT, © Prince Canuma), [`mlx`](https://github.com/ml-explore/mlx) and [`mlx-lm`](https://github.com/ml-explore/mlx-lm) (MIT, © Apple), and [`transformers`](https://github.com/huggingface/transformers) (Apache 2.0, © Hugging Face). stackvox does not download, bundle, or redistribute any MLX model; the license of whichever model you supply governs your use of it.
+
 **GPL note.** `kokoro-onnx` pulls in [`phonemizer-fork`](https://github.com/bootphon/phonemizer) as a transitive runtime dependency; it is licensed under **GPL-3.0**. stackvox does not bundle, modify, or statically link it — pip installs it alongside stackvox and the two communicate through phonemizer's published Python API at runtime. If you redistribute a combined work (e.g. a frozen binary, container image, or vendored wheel set) that includes phonemizer-fork, review GPL-3.0 obligations for that distribution.

{stackvox-0.12.0 → stackvox-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.12.0"
+version = "0.14.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,6 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "kokoro-onnx>=0.4.0",
+    "onnxruntime>=1.20.1",
     "soundfile>=0.12.1",
     "sounddevice>=0.4.6",
     "numpy>=1.24",
@@ -28,6 +29,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# MLX Audio is pre-1.0, so cap at the next minor; the floor is the version
+# verified end to end with stackvox's loader and generate() usage.
+mlx = [
+    "mlx-audio>=0.4.5,<0.5; platform_system=='Darwin' and platform_machine=='arm64'",
+]
 dev = [
     "pytest>=8.0",
     "pytest-mock>=3.12",
@@ -124,7 +130,7 @@ disallow_untyped_defs = true
 [[tool.mypy.overrides]]
 # 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"]
+module = ["kokoro_onnx", "mlx_audio.*", "onnxruntime", "sounddevice", "soundfile", "tomli"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]

{stackvox-0.12.0 → stackvox-0.14.0}/stackvox/__init__.py

@@ -4,7 +4,7 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
 
 from stackvox import daemon
-from stackvox.engine import Stackvox, speak, synthesize
+from stackvox.engine import Stackvox, speak, synthesize, synthesize_stream
 from stackvox.text import normalize_for_speech
 
 try:
@@ -14,4 +14,4 @@ except PackageNotFoundError:
     # bootstrap before `pip install -e .` has completed).
     __version__ = "0.0.0+unknown"
 
-__all__ = ["Stackvox", "daemon", "normalize_for_speech", "speak", "synthesize"]
+__all__ = ["Stackvox", "daemon", "normalize_for_speech", "speak", "synthesize", "synthesize_stream"]