@sonara/client 0.21.6

package/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.

package/README.md

@@ -0,0 +1,36 @@
+# @sonara/client
+
+Talk to the Sonara text-to-speech runtime from Node 18+ or an Electron main process. Zero dependencies; ESM and CommonJS builds with type declarations.
+
+```js
+import { connect } from "@sonara/client";
+import { runtimePath } from "@sonara/runtime-win32-x64";
+
+const sonara = await connect({ clientName: "my-app", runtimePath: runtimePath() });
+sonara.onState((s) => console.log(s.now_playing?.text ?? "idle"));
+const item = await sonara.speak("Hello.", { label: "greeting" });
+await sonara.control("pause");
+await sonara.set("rate", 240);
+await sonara.close();
+```
+
+- `connect(options)`: finds the shared runtime through `runtime.json`, starts the bundled `sonarad.exe` when none is usable (`autostart`, default on), takes over an idle incompatible one. Options: `clientName` (required), `runtimePath` (default `SONARA_RUNTIME`), `home`, `autostart`, `require`, `extensions`, `keepAlive`.
+- `speak(text, { mode: "append" | "replace", interrupt, label })` resolves with the item id.
+- `control(action)`: `play`, `pause`, `toggle`, `stop`, `skip`, `previous`, `next`, `restart`, `mute`, `unmute`.
+- `set(key, value)` / `get(key)` for `volume` (0..100), `rate` (100..400 wpm), `voice`, `engine`; `voices(engine?)`.
+- `onState`, `onItem`, `onLog` return an unsubscribe function; events arrive on a second connection opened by the first listener. Every state listener, also one added later, gets the current state first. `onClose` fires when the runtime goes away.
+- `channels`, `agent`, `system`: extension namespaces that send the protocol's extension messages as they are.
+- Errors are `SonaraError` with a `code` (`E_BUSY`, `E_NOT_RUNNING`, ...).
+
+Guide: [Bundle Sonara in your app](https://github.com/Maxaubert/Sonara/blob/main/docs/bundling.md). Protocol: [protocol v1](https://github.com/Maxaubert/Sonara/blob/main/docs/protocol-v1.md).
+
+## Development
+
+```sh
+npm ci
+npm run build       # tsc to dist/esm and dist/cjs
+npm run test:unit   # against a fake runtime
+npm test            # also against a real sonarad.exe (cargo build -p sonarad, or SONARAD=...)
+```
+
+MIT. Ship `THIRD_PARTY_NOTICES.md` with an app that bundles the runtime (see `LICENSING.md` in the repository).

package/dist/cjs/client.d.ts

@@ -0,0 +1,87 @@
+import { Connection } from "./connection.js";
+import { EnginesApi } from "./engines.js";
+import { AgentApi, ChannelsApi, SystemApi } from "./extensions.js";
+import type { ControlAction, HelloInfo, ItemEvent, LogEvent, Reply, RuntimeInfo, SettingKey, SpeakOptions, State, Voice } from "./types.js";
+export type Unsubscribe = () => void;
+type Listener<T> = (value: T) => void;
+/** Opens and greets one more connection (the event connection). */
+export type Dial = () => Promise<Connection>;
+/**
+ * A connected Sonara client. Requests use one connection; events
+ * (`onState`, `onItem`, `onLog`) arrive on a second one, opened on the first
+ * listener and subscribed to every stream.
+ */
+export declare class SonaraClient {
+    /** The runtime's `hello` reply: version, protocol, capabilities, extensions. */
+    readonly info: HelloInfo;
+    /** `runtime.json` of the instance this client talks to. */
+    readonly runtime: Readonly<RuntimeInfo>;
+    /** Extension `channels` (pass-through; needs a runtime that offers it). */
+    readonly channels: ChannelsApi;
+    /** Extension `agent` (pass-through). */
+    readonly agent: AgentApi;
+    /** Extension `system` (pass-through). */
+    readonly system: SystemApi;
+    /** External engines (protocol 1.2, capability `engines`; pass-through). */
+    readonly engines: EnginesApi;
+    private readonly conn;
+    private readonly dial;
+    private eventConn;
+    private eventsOpening;
+    private eventsFailed;
+    /** The newest `state` snapshot, handed to a state listener added later. */
+    private lastState;
+    private closing;
+    private readonly stateListeners;
+    private readonly itemListeners;
+    private readonly logListeners;
+    private readonly closeListeners;
+    constructor(conn: Connection, runtime: RuntimeInfo, info: HelloInfo, dial: Dial);
+    /** True once the connection closed (close(), a takeover or the runtime exited). */
+    get closed(): boolean;
+    /** Send any protocol message; resolves with the `ok: true` reply. */
+    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    /** Add `text` as one item; resolves with its item id. */
+    speak(text: string, opts?: SpeakOptions): Promise<number>;
+    /** Playback control: play, pause, toggle, stop, skip, previous, next, restart, mute, unmute. */
+    control(action: ControlAction): Promise<void>;
+    /** Change a setting; resolves with the value now in force. */
+    set(key: SettingKey, value: unknown): Promise<unknown>;
+    /** Read a setting. */
+    get(key: SettingKey): Promise<unknown>;
+    /**
+     * Voices of one engine, or of all. `refresh` asks an external engine's
+     * provider again (protocol 1.2).
+     */
+    voices(engine?: string, opts?: {
+        refresh?: boolean;
+    }): Promise<Voice[]>;
+    /**
+     * Call `cb` with every `state` snapshot. The first is the current state,
+     * also for a listener added after others: the runtime sends state on
+     * change only, so the latest snapshot is replayed to it (asynchronously).
+     */
+    onState(cb: Listener<State>): Unsubscribe;
+    /** Call `cb` with every `item` event (started, finished, skipped, failed). */
+    onItem(cb: Listener<ItemEvent>): Unsubscribe;
+    /** Call `cb` with every `log` event. */
+    onLog(cb: Listener<LogEvent>): Unsubscribe;
+    /**
+     * Call `cb` once the request connection closes for any reason. A drop of
+     * the event connection alone is reported to `onLog` ("event stream
+     * closed"); the next listener added opens a new one.
+     */
+    onClose(cb: () => void): Unsubscribe;
+    /**
+     * Resolves once the event connection is subscribed (opened by the first
+     * listener), so nothing that follows is missed. Rejects when that failed;
+     * the next listener added tries again.
+     */
+    eventsReady(): Promise<void>;
+    /** Close both connections. The runtime keeps running for other clients and exits on its own when idle. */
+    close(): Promise<void>;
+    private listen;
+    private openEvents;
+    private dispatch;
+}
+export {};

package/dist/cjs/client.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SonaraClient = void 0;
+const errors_js_1 = require("./errors.js");
+const engines_js_1 = require("./engines.js");
+const extensions_js_1 = require("./extensions.js");
+/**
+ * A connected Sonara client. Requests use one connection; events
+ * (`onState`, `onItem`, `onLog`) arrive on a second one, opened on the first
+ * listener and subscribed to every stream.
+ */
+class SonaraClient {
+    constructor(conn, runtime, info, dial) {
+        this.eventConn = null;
+        this.eventsOpening = null;
+        this.eventsFailed = false;
+        /** The newest `state` snapshot, handed to a state listener added later. */
+        this.lastState = null;
+        this.closing = false;
+        this.stateListeners = new Set();
+        this.itemListeners = new Set();
+        this.logListeners = new Set();
+        this.closeListeners = new Set();
+        this.conn = conn;
+        this.runtime = runtime;
+        this.info = info;
+        this.dial = dial;
+        const send = (type, fields) => this.request(type, fields);
+        this.channels = new extensions_js_1.ChannelsApi(send);
+        this.agent = new extensions_js_1.AgentApi(send);
+        this.system = new extensions_js_1.SystemApi(send);
+        this.engines = new engines_js_1.EnginesApi(send);
+        conn.onClose = () => {
+            this.eventConn?.close();
+            for (const cb of [...this.closeListeners])
+                cb();
+        };
+    }
+    /** True once the connection closed (close(), a takeover or the runtime exited). */
+    get closed() {
+        return this.conn.closed;
+    }
+    /** Send any protocol message; resolves with the `ok: true` reply. */
+    request(type, fields = {}) {
+        return this.conn.request(type, fields);
+    }
+    /** Add `text` as one item; resolves with its item id. */
+    async speak(text, opts = {}) {
+        const fields = { text };
+        if (opts.mode !== undefined)
+            fields.mode = opts.mode;
+        if (opts.interrupt !== undefined)
+            fields.interrupt = opts.interrupt;
+        if (opts.label !== undefined)
+            fields.label = opts.label;
+        const r = await this.request("speak", fields);
+        return r.item_id;
+    }
+    /** Playback control: play, pause, toggle, stop, skip, previous, next, restart, mute, unmute. */
+    async control(action) {
+        await this.request("control", { action });
+    }
+    /** Change a setting; resolves with the value now in force. */
+    async set(key, value) {
+        const r = await this.request("set", { key, value });
+        return r.value;
+    }
+    /** Read a setting. */
+    async get(key) {
+        const r = await this.request("get", { key });
+        return r.value;
+    }
+    /**
+     * Voices of one engine, or of all. `refresh` asks an external engine's
+     * provider again (protocol 1.2).
+     */
+    async voices(engine, opts = {}) {
+        const fields = engine === undefined ? {} : { engine };
+        if (opts.refresh !== undefined)
+            fields.refresh = opts.refresh;
+        const r = await this.request("voices", fields);
+        return r.voices;
+    }
+    /**
+     * Call `cb` with every `state` snapshot. The first is the current state,
+     * also for a listener added after others: the runtime sends state on
+     * change only, so the latest snapshot is replayed to it (asynchronously).
+     */
+    onState(cb) {
+        const off = this.listen(this.stateListeners, cb);
+        const last = this.lastState;
+        if (last) {
+            queueMicrotask(() => {
+                // Skip it when unsubscribed meanwhile or a newer state already came.
+                if (this.stateListeners.has(cb) && this.lastState === last)
+                    cb(last);
+            });
+        }
+        return off;
+    }
+    /** Call `cb` with every `item` event (started, finished, skipped, failed). */
+    onItem(cb) {
+        return this.listen(this.itemListeners, cb);
+    }
+    /** Call `cb` with every `log` event. */
+    onLog(cb) {
+        return this.listen(this.logListeners, cb);
+    }
+    /**
+     * Call `cb` once the request connection closes for any reason. A drop of
+     * the event connection alone is reported to `onLog` ("event stream
+     * closed"); the next listener added opens a new one.
+     */
+    onClose(cb) {
+        this.closeListeners.add(cb);
+        return () => {
+            this.closeListeners.delete(cb);
+        };
+    }
+    /**
+     * Resolves once the event connection is subscribed (opened by the first
+     * listener), so nothing that follows is missed. Rejects when that failed;
+     * the next listener added tries again.
+     */
+    eventsReady() {
+        return this.eventsOpening ?? Promise.resolve();
+    }
+    /** Close both connections. The runtime keeps running for other clients and exits on its own when idle. */
+    async close() {
+        this.closing = true;
+        this.eventConn?.close();
+        this.conn.close();
+    }
+    listen(set, cb) {
+        set.add(cb);
+        // A failed attempt is retried by the next listener.
+        if ((!this.eventsOpening || this.eventsFailed) && !this.closing) {
+            this.eventsFailed = false;
+            this.eventsOpening = this.openEvents();
+            // The failure is reported to log listeners; eventsReady() still rejects.
+            this.eventsOpening.catch(() => undefined);
+        }
+        return () => {
+            set.delete(cb);
+        };
+    }
+    async openEvents() {
+        try {
+            const conn = await this.dial();
+            if (this.closing) {
+                conn.close();
+                return;
+            }
+            this.eventConn = conn;
+            conn.onEvent = (e) => this.dispatch(e);
+            await conn.request("subscribe", { events: ["state", "items", "log"] });
+            // The event connection can drop on its own (the request connection
+            // reports through onClose). Once subscribed, tell log listeners, and
+            // let the next listener open a new one.
+            conn.onClose = () => {
+                if (this.eventConn === conn)
+                    this.eventConn = null;
+                // A new event connection starts with the then current state.
+                this.lastState = null;
+                if (this.closing || this.conn.closed)
+                    return;
+                this.eventsFailed = true;
+                for (const cb of [...this.logListeners])
+                    cb({ message: "event stream closed" });
+            };
+        }
+        catch (err) {
+            this.eventsFailed = true;
+            const message = `event stream failed: ${err.message}`;
+            for (const cb of [...this.logListeners])
+                cb({ message });
+            throw err instanceof errors_js_1.SonaraError ? err : new errors_js_1.SonaraError("E_CLOSED", message);
+        }
+    }
+    dispatch(e) {
+        const { event, ...body } = e;
+        if (event === "state") {
+            const state = body;
+            this.lastState = state;
+            for (const cb of [...this.stateListeners])
+                cb(state);
+        }
+        else if (event === "item")
+            for (const cb of [...this.itemListeners])
+                cb(body);
+        else if (event === "log")
+            for (const cb of [...this.logListeners])
+                cb(body);
+    }
+}
+exports.SonaraClient = SonaraClient;

package/dist/cjs/connect.d.ts

@@ -0,0 +1,44 @@
+import { SonaraClient } from "./client.js";
+export interface ConnectOptions {
+    /** Your app's name, sent in `hello` (informational). */
+    clientName: string;
+    /** Your app's version (default: this package's version). */
+    clientVersion?: string;
+    /**
+     * The bundled `sonarad.exe`, started when no usable runtime is running.
+     * Default: `SONARA_RUNTIME` from the environment. With
+     * `@sonara/runtime-win32-x64`: `runtimePath()` from that package.
+     */
+    runtimePath?: string;
+    /** Home folder (default: `SONARA_HOME`, else `%LOCALAPPDATA%\Sonara`). */
+    home?: string;
+    /** Start the bundled runtime when none is usable (default true). */
+    autostart?: boolean;
+    /** Capabilities or extensions this client cannot work without. */
+    require?: string[];
+    /** Extensions to enable (`channels`, `agent`, `system`). */
+    extensions?: string[];
+    /** Keep the runtime running after the last client left. */
+    keepAlive?: boolean;
+    /** Extra command-line arguments for a started runtime (tests: `["--engine", "fake"]`). */
+    runtimeArgs?: string[];
+    /** Wait for a started runtime's `runtime.json` (default 5000 ms). */
+    startTimeoutMs?: number;
+    /** Retry the takeover of a busy, incompatible runtime this long (default 30000 ms). */
+    takeoverTimeoutMs?: number;
+    /** Wait between takeover retries (default 250 ms). */
+    takeoverRetryMs?: number;
+}
+/**
+ * Connect to the shared Sonara runtime (spec section 3):
+ *
+ * 1. Read `runtime.json` in the home; when its pid is alive, connect and
+ *    send `hello`.
+ * 2. Use it when it speaks protocol 1 and offers everything in `require`.
+ * 3. Otherwise (and with `autostart`), start `runtimePath --home <home>`,
+ *    wait up to 5 s 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 30 s, then `E_INCOMPATIBLE`.
+ */
+export declare function connect(opts: ConnectOptions): Promise<SonaraClient>;

package/dist/cjs/connect.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connect = connect;
+const client_js_1 = require("./client.js");
+const connection_js_1 = require("./connection.js");
+const discovery_js_1 = require("./discovery.js");
+const errors_js_1 = require("./errors.js");
+const version_js_1 = require("./version.js");
+const CONNECT_TIMEOUT_MS = 5000;
+const EXIT_WAIT_MS = 5000;
+/** Why an instance cannot serve this client. */
+class Incompatible extends Error {
+}
+/**
+ * Connect to the shared Sonara runtime (spec section 3):
+ *
+ * 1. Read `runtime.json` in the home; when its pid is alive, connect and
+ *    send `hello`.
+ * 2. Use it when it speaks protocol 1 and offers everything in `require`.
+ * 3. Otherwise (and with `autostart`), start `runtimePath --home <home>`,
+ *    wait up to 5 s 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 30 s, then `E_INCOMPATIBLE`.
+ */
+async function connect(opts) {
+    if (!opts || typeof opts.clientName !== "string" || !opts.clientName) {
+        throw new errors_js_1.SonaraError("E_BAD_REQUEST", "connect() needs a clientName");
+    }
+    const home = (0, discovery_js_1.resolveHome)(opts.home);
+    const runtimePath = opts.runtimePath ?? process.env.SONARA_RUNTIME;
+    const canStart = (opts.autostart ?? true) && !!runtimePath;
+    const require = opts.require ?? [];
+    const hello = {
+        client: { name: opts.clientName, version: opts.clientVersion ?? version_js_1.VERSION },
+        protocol: { ...version_js_1.PROTOCOL },
+        require,
+        extensions: opts.extensions ?? [],
+    };
+    if (opts.keepAlive)
+        hello.keep_alive = true;
+    const greeting = { hello, require };
+    const running = (0, discovery_js_1.liveRuntime)(home);
+    if (running) {
+        try {
+            const client = await greet(running, greeting);
+            if (client)
+                return client;
+        }
+        catch (err) {
+            if (!(err instanceof Incompatible))
+                throw err;
+            if (!canStart) {
+                throw new errors_js_1.SonaraError("E_INCOMPATIBLE", `the running Sonara ${running.version} cannot serve this client (${err.message}) and there is no runtime to start in its place`);
+            }
+            await takeOver(home, opts, err.message);
+        }
+    }
+    if (!canStart) {
+        throw new errors_js_1.SonaraError("E_NOT_RUNNING", runtimePath
+            ? "no Sonara runtime is running and autostart is off"
+            : "no Sonara runtime is running and no runtimePath to start one");
+    }
+    const started = await (0, discovery_js_1.startRuntime)(runtimePath, home, opts.runtimeArgs ?? [], opts.startTimeoutMs ?? 5000);
+    try {
+        const client = await greet(started, greeting);
+        if (client)
+            return client;
+        throw new errors_js_1.SonaraError("E_CLOSED", "the started runtime closed the connection");
+    }
+    catch (err) {
+        if (err instanceof Incompatible) {
+            throw new errors_js_1.SonaraError("E_INCOMPATIBLE", `the bundled Sonara ${started.version} cannot serve this client: ${err.message}`);
+        }
+        throw err;
+    }
+}
+/**
+ * Connect and send `hello`. Null when the instance cannot be reached (it is
+ * exiting); throws Incompatible when it answers but cannot serve us.
+ */
+async function greet(info, g) {
+    const dial = async () => {
+        const conn = await connection_js_1.Connection.open(info.port, CONNECT_TIMEOUT_MS);
+        try {
+            await conn.request("hello", { ...g.hello, token: info.token });
+        }
+        catch (err) {
+            conn.close();
+            throw err;
+        }
+        return conn;
+    };
+    let conn;
+    try {
+        conn = await connection_js_1.Connection.open(info.port, CONNECT_TIMEOUT_MS);
+    }
+    catch {
+        return null;
+    }
+    let reply;
+    try {
+        reply = await conn.request("hello", { ...g.hello, token: info.token });
+    }
+    catch (err) {
+        conn.close();
+        if (err instanceof errors_js_1.SonaraError && (err.code === "E_INCOMPATIBLE" || err.code === "E_UNSUPPORTED")) {
+            throw new Incompatible(err.message);
+        }
+        if (err instanceof errors_js_1.SonaraError && err.code === "E_CLOSED")
+            return null;
+        throw err;
+    }
+    const helloInfo = reply;
+    const offered = new Set([...(helloInfo.capabilities ?? []), ...(helloInfo.extensions ?? [])]);
+    const missing = g.require.filter((r) => !offered.has(r));
+    if (helloInfo.protocol?.major !== version_js_1.PROTOCOL.major || missing.length) {
+        conn.close();
+        throw new Incompatible(missing.length ? `it does not offer ${missing.join(", ")}` : `it speaks protocol ${helloInfo.protocol?.major}`);
+    }
+    return new client_js_1.SonaraClient(conn, info, helloInfo, dial);
+}
+/**
+ * Ask the running instance to exit so the bundled runtime can start. It
+ * accepts only when idle; while it is busy, retry until `takeoverTimeoutMs`.
+ * Each attempt uses a fresh connection: the runtime closes one that has no
+ * successful `hello` within 5 s.
+ */
+async function takeOver(home, opts, why) {
+    const deadline = Date.now() + (opts.takeoverTimeoutMs ?? 30000);
+    const retryMs = opts.takeoverRetryMs ?? 250;
+    const client = { name: opts.clientName, version: opts.clientVersion ?? version_js_1.VERSION };
+    for (;;) {
+        const cur = (0, discovery_js_1.liveRuntime)(home);
+        if (!cur)
+            return;
+        let conn = null;
+        try {
+            conn = await connection_js_1.Connection.open(cur.port, CONNECT_TIMEOUT_MS);
+            await conn.request("hello", { token: cur.token, client, takeover: true });
+            conn.close();
+            if (await (0, discovery_js_1.waitExit)(cur.pid, EXIT_WAIT_MS))
+                return;
+        }
+        catch (err) {
+            conn?.close();
+            const code = err instanceof errors_js_1.SonaraError ? err.code : "";
+            if (code !== "E_BUSY" && code !== "E_CLOSED") {
+                throw new errors_js_1.SonaraError("E_INCOMPATIBLE", `the running Sonara cannot serve this client (${why}) and refused a takeover: ${err.message}`);
+            }
+        }
+        if (Date.now() >= deadline) {
+            throw new errors_js_1.SonaraError("E_INCOMPATIBLE", `the running Sonara cannot serve this client (${why}) and stayed busy; gave up the takeover`);
+        }
+        await (0, discovery_js_1.sleep)(retryMs);
+    }
+}

package/dist/cjs/connection.d.ts

@@ -0,0 +1,25 @@
+import type { Reply } from "./types.js";
+/**
+ * One TCP JSON-lines connection to the runtime. Requests carry an `id`;
+ * replies (with `ok`) settle the matching promise, events (with `event`) go
+ * to `onEvent`.
+ */
+export declare class Connection {
+    onEvent: ((event: Record<string, unknown>) => void) | null;
+    onClose: (() => void) | null;
+    private readonly sock;
+    private buf;
+    private nextId;
+    private readonly pending;
+    private closedFlag;
+    private constructor();
+    /** Connect to `127.0.0.1:<port>`; rejects after `timeoutMs`. */
+    static open(port: number, timeoutMs: number): Promise<Connection>;
+    get closed(): boolean;
+    /** Send `{type, ...fields}`; resolves with the `ok: true` reply, rejects with a SonaraError. */
+    request(type: string, fields?: Record<string, unknown>): Promise<Reply>;
+    close(): void;
+    private onData;
+    private onLine;
+    private finish;
+}