saynow 0.1.0__tar.gz

saynow-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+*.tgz
+.DS_Store
+
+# python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/

saynow-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: saynow
+Version: 0.1.0
+Summary: Speak text aloud from the terminal. Built for LLM agents to talk to you, with offline system TTS when no API key is configured.
+Project-URL: Homepage, https://github.com/dhruvyad/saynow
+Project-URL: Repository, https://github.com/dhruvyad/saynow
+Project-URL: Issues, https://github.com/dhruvyad/saynow/issues
+Author-email: Dhruv Yadav <dhruvyadav1806@gmail.com>
+License: MIT
+Keywords: agent,cli,llm,say,speech,text-to-speech,tts,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# saynow
+
+Speak text aloud from the terminal. Built so LLM agents can talk to you.
+
+```bash
+saynow "the build finished, 42 tests passed"
+```
+
+Works with no configuration at all — it falls back to your operating system's
+built-in voice, which is offline, free, and needs no API key. Configure a cloud
+provider when you want it to sound good.
+
+## Status: not published to PyPI
+
+The shipping build of saynow is [the npm package](https://www.npmjs.com/package/saynow).
+This Python port is a complete, working equivalent that lives in the repo but is
+deliberately unpublished — maintaining two implementations in lockstep is a cost
+worth paying only once someone actually needs the Python one.
+
+The name is available on PyPI, so it can be published at any time. Open an issue
+if you want it.
+
+## Install from source
+
+```bash
+git clone https://github.com/dhruvyad/saynow
+uv tool install ./saynow/python
+```
+
+No third-party dependencies — it uses only the standard library. Both builds
+read the same config file, so they are interchangeable on one machine.
+
+## Usage
+
+```bash
+saynow "text to speak"             # speak an argument
+echo "text" | saynow               # speak stdin
+pytest 2>&1 | tail -1 | saynow     # speak the last line of a command
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `-v, --voice <name>` | Voice to use — see `saynow voices` |
+| `-p, --provider <id>` | `system`, `openai`, or `elevenlabs` |
+| `-r, --rate <n>` | Words per minute (system provider) |
+| `-s, --speed <n>` | Playback speed 0.25–4.0 (cloud providers) |
+| `--save <file>` | Write audio to a file instead of playing it |
+| `--no-queue` | Speak immediately, overlapping in-flight speech |
+| `--strict` | Fail rather than falling back to the system voice |
+| `-q, --quiet` | Suppress warnings on stderr |
+
+## Configuration
+
+```bash
+saynow init          # interactive setup
+saynow config list   # show settings, API keys redacted
+saynow config set provider openai
+```
+
+Config is stored at `~/.config/saynow/config.json` with `0600` permissions.
+Precedence is **defaults → config file → environment → flags**.
+
+API keys are never accepted as command-line flags — argv is visible in shell
+history and to `ps`.
+
+## Providers
+
+| Provider | Quality | Cost | Needs |
+| --- | --- | --- | --- |
+| `system` | Fair | Free | Nothing — built into the OS |
+| `openai` | Good | Paid | `OPENAI_API_KEY` |
+| `elevenlabs` | Best | Paid | `ELEVENLABS_API_KEY` |
+
+If a cloud provider is selected but no key is available, `saynow` warns on stderr
+and speaks with the system voice anyway. Pass `--strict` to opt out.
+
+## Using it from an agent
+
+Add this to your `CLAUDE.md`, `AGENTS.md`, or equivalent:
+
+```markdown
+You can speak to the user out loud with `saynow "<text>"`. Use it for things
+worth interrupting for: a long task finishing, a question that blocks progress,
+or an error that needs attention. Keep it to one short sentence — it is spoken
+aloud, not read. Do not narrate routine progress.
+```
+
+Concurrent invocations are serialized with a lock file, so three calls in a row
+produce three sentences rather than one muddle.
+
+## License
+
+MIT — source at <https://github.com/dhruvyad/saynow>

saynow-0.1.0/README.md

@@ -0,0 +1,93 @@
+# saynow
+
+Speak text aloud from the terminal. Built so LLM agents can talk to you.
+
+```bash
+saynow "the build finished, 42 tests passed"
+```
+
+Works with no configuration at all — it falls back to your operating system's
+built-in voice, which is offline, free, and needs no API key. Configure a cloud
+provider when you want it to sound good.
+
+## Status: not published to PyPI
+
+The shipping build of saynow is [the npm package](https://www.npmjs.com/package/saynow).
+This Python port is a complete, working equivalent that lives in the repo but is
+deliberately unpublished — maintaining two implementations in lockstep is a cost
+worth paying only once someone actually needs the Python one.
+
+The name is available on PyPI, so it can be published at any time. Open an issue
+if you want it.
+
+## Install from source
+
+```bash
+git clone https://github.com/dhruvyad/saynow
+uv tool install ./saynow/python
+```
+
+No third-party dependencies — it uses only the standard library. Both builds
+read the same config file, so they are interchangeable on one machine.
+
+## Usage
+
+```bash
+saynow "text to speak"             # speak an argument
+echo "text" | saynow               # speak stdin
+pytest 2>&1 | tail -1 | saynow     # speak the last line of a command
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `-v, --voice <name>` | Voice to use — see `saynow voices` |
+| `-p, --provider <id>` | `system`, `openai`, or `elevenlabs` |
+| `-r, --rate <n>` | Words per minute (system provider) |
+| `-s, --speed <n>` | Playback speed 0.25–4.0 (cloud providers) |
+| `--save <file>` | Write audio to a file instead of playing it |
+| `--no-queue` | Speak immediately, overlapping in-flight speech |
+| `--strict` | Fail rather than falling back to the system voice |
+| `-q, --quiet` | Suppress warnings on stderr |
+
+## Configuration
+
+```bash
+saynow init          # interactive setup
+saynow config list   # show settings, API keys redacted
+saynow config set provider openai
+```
+
+Config is stored at `~/.config/saynow/config.json` with `0600` permissions.
+Precedence is **defaults → config file → environment → flags**.
+
+API keys are never accepted as command-line flags — argv is visible in shell
+history and to `ps`.
+
+## Providers
+
+| Provider | Quality | Cost | Needs |
+| --- | --- | --- | --- |
+| `system` | Fair | Free | Nothing — built into the OS |
+| `openai` | Good | Paid | `OPENAI_API_KEY` |
+| `elevenlabs` | Best | Paid | `ELEVENLABS_API_KEY` |
+
+If a cloud provider is selected but no key is available, `saynow` warns on stderr
+and speaks with the system voice anyway. Pass `--strict` to opt out.
+
+## Using it from an agent
+
+Add this to your `CLAUDE.md`, `AGENTS.md`, or equivalent:
+
+```markdown
+You can speak to the user out loud with `saynow "<text>"`. Use it for things
+worth interrupting for: a long task finishing, a question that blocks progress,
+or an error that needs attention. Keep it to one short sentence — it is spoken
+aloud, not read. Do not narrate routine progress.
+```
+
+Concurrent invocations are serialized with a lock file, so three calls in a row
+produce three sentences rather than one muddle.
+
+## License
+
+MIT — source at <https://github.com/dhruvyad/saynow>

saynow-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "saynow"
+version = "0.1.0"
+description = "Speak text aloud from the terminal. Built for LLM agents to talk to you, with offline system TTS when no API key is configured."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Dhruv Yadav", email = "dhruvyadav1806@gmail.com" }]
+keywords = ["tts", "text-to-speech", "cli", "speech", "say", "voice", "agent", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/dhruvyad/saynow"
+Repository = "https://github.com/dhruvyad/saynow"
+Issues = "https://github.com/dhruvyad/saynow/issues"
+
+[project.scripts]
+saynow = "saynow.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/saynow"]

saynow-0.1.0/src/saynow/__init__.py

@@ -0,0 +1,5 @@
+"""saynow — speak text aloud from the terminal."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

saynow-0.1.0/src/saynow/audio.py

@@ -0,0 +1,101 @@
+"""Audio playback and cross-process serialization of speech."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+PLAYERS = {
+    "darwin": [("afplay", lambda f: [f])],
+    "linux": [
+        ("ffplay", lambda f: ["-nodisp", "-autoexit", "-loglevel", "quiet", f]),
+        ("mpv", lambda f: ["--no-video", "--really-quiet", f]),
+        ("mpg123", lambda f: ["-q", f]),
+        ("paplay", lambda f: [f]),
+        ("aplay", lambda f: ["-q", f]),
+    ],
+}
+
+LOCK_PATH = Path(tempfile.gettempdir()) / "saynow.lock"
+STALE_SECONDS = 300
+
+
+def find_player():
+    for name, args in PLAYERS.get(sys.platform, []):
+        if shutil.which(name):
+            return name, args
+    return None
+
+
+def play(path: str) -> None:
+    found = find_player()
+    if not found:
+        tried = ", ".join(n for n, _ in PLAYERS.get(sys.platform, [])) or sys.platform
+        raise SystemExit(
+            f"saynow: no audio player found (looked for: {tried}).\n"
+            "Install one, or use --save <file> to write the audio instead."
+        )
+    name, args = found
+    result = subprocess.run([name, *args(path)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    if result.returncode != 0:
+        raise SystemExit(f"saynow: {name} exited with code {result.returncode}")
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def _clear_if_stale() -> None:
+    try:
+        holder = json.loads(LOCK_PATH.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return
+    except (json.JSONDecodeError, OSError):
+        LOCK_PATH.unlink(missing_ok=True)
+        return
+
+    expired = time.time() - holder.get("at", 0) > STALE_SECONDS
+    if expired or not _alive(holder.get("pid", -1)):
+        LOCK_PATH.unlink(missing_ok=True)
+
+
+@contextmanager
+def queued(enabled: bool = True, timeout: float = 120.0):
+    """Serialize playback so concurrent invocations never overlap."""
+    if not enabled:
+        yield
+        return
+
+    deadline = time.time() + timeout
+    while True:
+        try:
+            fd = os.open(str(LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.write(fd, json.dumps({"pid": os.getpid(), "at": time.time()}).encode())
+            os.close(fd)
+            break
+        except FileExistsError:
+            _clear_if_stale()
+            if time.time() > deadline:
+                raise SystemExit(
+                    f"saynow: timed out waiting for another saynow to finish (lock: {LOCK_PATH}).\n"
+                    "Pass --no-queue to speak immediately without waiting."
+                )
+            time.sleep(0.06)
+
+    try:
+        yield
+    finally:
+        LOCK_PATH.unlink(missing_ok=True)

saynow-0.1.0/src/saynow/cli.py

@@ -0,0 +1,255 @@
+"""Command-line interface for saynow."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import __version__, config as cfg, providers
+from .audio import play, queued
+
+SUBCOMMANDS = {"init", "config", "voices", "help"}
+
+EPILOG = f"""
+config:
+  saynow config list            Show current settings (keys redacted)
+  saynow config get <key>
+  saynow config set <key> <val>
+  saynow config path            Print the config file location
+
+  Config lives at {cfg.config_path()} with 0600 permissions.
+  Precedence: defaults < config file < environment < flags.
+  Keys: provider, voice, model, speed, openaiApiKey, elevenlabsApiKey
+  Env:  SAYNOW_PROVIDER, SAYNOW_VOICE, SAYNOW_MODEL, SAYNOW_SPEED,
+        OPENAI_API_KEY, ELEVENLABS_API_KEY
+
+notes:
+  With no provider configured, saynow uses the built-in OS voice — offline,
+  no API key, works out of the box. Configure a cloud provider for better
+  audio quality. Concurrent invocations are queued so speech never overlaps.
+
+examples:
+  saynow "the build finished"
+  saynow -p openai -v nova "tests passed, 42 of 42"
+  saynow --save note.mp3 "long form text"
+  pytest 2>&1 | tail -1 | saynow
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="saynow",
+        description="Speak text aloud from the terminal.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument("text", nargs="*", help="text to speak (or pipe it on stdin)")
+    parser.add_argument("-v", "--voice", help="voice to use (see: saynow voices)")
+    parser.add_argument(
+        "-p", "--provider", choices=sorted(providers.PROVIDERS), help="speech provider"
+    )
+    parser.add_argument("-r", "--rate", type=float, help="words per minute (system provider)")
+    parser.add_argument("-s", "--speed", type=float, help="speed 0.25-4.0 (cloud providers)")
+    parser.add_argument("--save", metavar="FILE", help="write audio to a file instead of playing")
+    parser.add_argument(
+        "--no-queue", action="store_true", help="speak immediately, overlapping in-flight speech"
+    )
+    parser.add_argument(
+        "--strict", action="store_true", help="fail instead of falling back to the system voice"
+    )
+    parser.add_argument("-q", "--quiet", action="store_true", help="suppress warnings on stderr")
+    parser.add_argument("--version", action="version", version=__version__)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.text and args.text[0] in SUBCOMMANDS:
+        command, rest = args.text[0], args.text[1:]
+        if command == "help":
+            parser.print_help()
+            return 0
+        if command == "init":
+            return init_command()
+        if command == "config":
+            return config_command(rest)
+        if command == "voices":
+            return voices_command(args)
+
+    text = " ".join(args.text) if args.text else read_stdin()
+    if not text.strip():
+        parser.error("nothing to say. Pass text as an argument or pipe it on stdin.")
+
+    return speak(text.strip(), args)
+
+
+def read_stdin() -> str:
+    if sys.stdin.isatty():
+        return ""
+    return sys.stdin.read()
+
+
+def speak(text: str, args: argparse.Namespace) -> int:
+    """Always make a sound: degrade to the offline voice rather than failing."""
+    config = cfg.resolve(
+        provider=args.provider, voice=args.voice, model=None, speed=args.speed
+    )
+    provider_id = config["provider"]
+    selected = providers.get(provider_id)
+    key = cfg.api_key(provider_id, config)
+
+    if not selected["speaks_directly"] and not key:
+        if args.strict:
+            raise SystemExit(
+                f"saynow: provider \"{provider_id}\" needs a key but none was found. "
+                f"Set {selected['env_var']} or run: saynow init"
+            )
+        warn(
+            args,
+            f"no {selected['env_var']} found — using the offline system voice. "
+            f"Run `saynow init` to configure {provider_id}.",
+        )
+        provider_id, key = "system", None
+
+    if provider_id == "system":
+        if args.save:
+            raise SystemExit(
+                "saynow: --save is not supported by the system provider. "
+                "Configure openai or elevenlabs to write audio files."
+            )
+        with queued(enabled=not args.no_queue):
+            providers.speak_system(text, voice=config.get("voice"), rate=args.rate)
+        return 0
+
+    audio = providers.SYNTHESIZERS[provider_id](
+        text,
+        api_key=key,
+        voice=config.get("voice"),
+        model=config.get("model"),
+        speed=config.get("speed"),
+    )
+
+    if args.save:
+        Path(args.save).write_bytes(audio)
+        if not args.quiet:
+            print(os.path.abspath(args.save))
+        return 0
+
+    tmp = Path(tempfile.gettempdir()) / f"saynow-{os.getpid()}.mp3"
+    tmp.write_bytes(audio)
+    os.chmod(tmp, 0o600)
+    try:
+        with queued(enabled=not args.no_queue):
+            play(str(tmp))
+    finally:
+        tmp.unlink(missing_ok=True)
+    return 0
+
+
+def init_command() -> int:
+    print("Configure saynow. Press enter to keep the current value.\n")
+    for name, meta in providers.PROVIDERS.items():
+        print(f"  {name:<12} {meta['label']}")
+    print()
+
+    config = cfg.load()
+    chosen = input(f"Provider [{config['provider']}]: ").strip() or config["provider"]
+    meta = providers.get(chosen)
+    config["provider"] = chosen
+
+    if not meta["speaks_directly"]:
+        existing = config.get(meta["config_key"])
+        prompt = (
+            f"API key [{cfg.redact(existing)}]: "
+            if existing
+            else f"API key (or leave blank to use ${meta['env_var']}): "
+        )
+        entered = input(prompt).strip()
+        if entered:
+            config[meta["config_key"]] = entered
+
+    voice = input(f"Voice [{config.get('voice') or 'default'}]: ").strip()
+    if voice:
+        config["voice"] = voice
+
+    cfg.save(config)
+    print(f"\nSaved to {cfg.config_path()} (mode 0600).")
+
+    if not meta["speaks_directly"] and not cfg.api_key(chosen, config):
+        print(
+            f"\nNo key stored and ${meta['env_var']} is unset — "
+            "saynow will use the offline system voice until one is available."
+        )
+    return 0
+
+
+def config_command(rest: List[str]) -> int:
+    action = rest[0] if rest else "list"
+    config: Dict[str, Any] = cfg.load()
+
+    if action == "path":
+        print(cfg.config_path())
+        return 0
+
+    if action == "list":
+        width = max(len(k) for k in config)
+        for key, value in config.items():
+            shown = cfg.redact(value) if key in cfg.SECRET_KEYS else value
+            print(f"{key:<{width}}  {shown}")
+        if not cfg.config_path().exists():
+            print("\n(no config file yet — these are defaults. Run `saynow init`.)")
+        return 0
+
+    if action == "get":
+        if len(rest) < 2:
+            raise SystemExit("saynow: usage: saynow config get <key>")
+        key = rest[1]
+        if key not in config:
+            raise SystemExit(f"saynow: no such key: {key}")
+        print(cfg.redact(config[key]) if key in cfg.SECRET_KEYS else config[key])
+        return 0
+
+    if action == "set":
+        if len(rest) < 3:
+            raise SystemExit("saynow: usage: saynow config set <key> <value>")
+        key, value = rest[1], " ".join(rest[2:])
+        if key == "provider":
+            providers.get(value)
+        config[key] = float(value) if key in {"speed", "rate"} else value
+        cfg.save(config)
+        shown = cfg.redact(value) if key in cfg.SECRET_KEYS else config[key]
+        print(f"{key} = {shown}")
+        return 0
+
+    raise SystemExit(f"saynow: unknown config command \"{action}\". Use: list, get, set, path")
+
+
+def voices_command(args: argparse.Namespace) -> int:
+    config = cfg.resolve(provider=args.provider)
+    provider_id = config["provider"]
+    listed = providers.voices(provider_id, cfg.api_key(provider_id, config))
+
+    if not listed:
+        print(f"No voices listed for provider \"{provider_id}\".")
+        return 0
+
+    width = max(len(name) for name, _, _ in listed)
+    for name, locale, note in listed:
+        print(f"{name:<{width}}  {locale:<8} {note}".rstrip())
+    return 0
+
+
+def warn(args: argparse.Namespace, message: str) -> None:
+    if not args.quiet:
+        print(f"saynow: {message}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

saynow-0.1.0/src/saynow/config.py

@@ -0,0 +1,91 @@
+"""Configuration storage, shared on disk with the npm build of saynow."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+SECRET_KEYS = {"openaiApiKey", "elevenlabsApiKey"}
+
+DEFAULTS: Dict[str, Any] = {
+    "provider": "system",
+    "voice": None,
+    "model": None,
+    "speed": 1,
+}
+
+
+def config_dir() -> Path:
+    override = os.environ.get("SAYNOW_CONFIG_DIR")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path.home() / ".config" / "saynow"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> Dict[str, Any]:
+    path = config_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return dict(DEFAULTS)
+    except json.JSONDecodeError as err:
+        raise SystemExit(f"saynow: config at {path} is not valid JSON: {err}")
+    merged = dict(DEFAULTS)
+    merged.update(data)
+    return merged
+
+
+def save(config: Dict[str, Any]) -> None:
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    os.chmod(directory, 0o700)
+
+    path = config_path()
+    # Write to a temp file first so a crash can't truncate an existing config.
+    tmp = path.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+    os.chmod(path, 0o600)
+
+
+def resolve(**flags: Any) -> Dict[str, Any]:
+    """Layer the sources: defaults < config file < environment < CLI flags."""
+    config = load()
+
+    env_map = {
+        "provider": "SAYNOW_PROVIDER",
+        "voice": "SAYNOW_VOICE",
+        "model": "SAYNOW_MODEL",
+        "speed": "SAYNOW_SPEED",
+    }
+    for key, var in env_map.items():
+        value = os.environ.get(var)
+        if value:
+            config[key] = float(value) if key == "speed" else value
+
+    config.update({k: v for k, v in flags.items() if v is not None})
+    return config
+
+
+def api_key(provider: str, config: Optional[Dict[str, Any]] = None) -> Optional[str]:
+    """Environment wins over the config file so a shell can override it."""
+    if config is None:
+        config = load()
+    if provider == "openai":
+        return os.environ.get("OPENAI_API_KEY") or config.get("openaiApiKey")
+    if provider == "elevenlabs":
+        return os.environ.get("ELEVENLABS_API_KEY") or config.get("elevenlabsApiKey")
+    return None
+
+
+def redact(value: Any) -> str:
+    if not isinstance(value, str) or len(value) <= 8:
+        return "****"
+    return f"{value[:4]}…{value[-4:]}"

saynow-0.1.0/src/saynow/providers.py

@@ -0,0 +1,226 @@
+"""Speech providers: the offline system voice plus cloud backends."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional, Tuple
+
+OPENAI_VOICES = [
+    "alloy", "ash", "ballad", "coral", "echo",
+    "fable", "nova", "onyx", "sage", "shimmer",
+]
+
+ELEVENLABS_DEFAULT_VOICE = "21m00Tcm4TlvDq8ikWAM"  # "Rachel", the default public voice
+
+PROVIDERS: Dict[str, Dict[str, Any]] = {
+    "system": {
+        "label": "built-in OS speech synthesis (offline, no API key)",
+        "speaks_directly": True,
+        "env_var": None,
+        "config_key": None,
+    },
+    "openai": {
+        "label": "OpenAI /v1/audio/speech",
+        "speaks_directly": False,
+        "env_var": "OPENAI_API_KEY",
+        "config_key": "openaiApiKey",
+    },
+    "elevenlabs": {
+        "label": "ElevenLabs text-to-speech",
+        "speaks_directly": False,
+        "env_var": "ELEVENLABS_API_KEY",
+        "config_key": "elevenlabsApiKey",
+    },
+}
+
+
+def get(provider_id: str) -> Dict[str, Any]:
+    if provider_id not in PROVIDERS:
+        raise SystemExit(
+            f"saynow: unknown provider \"{provider_id}\". "
+            f"Available: {', '.join(PROVIDERS)}"
+        )
+    return PROVIDERS[provider_id]
+
+
+# --- system -----------------------------------------------------------------
+
+def _system_command(text: str, voice: Optional[str], rate: Optional[float]) -> List[str]:
+    if sys.platform == "darwin":
+        cmd = ["say"]
+        if voice:
+            cmd += ["-v", voice]
+        if rate:
+            cmd += ["-r", str(int(rate))]
+        return cmd + ["--", text]
+
+    if sys.platform.startswith("linux"):
+        binary = "espeak-ng" if shutil.which("espeak-ng") else "espeak"
+        cmd = [binary]
+        if voice:
+            cmd += ["-v", voice]
+        if rate:
+            cmd += ["-s", str(int(rate))]
+        return cmd + ["--", text]
+
+    if sys.platform == "win32":
+        escaped = text.replace("'", "''")
+        script = (
+            "Add-Type -AssemblyName System.Speech;"
+            "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer;"
+        )
+        if voice:
+            script += f"$s.SelectVoice('{voice}');"
+        if rate:
+            script += f"$s.Rate = {max(-10, min(10, int(rate)))};"
+        script += f"$s.Speak('{escaped}')"
+        return ["powershell", "-NoProfile", "-Command", script]
+
+    raise SystemExit(f"saynow: no system speech backend known for platform \"{sys.platform}\"")
+
+
+def speak_system(text: str, voice: Optional[str] = None, rate: Optional[float] = None) -> None:
+    cmd = _system_command(text, voice, rate)
+    try:
+        result = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except FileNotFoundError:
+        raise SystemExit(
+            f"saynow: \"{cmd[0]}\" not found. On Linux install espeak-ng "
+            "(apt install espeak-ng), or configure a cloud provider with: saynow init"
+        )
+    if result.returncode != 0:
+        raise SystemExit(f"saynow: {cmd[0]} exited with code {result.returncode}")
+
+
+def system_voices() -> List[Tuple[str, str, str]]:
+    if sys.platform == "darwin":
+        out = subprocess.run(["say", "-v", "?"], capture_output=True, text=True)
+        if out.returncode != 0:
+            return []
+        voices = []
+        for line in out.stdout.splitlines():
+            parts = line.split("#", 1)
+            head = parts[0].rstrip()
+            note = parts[1].strip() if len(parts) > 1 else ""
+            bits = head.rsplit(None, 1)
+            if len(bits) == 2:
+                voices.append((bits[0].strip(), bits[1], note))
+        return voices
+
+    if sys.platform.startswith("linux"):
+        binary = "espeak-ng" if shutil.which("espeak-ng") else "espeak"
+        out = subprocess.run([binary, "--voices"], capture_output=True, text=True)
+        if out.returncode != 0:
+            return []
+        voices = []
+        for line in out.stdout.splitlines()[1:]:
+            parts = line.split()
+            if len(parts) >= 4:
+                voices.append((parts[3], parts[1], ""))
+        return voices
+
+    return []
+
+
+# --- cloud ------------------------------------------------------------------
+
+def _post(url: str, headers: Dict[str, str], body: Dict[str, Any], provider: str) -> bytes:
+    request = urllib.request.Request(
+        url, data=json.dumps(body).encode("utf-8"), headers=headers, method="POST"
+    )
+    try:
+        with urllib.request.urlopen(request) as response:
+            return response.read()
+    except urllib.error.HTTPError as err:
+        detail = err.read().decode("utf-8", "replace")[:300]
+        if err.code == 401:
+            raise SystemExit(
+                f"saynow: {provider} rejected the API key (401). Check it with: saynow config list"
+            )
+        if err.code == 429:
+            raise SystemExit(f"saynow: {provider} rate limited or out of quota (429). {detail}")
+        raise SystemExit(f"saynow: {provider} request failed ({err.code}). {detail}")
+    except urllib.error.URLError as err:
+        raise SystemExit(f"saynow: could not reach {provider}: {err.reason}")
+
+
+def synthesize_openai(
+    text: str,
+    api_key: str,
+    voice: Optional[str] = None,
+    model: Optional[str] = None,
+    speed: Optional[float] = None,
+) -> bytes:
+    body: Dict[str, Any] = {
+        "model": model or "gpt-4o-mini-tts",
+        "voice": voice or "alloy",
+        "input": text,
+        "response_format": "mp3",
+    }
+    # Only the tts-1 family accepts `speed`; sending it otherwise is a 400.
+    if speed and speed != 1:
+        body["speed"] = speed
+
+    return _post(
+        "https://api.openai.com/v1/audio/speech",
+        {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        body,
+        "OpenAI",
+    )
+
+
+def synthesize_elevenlabs(
+    text: str,
+    api_key: str,
+    voice: Optional[str] = None,
+    model: Optional[str] = None,
+    speed: Optional[float] = None,
+) -> bytes:
+    body: Dict[str, Any] = {"text": text, "model_id": model or "eleven_turbo_v2_5"}
+    if speed and speed != 1:
+        body["voice_settings"] = {"speed": speed}
+
+    return _post(
+        f"https://api.elevenlabs.io/v1/text-to-speech/{voice or ELEVENLABS_DEFAULT_VOICE}",
+        {"xi-api-key": api_key, "Content-Type": "application/json", "Accept": "audio/mpeg"},
+        body,
+        "ElevenLabs",
+    )
+
+
+SYNTHESIZERS = {
+    "openai": synthesize_openai,
+    "elevenlabs": synthesize_elevenlabs,
+}
+
+
+def voices(provider_id: str, api_key: Optional[str] = None) -> List[Tuple[str, str, str]]:
+    if provider_id == "system":
+        return system_voices()
+    if provider_id == "openai":
+        return [(name, "multi", "") for name in OPENAI_VOICES]
+    if provider_id == "elevenlabs":
+        if not api_key:
+            return []
+        request = urllib.request.Request(
+            "https://api.elevenlabs.io/v1/voices", headers={"xi-api-key": api_key}
+        )
+        try:
+            with urllib.request.urlopen(request) as response:
+                payload = json.loads(response.read())
+        except (urllib.error.URLError, json.JSONDecodeError):
+            return []
+        return [
+            (
+                f"{v['name']}  ({v['voice_id']})",
+                (v.get("labels") or {}).get("accent", "multi"),
+                (v.get("labels") or {}).get("description", ""),
+            )
+            for v in payload.get("voices", [])
+        ]
+    return []