sonara-client 0.21.7__tar.gz

sonara_client-0.21.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nima Hakimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sonara_client-0.21.7/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: sonara-client
+Version: 0.21.7
+Summary: Client for the Sonara text-to-speech runtime (protocol v1). Standard library only.
+Maintainer: Max Aubert
+License: MIT
+Project-URL: Homepage, https://github.com/Maxaubert/Sonara
+Project-URL: Documentation, https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sonara-client
+
+Talk to the Sonara text-to-speech runtime from Python 3.9+. Standard library only.
+
+```python
+import sonara_client
+
+with sonara_client.connect("my-app", runtime_path=r"C:\path\to\sonarad.exe") as sonara:
+    item = sonara.speak("Hello.", label="greeting")
+    sonara.set("rate", 240)
+    with sonara.subscribe(["state", "items"]) as events:
+        for e in events:
+            if e["event"] == "item" and e["item_id"] == item and e["phase"] != "started":
+                break
+```
+
+- `connect(client_name, *, runtime_path=None, home=None, autostart=True, require=(), extensions=(), keep_alive=False)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` when none is usable (`runtime_path`, default `SONARA_RUNTIME`), takes over an idle incompatible one.
+- `speak(text, mode=None, interrupt=None, label=None)` returns the item id; `control(action)`; `set(key, value)` / `get(key)`; `voices(engine=None)`.
+- `subscribe(events)` opens an event stream on its own connection: iterate it, or `read(timeout)`.
+- `channels`, `agent`, `system`: extension namespaces that send the protocol's extension messages as they are.
+- Errors are `SonaraError` with a `code`. The client is thread-safe.
+
+Guide: [Bundle Sonara in your app](https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md). Tests: `python -m pytest clients/python/tests -q` (the end-to-end ones need `cargo build -p sonarad`).
+
+MIT. Ship `THIRD_PARTY_NOTICES.md` with an app that bundles the runtime.

sonara_client-0.21.7/README.md

@@ -0,0 +1,25 @@
+# sonara-client
+
+Talk to the Sonara text-to-speech runtime from Python 3.9+. Standard library only.
+
+```python
+import sonara_client
+
+with sonara_client.connect("my-app", runtime_path=r"C:\path\to\sonarad.exe") as sonara:
+    item = sonara.speak("Hello.", label="greeting")
+    sonara.set("rate", 240)
+    with sonara.subscribe(["state", "items"]) as events:
+        for e in events:
+            if e["event"] == "item" and e["item_id"] == item and e["phase"] != "started":
+                break
+```
+
+- `connect(client_name, *, runtime_path=None, home=None, autostart=True, require=(), extensions=(), keep_alive=False)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` when none is usable (`runtime_path`, default `SONARA_RUNTIME`), takes over an idle incompatible one.
+- `speak(text, mode=None, interrupt=None, label=None)` returns the item id; `control(action)`; `set(key, value)` / `get(key)`; `voices(engine=None)`.
+- `subscribe(events)` opens an event stream on its own connection: iterate it, or `read(timeout)`.
+- `channels`, `agent`, `system`: extension namespaces that send the protocol's extension messages as they are.
+- Errors are `SonaraError` with a `code`. The client is thread-safe.
+
+Guide: [Bundle Sonara in your app](https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md). Tests: `python -m pytest clients/python/tests -q` (the end-to-end ones need `cargo build -p sonarad`).
+
+MIT. Ship `THIRD_PARTY_NOTICES.md` with an app that bundles the runtime.

sonara_client-0.21.7/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonara-client"
+version = "0.21.7"
+description = "Client for the Sonara text-to-speech runtime (protocol v1). Standard library only."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+# setuptools ships LICENSE beside this file (a copy of the root one) in
+# the sdist and the wheel by default.
+maintainers = [{ name = "Max Aubert" }]
+# Zero runtime dependencies (spec R6): bundlers ship nothing else's licence.
+dependencies = []
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+
+[project.urls]
+Homepage = "https://github.com/Maxaubert/Sonara"
+Documentation = "https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sonara_client-0.21.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sonara_client-0.21.7/src/sonara_client/__init__.py

@@ -0,0 +1,35 @@
+"""sonara-client: talk to the Sonara runtime (protocol v1). Standard library only.
+
+    import sonara_client
+
+    with sonara_client.connect("my-app", runtime_path=r"C:\\path\\to\\sonarad.exe") as sonara:
+        item = sonara.speak("Hello.")
+        for event in sonara.subscribe(["items"]):
+            if event["item_id"] == item and event["phase"] != "started":
+                break
+"""
+from __future__ import annotations
+
+from .client import Client, Subscription
+from .connect import connect
+from .discovery import read_runtime, resolve_home
+from .engines import SEND_MODES, Engines
+from .errors import SonaraError
+from .extensions import Agent, Channels, System
+from .version import PROTOCOL, __version__
+
+__all__ = [
+    "Agent",
+    "Channels",
+    "Client",
+    "Engines",
+    "PROTOCOL",
+    "SEND_MODES",
+    "SonaraError",
+    "Subscription",
+    "System",
+    "__version__",
+    "connect",
+    "read_runtime",
+    "resolve_home",
+]

sonara_client-0.21.7/src/sonara_client/client.py

@@ -0,0 +1,136 @@
+"""The connected client and its event subscriptions."""
+from __future__ import annotations
+
+import socket
+from typing import Any, Callable, Iterator, List, Optional, Sequence
+
+from .connection import Connection
+from .errors import E_CLOSED, SonaraError
+from .engines import Engines
+from .extensions import Agent, Channels, System
+
+ALL_EVENTS = ("state", "items", "log")
+
+
+class Subscription:
+    """Events on a connection of their own: iterate it, or ``read()`` with a
+    timeout. Each event is a dict whose ``event`` is ``state``, ``item`` or
+    ``log``. Iteration ends when the runtime closes the connection."""
+
+    def __init__(self, conn: Connection):
+        self._conn = conn
+
+    def __iter__(self) -> Iterator[dict]:
+        return self
+
+    def __next__(self) -> dict:
+        event = self._conn.next_event(None)
+        if event is None:
+            raise StopIteration
+        return event
+
+    def read(self, timeout: Optional[float] = None) -> Optional[dict]:
+        """The next event, or None when none arrived within ``timeout``
+        seconds. SonaraError ``E_CLOSED`` once the stream ended."""
+        try:
+            event = self._conn.next_event(timeout)
+        except socket.timeout:
+            return None
+        if event is None:
+            raise SonaraError(E_CLOSED, "the event stream ended")
+        return event
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> "Subscription":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class Client:
+    """A connected Sonara client (see ``connect``). Thread-safe: requests on
+    the shared connection run one at a time."""
+
+    def __init__(self, conn: Connection, runtime: dict, info: dict, dial: Callable[[], Connection]):
+        self._conn = conn
+        self._dial = dial
+        self._subs: List[Subscription] = []
+        #: ``runtime.json`` of the instance this client talks to.
+        self.runtime = runtime
+        #: The ``hello`` reply: version, protocol, capabilities, extensions, unavailable.
+        self.info = info
+        self.channels = Channels(self.request)
+        self.agent = Agent(self.request)
+        self.system = System(self.request)
+        self.engines = Engines(self.request)
+
+    @property
+    def closed(self) -> bool:
+        return self._conn.closed
+
+    def request(self, type_: str, fields: Optional[dict] = None) -> dict:
+        """Send any protocol message; the ``ok: true`` reply."""
+        return self._conn.request(type_, fields)
+
+    def speak(self, text: str, mode: Optional[str] = None, interrupt: Optional[bool] = None,
+              label: Optional[str] = None) -> int:
+        """Add ``text`` as one item; its item id. ``mode``: ``append``
+        (default) or ``replace``; ``interrupt`` also cuts the current item."""
+        fields: dict = {"text": text}
+        if mode is not None:
+            fields["mode"] = mode
+        if interrupt is not None:
+            fields["interrupt"] = interrupt
+        if label is not None:
+            fields["label"] = label
+        return self.request("speak", fields)["item_id"]
+
+    def control(self, action: str) -> None:
+        """play, pause, toggle, stop, skip, previous, next, restart, mute, unmute."""
+        self.request("control", {"action": action})
+
+    def set(self, key: str, value: Any) -> Any:
+        """Change ``volume``, ``rate``, ``voice`` or ``engine``; the value now in force."""
+        return self.request("set", {"key": key, "value": value})["value"]
+
+    def get(self, key: str) -> Any:
+        """Read a setting."""
+        return self.request("get", {"key": key})["value"]
+
+    def voices(self, engine: Optional[str] = None, refresh: bool = False) -> list:
+        """Voices of one engine, or of all. ``refresh`` asks an external
+        engine's provider again (protocol 1.2)."""
+        fields: dict = {} if engine is None else {"engine": engine}
+        if refresh:
+            fields["refresh"] = True
+        return self.request("voices", fields)["voices"]
+
+    def subscribe(self, events: Sequence[str] = ALL_EVENTS) -> Subscription:
+        """Open an event stream (``state``, ``items``, ``log``) on a new
+        connection. When ``state`` is included the first event is the
+        current state."""
+        conn = self._dial()
+        try:
+            conn.request("subscribe", {"events": list(events)})
+        except SonaraError:
+            conn.close()
+            raise
+        sub = Subscription(conn)
+        self._subs.append(sub)
+        return sub
+
+    def close(self) -> None:
+        """Close this client's connections. The runtime keeps running for
+        other clients and exits on its own when idle."""
+        for sub in self._subs:
+            sub.close()
+        self._conn.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

sonara_client-0.21.7/src/sonara_client/connect.py

@@ -0,0 +1,164 @@
+"""``connect()``: find or start the shared runtime (spec section 3)."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional, Sequence
+
+from .client import Client
+from .connection import Connection
+from .discovery import live_runtime, resolve_home, start_runtime, wait_exit
+from .errors import E_CLOSED, E_NOT_RUNNING, SonaraError
+from .version import PROTOCOL, __version__
+
+CONNECT_TIMEOUT = 5.0
+EXIT_WAIT = 5.0
+
+
+class _Incompatible(Exception):
+    """The instance answers but cannot serve this client."""
+
+
+def connect(
+    client_name: str,
+    *,
+    runtime_path: Optional[str] = None,
+    home: Optional[str] = None,
+    autostart: bool = True,
+    require: Sequence[str] = (),
+    extensions: Sequence[str] = (),
+    client_version: Optional[str] = None,
+    keep_alive: bool = False,
+    runtime_args: Sequence[str] = (),
+    start_timeout: float = 5.0,
+    takeover_timeout: float = 30.0,
+    takeover_retry: float = 0.25,
+    timeout: float = 10.0,
+) -> Client:
+    """Connect to the shared Sonara runtime.
+
+    1. Read ``runtime.json`` in the home (``home``, else ``SONARA_HOME``,
+       else ``%LOCALAPPDATA%\\Sonara``); when its pid is alive, connect and
+       send ``hello``.
+    2. Use it when it speaks protocol 1 and offers everything in ``require``.
+    3. Otherwise (with ``autostart``), start ``runtime_path --home <home>``
+       (default: ``SONARA_RUNTIME``), wait up to ``start_timeout`` seconds
+       for its ``runtime.json``, then ``hello``.
+    4. An incompatible running instance is first asked to step down
+       (``hello`` with ``takeover: true``); while it is busy the takeover is
+       retried for up to ``takeover_timeout`` seconds, then
+       ``E_INCOMPATIBLE``.
+
+    ``runtime_args`` are extra arguments for a started runtime (tests:
+    ``["--engine", "fake"]``); ``timeout`` bounds each request.
+    """
+    if not isinstance(client_name, str) or not client_name:
+        raise SonaraError("E_BAD_REQUEST", "connect() needs a client_name")
+    home = resolve_home(home)
+    runtime_path = runtime_path or os.environ.get("SONARA_RUNTIME")
+    can_start = bool(autostart and runtime_path)
+    hello = {
+        "client": {"name": client_name, "version": client_version or __version__},
+        "protocol": dict(PROTOCOL),
+        "require": list(require),
+        "extensions": list(extensions),
+    }
+    if keep_alive:
+        hello["keep_alive"] = True
+
+    running = live_runtime(home)
+    if running:
+        try:
+            client = _greet(running, hello, list(require), timeout)
+            if client:
+                return client
+        except _Incompatible as e:
+            if not can_start:
+                raise SonaraError(
+                    "E_INCOMPATIBLE",
+                    f"the running Sonara {running.get('version')} cannot serve this client ({e}) "
+                    "and there is no runtime to start in its place",
+                ) from None
+            _take_over(home, client_name, client_version, str(e), takeover_timeout, takeover_retry)
+
+    if not can_start:
+        why = "autostart is off" if runtime_path else "no runtime_path to start one"
+        raise SonaraError(E_NOT_RUNNING, f"no Sonara runtime is running and {why}")
+    started = start_runtime(runtime_path, home, list(runtime_args), start_timeout)
+    try:
+        client = _greet(started, hello, list(require), timeout)
+    except _Incompatible as e:
+        raise SonaraError(
+            "E_INCOMPATIBLE", f"the bundled Sonara {started.get('version')} cannot serve this client: {e}"
+        ) from None
+    if client is None:
+        raise SonaraError(E_CLOSED, "the started runtime closed the connection")
+    return client
+
+
+def _greet(info: dict, hello: dict, require: list, timeout: float) -> Optional[Client]:
+    """Connect and ``hello``. None when the instance cannot be reached;
+    _Incompatible when it answers but cannot serve this client."""
+
+    def dial() -> Connection:
+        conn = Connection(info["port"], timeout)
+        try:
+            conn.request("hello", {**hello, "token": info["token"]})
+        except SonaraError:
+            conn.close()
+            raise
+        return conn
+
+    try:
+        conn = Connection(info["port"], min(timeout, CONNECT_TIMEOUT))
+    except SonaraError:
+        return None
+    try:
+        reply = conn.request("hello", {**hello, "token": info["token"]})
+    except SonaraError as e:
+        conn.close()
+        if e.code in ("E_INCOMPATIBLE", "E_UNSUPPORTED"):
+            raise _Incompatible(e.message) from None
+        if e.code == E_CLOSED:
+            return None
+        raise
+    offered = set(reply.get("capabilities") or []) | set(reply.get("extensions") or [])
+    missing = [r for r in require if r not in offered]
+    major = (reply.get("protocol") or {}).get("major")
+    if major != PROTOCOL["major"] or missing:
+        conn.close()
+        raise _Incompatible(f"it does not offer {', '.join(missing)}" if missing else f"it speaks protocol {major}")
+    return Client(conn, info, reply, dial)
+
+
+def _take_over(home: str, name: str, version: Optional[str], why: str, limit: float, retry: float) -> None:
+    """Ask the running instance to exit so the bundled runtime can start. It
+    accepts only when idle; while busy, retry until ``limit`` seconds. Each
+    attempt uses a fresh connection: the runtime closes one that has no
+    successful ``hello`` within 5 s."""
+    deadline = time.monotonic() + limit
+    client = {"name": name, "version": version or __version__}
+    while True:
+        cur = live_runtime(home)
+        if not cur:
+            return
+        try:
+            conn = Connection(cur["port"], CONNECT_TIMEOUT)
+            try:
+                conn.request("hello", {"token": cur["token"], "client": client, "takeover": True})
+            finally:
+                conn.close()
+            if wait_exit(cur["pid"], EXIT_WAIT):
+                return
+        except SonaraError as e:
+            if e.code not in ("E_BUSY", E_CLOSED):
+                raise SonaraError(
+                    "E_INCOMPATIBLE",
+                    f"the running Sonara cannot serve this client ({why}) and refused a takeover: {e.message}",
+                ) from None
+        if time.monotonic() >= deadline:
+            raise SonaraError(
+                "E_INCOMPATIBLE",
+                f"the running Sonara cannot serve this client ({why}) and stayed busy; gave up the takeover",
+            )
+        time.sleep(retry)

sonara_client-0.21.7/src/sonara_client/connection.py

@@ -0,0 +1,118 @@
+"""One TCP JSON-lines connection to the runtime."""
+from __future__ import annotations
+
+import itertools
+import json
+import socket
+import threading
+from typing import Optional
+
+from .errors import E_CLOSED, SonaraError
+
+MAX_LINE = 1 << 20
+
+
+class Connection:
+    """Requests and their replies (blocking, one at a time), plus events
+    for a subscribed connection."""
+
+    def __init__(self, port: int, timeout: float):
+        try:
+            self._sock = socket.create_connection(("127.0.0.1", port), timeout=timeout)
+        except OSError as e:
+            raise SonaraError(E_CLOSED, f"cannot connect to 127.0.0.1:{port}: {e}") from None
+        self._sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        self._timeout = timeout
+        self._buf = b""
+        self._ids = itertools.count(1)
+        self._lock = threading.Lock()
+        self._events: list = []
+        self.closed = False
+
+    def request(self, type_: str, fields: Optional[dict] = None) -> dict:
+        """Send ``{type, **fields}``; the ``ok: true`` reply, or SonaraError."""
+        with self._lock:
+            if self.closed:
+                raise SonaraError(E_CLOSED, "the connection is closed")
+            msg = dict(fields or {})
+            msg["type"] = type_
+            msg["id"] = next(self._ids)
+            try:
+                self._sock.sendall(json.dumps(msg).encode("utf-8") + b"\n")
+            except OSError as e:
+                self._mark_closed()
+                raise SonaraError(E_CLOSED, f"send failed: {e}") from None
+            while True:
+                try:
+                    reply = self._read(self._timeout)
+                except socket.timeout:
+                    # A late reply would answer the next request: give up
+                    # on this connection instead.
+                    self._mark_closed()
+                    raise SonaraError(E_CLOSED, f"no reply within {self._timeout} s") from None
+                if reply is None:
+                    raise SonaraError(E_CLOSED, "the connection closed before the reply")
+                if "event" in reply:
+                    self._events.append(reply)
+                    continue
+                if "ok" not in reply:
+                    continue
+                if reply.get("ok") is True:
+                    return reply
+                err = reply.get("error") or {}
+                raise SonaraError(err.get("code", "E_BAD_REQUEST"), err.get("message", "request failed"),
+                                  err.get("reason"))
+
+    def next_event(self, timeout: Optional[float]) -> Optional[dict]:
+        """The next event; None at the end of the stream. ``socket.timeout``
+        (``TimeoutError``) when none arrived within ``timeout`` seconds."""
+        if self._events:
+            return self._events.pop(0)
+        while True:
+            msg = self._read(timeout)
+            if msg is None or "event" in msg:
+                return msg
+
+    def close(self) -> None:
+        self._mark_closed()
+
+    def _mark_closed(self) -> None:
+        if not self.closed:
+            self.closed = True
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+
+    def _read(self, timeout: Optional[float]) -> Optional[dict]:
+        """The next JSON object line, or None once the stream ended."""
+        while True:
+            nl = self._buf.find(b"\n")
+            if nl >= 0:
+                line, self._buf = self._buf[:nl], self._buf[nl + 1:]
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    msg = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(msg, dict):
+                    return msg
+                continue
+            if self.closed:
+                return None
+            self._sock.settimeout(timeout)
+            try:
+                chunk = self._sock.recv(65536)
+            except socket.timeout:
+                raise
+            except OSError:
+                chunk = b""
+            if not chunk:
+                self._mark_closed()
+                return None
+            self._buf += chunk
+            if len(self._buf) > MAX_LINE * 2:
+                self._mark_closed()
+                return None