speak-cli 0.1.0__tar.gz

speak_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

speak_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+*.wav
+.pytest_cache/
+uv.lock

speak_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

speak_cli-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: speak-cli
+Version: 0.1.0
+Summary: Speak text out loud from the command line using Supertonic 3 (local, offline TTS)
+Project-URL: Repository, https://github.com/MohamedAliRashad/tts-cli
+Project-URL: Issues, https://github.com/MohamedAliRashad/tts-cli/issues
+Author: Mohamed Rashad
+License: MIT
+Keywords: cli,offline,speech,supertonic,text-to-speech,tts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Requires-Dist: supertonic>=1.3.1
+Description-Content-Type: text/markdown
+
+# speak — local text-to-speech CLI
+
+Speak text out loud from the command line using [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) — a fast, ~99M-parameter TTS model that runs entirely on your CPU. No cloud, no API keys.
+
+```bash
+speak "hello world"
+echo "piped text works too" | speak
+speak -v noah "a different voice"
+speak "مرحبا بالعالم"          # language auto-detected from the text
+speak -o clip.wav "save to a file instead"
+```
+
+## Install
+
+```bash
+uv tool install speak-cli
+```
+
+Or without waiting for a PyPI release, straight from GitHub:
+
+```bash
+uv tool install git+https://github.com/MohamedAliRashad/tts-cli
+```
+
+(From a clone, `uv tool install .` works too.) All dependencies are prebuilt Python wheels — no compilers, no apt packages. On the first `speak`, the Supertonic 3 models (~400 MB) are downloaded once to `~/.cache/supertonic3/`; everything after that works fully offline. `say` is installed as an alias of `speak` (handy, but if another tool on your machine already provides `say`, just use `speak`).
+
+## How it stays fast
+
+The first call starts a background daemon that keeps the models loaded in memory, so subsequent calls speak in well under a second. The daemon exits after 15 minutes idle (tune with `SPEAK_IDLE_TIMEOUT` seconds) and is respawned transparently. If the daemon can't run for any reason, `speak` silently falls back to in-process synthesis — it always works.
+
+```bash
+speak --stop        # stop the daemon manually
+speak --no-daemon   # bypass the daemon for one call
+```
+
+## Voices
+
+```
+speak --list-voices
+```
+
+| Female | Male |
+|---|---|
+| sara *(default)* | james |
+| emma | daniel |
+| lily | leo |
+| maya | ryan |
+| nora | noah |
+
+`--voice` accepts any of these names, case-insensitive. Set a persistent default with `export SPEAK_VOICE=noah`.
+
+## Options
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `-v, --voice` | sara | voice name |
+| `-s, --speed` | 1.05 | speech speed (0.7–2.0) |
+| `-l, --lang` | auto | language code, `auto`, or `na` (language-agnostic) |
+| `--steps` | 8 | quality/speed trade-off (5–12) |
+| `-o, --out FILE` | — | write WAV instead of playing (`--play` for both) |
+| `--verbose` | — | show detected language, timing, synthesis path |
+
+Language auto-detection is script-based: Arabic, Japanese, Korean, Russian, Greek, and Hindi are detected from their alphabets; all Latin-script text is assumed English (use `--lang fr`, `--lang de`, … to override). Supported languages: en ko ja ar bg cs da de el es et fi fr hi hr hu id it lt lv nl pl pt ro ru sk sl sv tr uk vi.
+
+Expression tags can be embedded in the text: `speak "well <laugh> that was funny"` (also `<breath>`, `<sigh>`, …).
+
+## Playback
+
+Audio is played through the first working system player among `paplay`, `pw-play`, `aplay`, `afplay` (macOS), `ffplay`, `play` (sox) — every mainstream desktop has at least one. If none works, `speak` tells you and suggests `--out`.
+
+## Licenses
+
+CLI code: MIT. Supertonic 3 model weights: [OpenRAIL-M](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE) (via the `supertonic` SDK's auto-download).

speak_cli-0.1.0/README.md

@@ -0,0 +1,73 @@
+# speak — local text-to-speech CLI
+
+Speak text out loud from the command line using [Supertonic 3](https://huggingface.co/Supertone/supertonic-3) — a fast, ~99M-parameter TTS model that runs entirely on your CPU. No cloud, no API keys.
+
+```bash
+speak "hello world"
+echo "piped text works too" | speak
+speak -v noah "a different voice"
+speak "مرحبا بالعالم"          # language auto-detected from the text
+speak -o clip.wav "save to a file instead"
+```
+
+## Install
+
+```bash
+uv tool install speak-cli
+```
+
+Or without waiting for a PyPI release, straight from GitHub:
+
+```bash
+uv tool install git+https://github.com/MohamedAliRashad/tts-cli
+```
+
+(From a clone, `uv tool install .` works too.) All dependencies are prebuilt Python wheels — no compilers, no apt packages. On the first `speak`, the Supertonic 3 models (~400 MB) are downloaded once to `~/.cache/supertonic3/`; everything after that works fully offline. `say` is installed as an alias of `speak` (handy, but if another tool on your machine already provides `say`, just use `speak`).
+
+## How it stays fast
+
+The first call starts a background daemon that keeps the models loaded in memory, so subsequent calls speak in well under a second. The daemon exits after 15 minutes idle (tune with `SPEAK_IDLE_TIMEOUT` seconds) and is respawned transparently. If the daemon can't run for any reason, `speak` silently falls back to in-process synthesis — it always works.
+
+```bash
+speak --stop        # stop the daemon manually
+speak --no-daemon   # bypass the daemon for one call
+```
+
+## Voices
+
+```
+speak --list-voices
+```
+
+| Female | Male |
+|---|---|
+| sara *(default)* | james |
+| emma | daniel |
+| lily | leo |
+| maya | ryan |
+| nora | noah |
+
+`--voice` accepts any of these names, case-insensitive. Set a persistent default with `export SPEAK_VOICE=noah`.
+
+## Options
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `-v, --voice` | sara | voice name |
+| `-s, --speed` | 1.05 | speech speed (0.7–2.0) |
+| `-l, --lang` | auto | language code, `auto`, or `na` (language-agnostic) |
+| `--steps` | 8 | quality/speed trade-off (5–12) |
+| `-o, --out FILE` | — | write WAV instead of playing (`--play` for both) |
+| `--verbose` | — | show detected language, timing, synthesis path |
+
+Language auto-detection is script-based: Arabic, Japanese, Korean, Russian, Greek, and Hindi are detected from their alphabets; all Latin-script text is assumed English (use `--lang fr`, `--lang de`, … to override). Supported languages: en ko ja ar bg cs da de el es et fi fr hi hr hu id it lt lv nl pl pt ro ru sk sl sv tr uk vi.
+
+Expression tags can be embedded in the text: `speak "well <laugh> that was funny"` (also `<breath>`, `<sigh>`, …).
+
+## Playback
+
+Audio is played through the first working system player among `paplay`, `pw-play`, `aplay`, `afplay` (macOS), `ffplay`, `play` (sox) — every mainstream desktop has at least one. If none works, `speak` tells you and suggests `--out`.
+
+## Licenses
+
+CLI code: MIT. Supertonic 3 model weights: [OpenRAIL-M](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE) (via the `supertonic` SDK's auto-download).

speak_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "speak-cli"
+version = "0.1.0"
+description = "Speak text out loud from the command line using Supertonic 3 (local, offline TTS)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Mohamed Rashad" }]
+keywords = ["tts", "text-to-speech", "supertonic", "cli", "speech", "offline"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "supertonic>=1.3.1",
+]
+
+[project.urls]
+Repository = "https://github.com/MohamedAliRashad/tts-cli"
+Issues = "https://github.com/MohamedAliRashad/tts-cli/issues"
+
+[project.scripts]
+say = "speak_cli.cli:main"
+speak = "speak_cli.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/speak_cli"]

speak_cli-0.1.0/src/speak_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

speak_cli-0.1.0/src/speak_cli/cli.py

@@ -0,0 +1,177 @@
+"""`speak` — speak text out loud using Supertonic 3, locally and offline."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, voices
+from .langdetect import SUPPORTED_LANGS, detect_lang
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="speak",
+        description="Speak text out loud using Supertonic 3 (local TTS, no cloud).",
+        epilog='Examples:  speak "hello world"   |   echo hi | speak   |   speak -v noah -l ar "مرحبا"',
+    )
+    p.add_argument("text", nargs="*", help="text to speak (reads stdin if omitted)")
+    p.add_argument("-v", "--voice", default=None, metavar="NAME",
+                   help="voice name (see --list-voices; default: sara)")
+    p.add_argument("-s", "--speed", type=float, default=1.05, metavar="X",
+                   help="speech speed, 0.7-2.0 (default: 1.05)")
+    p.add_argument("-l", "--lang", default="auto", metavar="CODE",
+                   help='language code, "auto" (default) or "na"')
+    p.add_argument("--steps", type=int, default=8, metavar="N",
+                   help="denoising steps 5-12, higher = better quality (default: 8)")
+    p.add_argument("-o", "--out", metavar="FILE",
+                   help="save WAV to FILE instead of playing")
+    p.add_argument("--play", action="store_true",
+                   help="with --out: also play the audio")
+    p.add_argument("--list-voices", action="store_true", help="list voices and exit")
+    p.add_argument("--no-daemon", action="store_true",
+                   help="synthesize in-process instead of using the daemon")
+    p.add_argument("--stop", action="store_true",
+                   help="stop the background daemon and exit")
+    p.add_argument("--verbose", action="store_true",
+                   help="print timing and which synthesis/playback path was used")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _resolve_text(args: argparse.Namespace) -> str:
+    if args.text:
+        return " ".join(args.text).strip()
+    if not sys.stdin.isatty():
+        return sys.stdin.read().strip()
+    return ""
+
+
+def _synthesize(req: dict, no_daemon: bool, verbose: bool) -> bytes:
+    """Get WAV bytes: daemon first, silent fallback to in-process."""
+    import time
+
+    from . import ipc
+    from .engine import models_cached
+
+    first_run = not models_cached()
+    if first_run:
+        print(
+            "First run: downloading Supertonic 3 models (~400 MB, one time)...",
+            file=sys.stderr,
+        )
+
+    t0 = time.monotonic()
+    if not no_daemon and not first_run:
+        try:
+            wav = ipc.get_wav_from_daemon(req)
+            if verbose:
+                print(f"[speak] daemon path, {time.monotonic() - t0:.2f}s", file=sys.stderr)
+            return wav
+        except Exception as e:
+            ipc.log_client(f"daemon path failed, falling back to one-shot: {e!r}")
+            if verbose:
+                print(f"[speak] daemon failed ({e}), one-shot fallback", file=sys.stderr)
+
+    from .engine import Engine
+
+    engine = Engine()
+    wav, _ = engine.synthesize(
+        text=req["text"],
+        voice=req["voice"],
+        speed=req["speed"],
+        lang=req["lang"],
+        steps=req["steps"],
+    )
+    if verbose:
+        print(f"[speak] one-shot path, {time.monotonic() - t0:.2f}s", file=sys.stderr)
+    if first_run and not no_daemon:
+        # Warm a daemon in the background so the next call is fast.
+        try:
+            from . import ipc as _ipc
+
+            _ipc.spawn_daemon(_ipc.runtime_paths())
+        except Exception:
+            pass
+    return wav
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.list_voices:
+        print(voices.listing())
+        return 0
+
+    if args.stop:
+        from . import ipc
+
+        n = ipc.stop_daemons()
+        print(f"stopped {n} daemon(s)" if n else "no daemon running")
+        return 0
+
+    text = _resolve_text(args)
+    if not text:
+        print("speak: no text to speak (pass text as arguments or pipe via stdin)",
+              file=sys.stderr)
+        return 2
+
+    try:
+        _, style_id = voices.resolve(args.voice or voices.default_voice())
+    except ValueError as e:
+        print(f"speak: {e}", file=sys.stderr)
+        return 2
+
+    if not 0.7 <= args.speed <= 2.0:
+        print("speak: --speed must be between 0.7 and 2.0", file=sys.stderr)
+        return 2
+    if not 1 <= args.steps <= 32:
+        print("speak: --steps must be between 1 and 32", file=sys.stderr)
+        return 2
+
+    lang = detect_lang(text) if args.lang == "auto" else args.lang.lower()
+    if lang not in SUPPORTED_LANGS:
+        supported = " ".join(sorted(SUPPORTED_LANGS))
+        print(f"speak: unsupported language {lang!r}. Supported: {supported}",
+              file=sys.stderr)
+        return 2
+    if args.verbose:
+        print(f"[speak] voice={style_id} lang={lang} speed={args.speed} steps={args.steps}",
+              file=sys.stderr)
+
+    req = {
+        "cmd": "speak",
+        "text": text,
+        "voice": style_id,
+        "speed": args.speed,
+        "lang": lang,
+        "steps": args.steps,
+    }
+
+    try:
+        wav = _synthesize(req, no_daemon=args.no_daemon, verbose=args.verbose)
+
+        if args.out:
+            with open(args.out, "wb") as f:
+                f.write(wav)
+            if args.verbose:
+                print(f"[speak] wrote {args.out}", file=sys.stderr)
+
+        if not args.out or args.play:
+            from .playback import PlaybackError, play
+
+            try:
+                play(wav, verbose=args.verbose)
+            except PlaybackError as e:
+                print(f"speak: {e}", file=sys.stderr)
+                return 1
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        print(f"speak: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

speak_cli-0.1.0/src/speak_cli/daemon.py

@@ -0,0 +1,103 @@
+"""Background daemon: keeps Supertonic models warm, serves synthesis requests.
+
+Run as `python -m speak_cli.daemon`. Single instance is enforced with an
+flock'd lock file; a second copy exits 0 immediately, so racing auto-spawns
+are harmless. Exits on idle timeout to free memory.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import socket
+import sys
+
+from . import ipc
+from .engine import Engine
+
+DEFAULT_IDLE_TIMEOUT = 900.0
+
+
+def _idle_timeout() -> float:
+    try:
+        return max(5.0, float(os.environ["SPEAK_IDLE_TIMEOUT"]))
+    except (KeyError, ValueError):
+        return DEFAULT_IDLE_TIMEOUT
+
+
+def handle_request(conn: socket.socket, engine: Engine) -> bool:
+    """Serve one connection. Returns False when asked to shut down."""
+    try:
+        req = json.loads(ipc.recv_line(conn))
+        cmd = req.get("cmd")
+        if cmd == "shutdown":
+            conn.sendall(b'{"status": "ok"}\n')
+            return False
+        if cmd == "ping":
+            conn.sendall(b'{"status": "ok"}\n')
+            return True
+        if cmd != "speak":
+            raise ValueError(f"unknown command {cmd!r}")
+        wav, duration = engine.synthesize(
+            text=req["text"],
+            voice=req.get("voice", "F1"),
+            speed=req.get("speed", 1.05),
+            lang=req.get("lang", "en"),
+            steps=req.get("steps", 8),
+        )
+        header = json.dumps(
+            {"status": "ok", "nbytes": len(wav), "duration": duration}
+        )
+        conn.sendall(header.encode() + b"\n" + wav)
+    except Exception as e:  # one bad request must never kill the daemon
+        with contextlib.suppress(OSError):
+            conn.sendall(
+                json.dumps({"status": "error", "message": str(e)}).encode() + b"\n"
+            )
+    return True
+
+
+def main() -> None:
+    paths = ipc.runtime_paths()
+
+    lock = open(paths.lock, "w")
+    try:
+        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        return  # another daemon is already serving
+    lock.write(str(os.getpid()))
+    lock.flush()
+
+    print(f"[daemon] starting, pid={os.getpid()}", flush=True)
+    engine = Engine()
+    engine.prewarm()
+    print("[daemon] models loaded and prewarmed", flush=True)
+
+    paths.sock.unlink(missing_ok=True)
+    srv = socket.socket(socket.AF_UNIX)
+    srv.bind(str(paths.sock))
+    os.chmod(paths.sock, 0o600)
+    srv.listen(8)
+    srv.settimeout(_idle_timeout())
+
+    try:
+        while True:
+            try:
+                conn, _ = srv.accept()
+            except socket.timeout:
+                print("[daemon] idle timeout, exiting", flush=True)
+                break
+            with conn:
+                conn.settimeout(ipc.REQUEST_TIMEOUT)
+                if not handle_request(conn, engine):
+                    print("[daemon] shutdown requested", flush=True)
+                    break
+    finally:
+        paths.sock.unlink(missing_ok=True)
+        paths.lock.unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

speak_cli-0.1.0/src/speak_cli/engine.py

@@ -0,0 +1,70 @@
+"""Lazy wrapper around the Supertonic 3 SDK producing WAV bytes.
+
+`supertonic` (and its onnxruntime import) is only loaded when an Engine is
+constructed, so fast CLI paths (--version, --list-voices, --stop) never pay
+the import cost.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+
+SAMPLE_RATE = 44100
+
+MODEL_CACHE = Path(os.environ.get("SUPERTONIC_CACHE", "")) if os.environ.get(
+    "SUPERTONIC_CACHE"
+) else Path.home() / ".cache" / "supertonic3"
+
+
+def models_cached() -> bool:
+    """True if the Supertonic model assets look downloaded already."""
+    try:
+        return any(MODEL_CACHE.rglob("*.onnx"))
+    except OSError:
+        return False
+
+
+class Engine:
+    def __init__(self) -> None:
+        from supertonic import TTS
+
+        self._tts = TTS(auto_download=True)
+        self._styles: dict[str, object] = {}
+
+    def _style(self, style_id: str):
+        if style_id not in self._styles:
+            self._styles[style_id] = self._tts.get_voice_style(voice_name=style_id)
+        return self._styles[style_id]
+
+    def synthesize(
+        self,
+        text: str,
+        voice: str = "F1",
+        speed: float = 1.05,
+        lang: str = "en",
+        steps: int = 8,
+    ) -> tuple[bytes, float]:
+        """Synthesize text and return (wav_bytes, duration_seconds)."""
+        import soundfile as sf
+
+        wav, duration = self._tts.synthesize(
+            text=text,
+            voice_style=self._style(voice),
+            total_steps=steps,
+            speed=speed,
+            max_chunk_length=300,
+            silence_duration=0.3,
+            lang=lang,
+            verbose=False,
+        )
+        import numpy as np
+
+        buf = io.BytesIO()
+        sf.write(buf, wav.squeeze(), SAMPLE_RATE, format="WAV", subtype="PCM_16")
+        return buf.getvalue(), float(np.asarray(duration).sum())
+
+    def prewarm(self) -> None:
+        """Run a tiny synthesis so the first real request hits warm ONNX kernels."""
+        self.synthesize("Hi.", steps=2)

speak_cli-0.1.0/src/speak_cli/ipc.py

@@ -0,0 +1,155 @@
+"""Client/daemon plumbing: runtime paths, JSON-line framing, spawn + connect.
+
+Protocol: one request per connection. Client sends a single JSON line;
+daemon replies a JSON header line, then (for "speak") exactly `nbytes` of
+raw WAV. The socket filename embeds the package version, so upgrading the
+package naturally retires old daemons (they exit via idle timeout).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__
+
+CONNECT_TIMEOUT = 30.0  # daemon cold-start budget (models already cached)
+REQUEST_TIMEOUT = 300.0  # long texts take a while to synthesize
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+    dir: Path
+    sock: Path
+    lock: Path
+    daemon_log: Path
+    client_log: Path
+
+
+def runtime_paths() -> RuntimePaths:
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime and os.path.isdir(runtime):
+        base = Path(runtime) / "speak-cli"
+    else:
+        base = Path.home() / ".cache" / "speak-cli" / "run"
+    base.mkdir(parents=True, exist_ok=True)
+    os.chmod(base, 0o700)
+    log_dir = Path.home() / ".cache" / "speak-cli"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return RuntimePaths(
+        dir=base,
+        sock=base / f"daemon-{__version__}.sock",
+        lock=base / f"daemon-{__version__}.lock",
+        daemon_log=log_dir / "daemon.log",
+        client_log=log_dir / "client.log",
+    )
+
+
+def log_client(message: str) -> None:
+    try:
+        with open(runtime_paths().client_log, "a") as f:
+            f.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {message}\n")
+    except OSError:
+        pass
+
+
+def recv_line(sock: socket.socket, max_bytes: int = 1_000_000) -> bytes:
+    chunks = []
+    total = 0
+    while total < max_bytes:
+        b = sock.recv(1)
+        if not b:
+            break
+        if b == b"\n":
+            return b"".join(chunks)
+        chunks.append(b)
+        total += 1
+    raise ValueError("malformed message (no newline)")
+
+
+def recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sock.recv(min(65536, n - len(buf)))
+        if not chunk:
+            raise ConnectionError("connection closed mid-payload")
+        buf.extend(chunk)
+    return bytes(buf)
+
+
+def _request(sock_path: Path, req: dict) -> bytes:
+    """Send one request; return WAV bytes (or b"" for control commands)."""
+    with socket.socket(socket.AF_UNIX) as s:
+        s.settimeout(REQUEST_TIMEOUT)
+        s.connect(str(sock_path))
+        s.sendall(json.dumps(req).encode() + b"\n")
+        header = json.loads(recv_line(s))
+        if header.get("status") != "ok":
+            raise RuntimeError(header.get("message", "daemon error"))
+        nbytes = header.get("nbytes", 0)
+        return recv_exact(s, nbytes) if nbytes else b""
+
+
+def spawn_daemon(paths: RuntimePaths) -> None:
+    """Start a detached daemon process; harmless if one is already running."""
+    with open(paths.daemon_log, "ab") as log:
+        subprocess.Popen(
+            [sys.executable, "-m", "speak_cli.daemon"],
+            stdin=subprocess.DEVNULL,
+            stdout=log,
+            stderr=log,
+            start_new_session=True,
+        )
+
+
+def get_wav_from_daemon(req: dict) -> bytes:
+    """Request synthesis from the daemon, auto-spawning it if needed.
+
+    Raises on any failure — the caller falls back to one-shot synthesis.
+    """
+    if os.name != "posix":
+        raise RuntimeError("daemon mode is POSIX-only")
+    paths = runtime_paths()
+    try:
+        return _request(paths.sock, req)
+    except (FileNotFoundError, ConnectionRefusedError):
+        # Not running (or crashed leaving a stale socket): clean up and spawn.
+        paths.sock.unlink(missing_ok=True)
+        spawn_daemon(paths)
+        deadline = time.monotonic() + CONNECT_TIMEOUT
+        while True:
+            try:
+                return _request(paths.sock, req)
+            except (FileNotFoundError, ConnectionRefusedError):
+                if time.monotonic() > deadline:
+                    raise TimeoutError(
+                        f"daemon did not start within {CONNECT_TIMEOUT:.0f}s"
+                    ) from None
+                time.sleep(0.15)
+
+
+def stop_daemons() -> int:
+    """Shut down daemons of any version in any runtime dir; returns how many responded."""
+    candidates = {runtime_paths().dir, Path.home() / ".cache" / "speak-cli" / "run"}
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime:
+        candidates.add(Path(runtime) / "speak-cli")
+    stopped = 0
+    for base in candidates:
+        if not base.is_dir():
+            continue
+        for sock_path in base.glob("daemon-*.sock"):
+            try:
+                _request(sock_path, {"cmd": "shutdown"})
+                stopped += 1
+            except OSError:
+                sock_path.unlink(missing_ok=True)  # stale
+            except Exception:
+                pass
+    return stopped

speak_cli-0.1.0/src/speak_cli/langdetect.py

@@ -0,0 +1,69 @@
+"""Unicode-script-based language guessing for Supertonic 3.
+
+Deliberately tiny: no models, no dependencies. Latin-script languages are
+indistinguishable this way and map to English — use --lang to override.
+Scripts Supertonic doesn't support (Han-only/Chinese, Thai, Hebrew, ...)
+map to "na", Supertonic's language-agnostic mode.
+"""
+
+from __future__ import annotations
+
+# (start, end, bucket) — checked in order, first match wins
+_RANGES: list[tuple[int, int, str]] = [
+    (0x0600, 0x06FF, "ar"),
+    (0x0750, 0x077F, "ar"),
+    (0x08A0, 0x08FF, "ar"),
+    (0xFB50, 0xFDFF, "ar"),
+    (0xFE70, 0xFEFF, "ar"),
+    (0x3040, 0x30FF, "kana"),
+    (0x31F0, 0x31FF, "kana"),
+    (0xAC00, 0xD7AF, "ko"),
+    (0x1100, 0x11FF, "ko"),
+    (0x3130, 0x318F, "ko"),
+    (0x4E00, 0x9FFF, "han"),
+    (0x3400, 0x4DBF, "han"),
+    (0xF900, 0xFAFF, "han"),
+    (0x0400, 0x04FF, "cyr"),
+    (0x0500, 0x052F, "cyr"),
+    (0x0370, 0x03FF, "el"),
+    (0x1F00, 0x1FFF, "el"),
+    (0x0900, 0x097F, "hi"),
+    (0x0E00, 0x0E7F, "unsupported"),  # Thai
+    (0x0590, 0x05FF, "unsupported"),  # Hebrew
+    (0x0041, 0x005A, "latin"),
+    (0x0061, 0x007A, "latin"),
+    (0x00C0, 0x024F, "latin"),
+]
+
+_BUCKET_TO_LANG = {
+    "ar": "ar",
+    "ko": "ko",
+    "cyr": "ru",
+    "el": "el",
+    "hi": "hi",
+    "han": "na",
+    "unsupported": "na",
+    "latin": "en",
+}
+
+SUPPORTED_LANGS = frozenset(
+    "en ko ja ar bg cs da de el es et fi fr hi hr hu id it lt lv "
+    "nl pl pt ro ru sk sl sv tr uk vi na".split()
+)
+
+
+def detect_lang(text: str) -> str:
+    counts: dict[str, int] = {}
+    for ch in text:
+        cp = ord(ch)
+        for lo, hi, bucket in _RANGES:
+            if lo <= cp <= hi:
+                counts[bucket] = counts.get(bucket, 0) + 1
+                break
+    if not counts:
+        return "en"
+    # Japanese text is often Han-heavy; any kana at all means Japanese.
+    if counts.get("kana"):
+        return "ja"
+    dominant = max(counts, key=lambda k: counts[k])
+    return _BUCKET_TO_LANG[dominant]

speak_cli-0.1.0/src/speak_cli/playback.py

@@ -0,0 +1,61 @@
+"""Play WAV bytes through whatever audio player the system has.
+
+No Python audio dependency on purpose: simpleaudio is unmaintained and
+sounddevice needs a system PortAudio library. Every mainstream desktop has
+at least one of the players below; each is tried until one exits 0.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+
+
+class PlaybackError(RuntimeError):
+    pass
+
+
+_PLAYERS: list[tuple[str, list[str]]] = [
+    ("paplay", []),
+    ("pw-play", []),
+    ("aplay", ["-q"]),
+    ("afplay", []),
+    ("ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet"]),
+    ("play", ["-q"]),
+]
+
+
+def _tmp_dir() -> str | None:
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime and os.path.isdir(runtime) and os.access(runtime, os.W_OK):
+        return runtime  # tmpfs: no disk I/O
+    return None
+
+
+def play(wav_bytes: bytes, verbose: bool = False) -> None:
+    """Play WAV bytes; raises PlaybackError if no player works."""
+    errors: list[str] = []
+    with tempfile.NamedTemporaryFile(suffix=".wav", dir=_tmp_dir()) as f:
+        f.write(wav_bytes)
+        f.flush()
+        for name, args in _PLAYERS:
+            exe = shutil.which(name)
+            if not exe:
+                continue
+            proc = subprocess.run(
+                [exe, *args, f.name],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+            )
+            if proc.returncode == 0:
+                if verbose:
+                    print(f"[speak] played via {name}", flush=True)
+                return
+            errors.append(f"{name}: exit {proc.returncode}")
+    detail = "; ".join(errors) if errors else "no audio player found on PATH"
+    raise PlaybackError(
+        f"could not play audio ({detail}). "
+        "Use --out FILE to save the audio to a WAV file instead."
+    )

speak_cli-0.1.0/src/speak_cli/voices.py

@@ -0,0 +1,55 @@
+"""Friendly-name registry for Supertonic 3 voice styles.
+
+Upstream ships anonymous style files (M1-M5, F1-F5); we give each a name.
+"""
+
+from __future__ import annotations
+
+import os
+
+# name -> (style_id, gender)
+VOICES: dict[str, tuple[str, str]] = {
+    "sara": ("F1", "female"),
+    "emma": ("F2", "female"),
+    "lily": ("F3", "female"),
+    "maya": ("F4", "female"),
+    "nora": ("F5", "female"),
+    "james": ("M1", "male"),
+    "daniel": ("M2", "male"),
+    "leo": ("M3", "male"),
+    "ryan": ("M4", "male"),
+    "noah": ("M5", "male"),
+}
+
+DEFAULT_VOICE = "sara"
+
+def default_voice() -> str:
+    env = os.environ.get("SPEAK_VOICE", "").strip()
+    if env:
+        try:
+            return resolve(env)[0]
+        except ValueError:
+            pass  # bad SPEAK_VOICE should not break the tool
+    return DEFAULT_VOICE
+
+
+def resolve(voice: str) -> tuple[str, str]:
+    """Resolve a voice name (case-insensitive) to (name, style_id).
+
+    Raises ValueError with a helpful message for unknown voices.
+    """
+    key = voice.strip().lower()
+    if key in VOICES:
+        return key, VOICES[key][0]
+    valid = ", ".join(VOICES)
+    raise ValueError(f"unknown voice {voice!r}. Valid voices: {valid}")
+
+
+def listing() -> str:
+    """Human-readable voice table for --list-voices."""
+    default = default_voice()
+    lines = []
+    for name, (_, gender) in VOICES.items():
+        mark = "  (default)" if name == default else ""
+        lines.append(f"{name:<7} {gender}{mark}")
+    return "\n".join(lines)

speak_cli-0.1.0/tests/test_ipc_paths.py

@@ -0,0 +1,18 @@
+from speak_cli import __version__, ipc
+
+
+def test_runtime_paths_created(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_RUNTIME_DIR", str(tmp_path))
+    paths = ipc.runtime_paths()
+    assert paths.dir.is_dir()
+    assert (paths.dir.stat().st_mode & 0o777) == 0o700
+    assert paths.sock.name == f"daemon-{__version__}.sock"
+    assert paths.sock.parent == paths.dir
+
+
+def test_runtime_paths_fallback_without_xdg(tmp_path, monkeypatch):
+    monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    paths = ipc.runtime_paths()
+    assert str(paths.dir).startswith(str(tmp_path))
+    assert paths.dir.is_dir()

speak_cli-0.1.0/tests/test_langdetect.py

@@ -0,0 +1,58 @@
+from speak_cli.langdetect import SUPPORTED_LANGS, detect_lang
+
+
+def test_english():
+    assert detect_lang("Hello, world!") == "en"
+
+
+def test_arabic():
+    assert detect_lang("مرحبا بالعالم") == "ar"
+
+
+def test_arabic_with_latin_word():
+    assert detect_lang("مرحبا بالعالم من Python") == "ar"
+
+
+def test_japanese_kana():
+    assert detect_lang("こんにちは") == "ja"
+
+
+def test_japanese_han_heavy_with_kana():
+    assert detect_lang("日本語の文章です") == "ja"
+
+
+def test_han_only_maps_to_na():
+    assert detect_lang("你好世界") == "na"
+
+
+def test_korean():
+    assert detect_lang("안녕하세요") == "ko"
+
+
+def test_cyrillic():
+    assert detect_lang("Привет мир") == "ru"
+
+
+def test_greek():
+    assert detect_lang("Γεια σου κόσμε") == "el"
+
+
+def test_hindi():
+    assert detect_lang("नमस्ते दुनिया") == "hi"
+
+
+def test_hebrew_unsupported_maps_to_na():
+    assert detect_lang("שלום עולם") == "na"
+
+
+def test_numbers_only_default_en():
+    assert detect_lang("12345 !!!") == "en"
+
+
+def test_empty():
+    assert detect_lang("") == "en"
+
+
+def test_all_outputs_supported():
+    for text in ["hi", "مرحبا", "こんにちは", "你好", "안녕", "Привет", "Γεια", "नमस्ते"]:
+        assert detect_lang(text) in SUPPORTED_LANGS

speak_cli-0.1.0/tests/test_voices.py

@@ -0,0 +1,41 @@
+import pytest
+
+from speak_cli import voices
+
+
+def test_resolve_friendly_name():
+    assert voices.resolve("sara") == ("sara", "F1")
+    assert voices.resolve("noah") == ("noah", "M5")
+
+
+def test_resolve_case_insensitive():
+    assert voices.resolve("SARA") == ("sara", "F1")
+    assert voices.resolve("James") == ("james", "M1")
+
+
+def test_resolve_raw_id_rejected():
+    with pytest.raises(ValueError, match="unknown voice"):
+        voices.resolve("F1")
+
+
+def test_resolve_unknown_raises():
+    with pytest.raises(ValueError, match="unknown voice"):
+        voices.resolve("bogus")
+
+
+def test_default_voice_env_override(monkeypatch):
+    monkeypatch.setenv("SPEAK_VOICE", "noah")
+    assert voices.default_voice() == "noah"
+
+
+def test_default_voice_bad_env_falls_back(monkeypatch):
+    monkeypatch.setenv("SPEAK_VOICE", "not-a-voice")
+    assert voices.default_voice() == voices.DEFAULT_VOICE
+
+
+def test_listing_contains_all_and_default(monkeypatch):
+    monkeypatch.delenv("SPEAK_VOICE", raising=False)
+    out = voices.listing()
+    for name in voices.VOICES:
+        assert name in out
+    assert "(default)" in out