speak-cli 1.2.0__tar.gz → 1.3.0__tar.gz

{speak_cli-1.2.0 → speak_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: speak-cli
-Version: 1.2.0
+Version: 1.3.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
@@ -51,6 +51,23 @@ ollama run llama3 "tell a story" | speak --live   # voice for your LLM
 ```
 **Note:** `say` also works as an alias.
 
+## Use from Python
+
+The same engine is available as a library — add `speak-cli` to your project (`uv add speak-cli` / `pip install speak-cli`) and:
+
+```python
+from speak_cli import Speaker, say
+
+say("hello world")                      # one-liner: synthesize and play
+
+speaker = Speaker(voice="noah", speed=1.1)   # model loads once, reuse it
+speaker.say("long texts stream, so they start speaking instantly")
+wav_bytes = speaker.synthesize("raw 44.1 kHz WAV bytes")
+speaker.save("مرحبا بالعالم", "clip.wav")    # language auto-detected per call
+```
+
+Per-call overrides work everywhere: `speaker.say("bonjour", lang="fr", speed=0.9)`.
+
 ## Voices
 
 Ten voices, picked by name (`speak --list-voices`):

{speak_cli-1.2.0 → speak_cli-1.3.0}/README.md

@@ -28,6 +28,23 @@ ollama run llama3 "tell a story" | speak --live   # voice for your LLM
 ```
 **Note:** `say` also works as an alias.
 
+## Use from Python
+
+The same engine is available as a library — add `speak-cli` to your project (`uv add speak-cli` / `pip install speak-cli`) and:
+
+```python
+from speak_cli import Speaker, say
+
+say("hello world")                      # one-liner: synthesize and play
+
+speaker = Speaker(voice="noah", speed=1.1)   # model loads once, reuse it
+speaker.say("long texts stream, so they start speaking instantly")
+wav_bytes = speaker.synthesize("raw 44.1 kHz WAV bytes")
+speaker.save("مرحبا بالعالم", "clip.wav")    # language auto-detected per call
+```
+
+Per-call overrides work everywhere: `speaker.say("bonjour", lang="fr", speed=0.9)`.
+
 ## Voices
 
 Ten voices, picked by name (`speak --list-voices`):

speak_cli-1.3.0/src/speak_cli/__init__.py

@@ -0,0 +1,20 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("speak-cli")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = ["Speaker", "say", "synthesize", "save", "list_voices", "__version__"]
+
+_API_NAMES = {"Speaker", "say", "synthesize", "save", "list_voices"}
+
+
+def __getattr__(name: str):
+    # PEP 562 lazy exports: `import speak_cli` stays instant; the API module
+    # (and eventually onnxruntime) loads only when actually used.
+    if name in _API_NAMES:
+        from . import api
+
+        return getattr(api, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

speak_cli-1.3.0/src/speak_cli/api.py

@@ -0,0 +1,124 @@
+"""Public Python API for speak-cli.
+
+    from speak_cli import Speaker, say
+
+    say("hello world")                     # one-liner: synthesize and play
+
+    s = Speaker(voice="noah", speed=1.1)   # reusable: model loads once
+    s.say("fast repeat calls")
+    wav = s.synthesize("raw 44.1kHz WAV bytes")
+    s.save("save to disk", "clip.wav")
+
+Everything runs in-process (no daemon); create one Speaker and reuse it to
+keep the models warm. All heavy imports happen on first synthesis, so
+importing this module is instant.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .langdetect import SUPPORTED_LANGS, detect_lang
+from .voices import VOICES, resolve
+
+
+def list_voices() -> list[str]:
+    """Names of the available voices."""
+    return list(VOICES)
+
+
+class Speaker:
+    """Reusable text-to-speech engine with a fixed default voice and pace.
+
+    Per-call keyword arguments override the constructor defaults.
+    """
+
+    def __init__(self, voice: str = "sara", speed: float = 1.0,
+                 steps: int = 8, lang: str = "auto") -> None:
+        self.voice = resolve(voice)[0]  # fail fast on unknown names
+        self.speed = speed
+        self.steps = steps
+        self.lang = lang
+        self._engine = None
+
+    def _resolve(self, text: str, voice: str | None, speed: float | None,
+                 lang: str | None, steps: int | None) -> dict:
+        from .chunker import clean
+
+        text = clean(text).strip()
+        if not text:
+            raise ValueError("no text to speak")
+        lang = (lang or self.lang).lower()
+        if lang == "auto":
+            lang = detect_lang(text)
+        if lang not in SUPPORTED_LANGS:
+            raise ValueError(
+                f"unsupported language {lang!r}; supported: "
+                + " ".join(sorted(SUPPORTED_LANGS))
+            )
+        return {
+            "text": text,
+            "voice": resolve(voice)[1] if voice else resolve(self.voice)[1],
+            "speed": speed if speed is not None else self.speed,
+            "lang": lang,
+            "steps": steps if steps is not None else self.steps,
+        }
+
+    def _synth(self, req: dict) -> bytes:
+        if self._engine is None:
+            from .engine import Engine
+
+            self._engine = Engine()
+        wav, _ = self._engine.synthesize(**req)
+        return wav
+
+    def synthesize(self, text: str, *, voice: str | None = None,
+                   speed: float | None = None, lang: str | None = None,
+                   steps: int | None = None) -> bytes:
+        """Synthesize speech; returns a complete 44.1kHz 16-bit WAV as bytes."""
+        return self._synth(self._resolve(text, voice, speed, lang, steps))
+
+    def say(self, text: str, *, voice: str | None = None,
+            speed: float | None = None, lang: str | None = None,
+            steps: int | None = None) -> None:
+        """Speak text through the speakers, streaming so long texts start fast."""
+        from .chunker import chunks
+        from .playback import stream_play
+
+        req = self._resolve(text, voice, speed, lang, steps)
+        pieces = ((p, req["lang"]) for p in chunks(req["text"]))
+        stream_play(
+            pieces,
+            lambda t, lang: self._synth({**req, "text": t, "lang": lang}),
+        )
+
+    def save(self, text: str, path: str | Path, **kwargs) -> Path:
+        """Synthesize speech and write it to a WAV file; returns the path."""
+        path = Path(path)
+        path.write_bytes(self.synthesize(text, **kwargs))
+        return path
+
+
+_default_speaker: Speaker | None = None
+
+
+def _default() -> Speaker:
+    global _default_speaker
+    if _default_speaker is None:
+        _default_speaker = Speaker()
+    return _default_speaker
+
+
+def say(text: str, **kwargs) -> None:
+    """Speak text out loud using a shared default Speaker."""
+    _default().say(text, **kwargs)
+
+
+def synthesize(text: str, **kwargs) -> bytes:
+    """Return speech for `text` as WAV bytes, using a shared default Speaker."""
+    return _default().synthesize(text, **kwargs)
+
+
+def save(text: str, path: str | Path, **kwargs) -> Path:
+    """Write speech for `text` to a WAV file, using a shared default Speaker."""
+    return _default().save(text, path, **kwargs)

{speak_cli-1.2.0 → speak_cli-1.3.0}/src/speak_cli/cli.py

@@ -3,9 +3,7 @@
 from __future__ import annotations
 
 import argparse
-import queue
 import sys
-import threading
 from collections.abc import Iterable
 
 from . import __version__, voices
@@ -122,28 +120,9 @@ class Synth:
 
 def _stream_speak(pieces: Iterable[tuple[str, str | None]], synth: Synth,
                   verbose: bool) -> None:
-    """Play piece N while piece N+1 synthesizes. Pieces are (text, lang)."""
-    from .playback import play
+    from .playback import stream_play
 
-    q: queue.Queue = queue.Queue(maxsize=3)
-    errors: list[Exception] = []
-
-    def produce() -> None:
-        try:
-            for text, lang in pieces:
-                q.put(synth(text, lang))
-        except Exception as e:
-            errors.append(e)
-        finally:
-            q.put(None)
-
-    t = threading.Thread(target=produce, daemon=True)
-    t.start()
-    while (wav := q.get()) is not None:
-        play(wav, verbose=verbose)
-    t.join()
-    if errors:
-        raise errors[0]
+    stream_play(pieces, synth, verbose=verbose)
 
 
 def main(argv: list[str] | None = None) -> int:

{speak_cli-1.2.0 → speak_cli-1.3.0}/src/speak_cli/playback.py

@@ -74,6 +74,36 @@ def _play_players(path: str, errors: list[str]) -> str | None:
     return None
 
 
+def stream_play(pieces, synth_fn, verbose: bool = False) -> None:
+    """Play piece N while piece N+1 synthesizes.
+
+    `pieces` yields (text, lang) tuples; `synth_fn(text, lang)` returns WAV
+    bytes. Used by both the CLI and the library API for instant-start speech.
+    """
+    import queue
+    import threading
+
+    q: queue.Queue = queue.Queue(maxsize=3)
+    errors: list[Exception] = []
+
+    def produce() -> None:
+        try:
+            for text, lang in pieces:
+                q.put(synth_fn(text, lang))
+        except Exception as e:
+            errors.append(e)
+        finally:
+            q.put(None)
+
+    t = threading.Thread(target=produce, daemon=True)
+    t.start()
+    while (wav := q.get()) is not None:
+        play(wav, verbose=verbose)
+    t.join()
+    if errors:
+        raise errors[0]
+
+
 def play(wav_bytes: bytes, verbose: bool = False) -> None:
     """Play WAV bytes; raises PlaybackError if nothing works."""
     errors: list[str] = []

speak_cli-1.3.0/tests/test_api.py

@@ -0,0 +1,57 @@
+import pytest
+
+import speak_cli
+from speak_cli.api import Speaker, list_voices
+from speak_cli.engine import models_cached
+
+
+def test_lazy_exports():
+    assert callable(speak_cli.say)
+    assert callable(speak_cli.synthesize)
+    assert speak_cli.Speaker is Speaker
+    with pytest.raises(AttributeError):
+        speak_cli.nonexistent
+
+
+def test_list_voices():
+    voices = list_voices()
+    assert "sara" in voices and "noah" in voices
+    assert len(voices) == 10
+
+
+def test_unknown_voice_fails_fast():
+    with pytest.raises(ValueError, match="unknown voice"):
+        Speaker(voice="bogus")
+
+
+def test_empty_text_rejected():
+    with pytest.raises(ValueError, match="no text"):
+        Speaker()._resolve("  \x1b[2K ", None, None, None, None)
+
+
+def test_unsupported_lang_rejected():
+    with pytest.raises(ValueError, match="unsupported language"):
+        Speaker()._resolve("hi", None, None, "xx", None)
+
+
+def test_resolve_defaults_and_overrides():
+    s = Speaker(voice="noah", speed=1.2)
+    req = s._resolve("hello there", None, None, None, None)
+    assert req == {"text": "hello there", "voice": "M5", "speed": 1.2,
+                   "lang": "en", "steps": 8}
+    req = s._resolve("مرحبا", "emma", 0.9, None, 6)
+    assert req["voice"] == "F2" and req["speed"] == 0.9
+    assert req["lang"] == "ar" and req["steps"] == 6
+
+
+@pytest.mark.skipif(not models_cached(), reason="model assets not downloaded")
+def test_synthesize_returns_wav():
+    wav = Speaker().synthesize("library api check", steps=2)
+    assert wav[:4] == b"RIFF" and wav[8:12] == b"WAVE"
+    assert len(wav) > 10_000
+
+
+@pytest.mark.skipif(not models_cached(), reason="model assets not downloaded")
+def test_save_writes_file(tmp_path):
+    out = speak_cli.save("saved from the api", tmp_path / "clip.wav", steps=2)
+    assert out.exists() and out.stat().st_size > 10_000

speak_cli-1.2.0/src/speak_cli/__init__.py

@@ -1,6 +0,0 @@
-from importlib.metadata import PackageNotFoundError, version
-
-try:
-    __version__ = version("speak-cli")
-except PackageNotFoundError:  # running from a source tree without install
-    __version__ = "0.0.0"