@qvac/sdk 0.9.2 → 0.10.0

package/dist/client/api/text-to-speech.js

@@ -1,58 +1,434 @@
-import { ttsResponseSchema, } from "../../schemas/index.js";
-import { stream as streamRpc } from "../rpc/rpc-client.js";
-export function textToSpeech(params, options) {
-    const request = {
+import { textToSpeechStreamResponseSchema, ttsClientParamsSchema, } from "../../schemas/index.js";
+import { stream as streamRpc, duplex } from "../rpc/rpc-client.js";
+import { getClientLogger } from "../../logging/index.js";
+import { TextToSpeechStreamFailedError } from "../../utils/errors-client.js";
+const logger = getClientLogger();
+/**
+ * Fan-out queue that lets multiple consumers iterate the same TTS response
+ * stream independently. Items are retained only until every active subscriber
+ * has consumed them, then trimmed from the queue.
+ *
+ * The source is injected as an `AsyncIterable<TtsResponse>` so this class can
+ * be unit-tested directly against the real implementation (without mocking
+ * the RPC layer). Production callsites adapt `streamRpc(...)` via
+ * `ttsResponseSource()` below.
+ *
+ * Exported for test use; not part of the public SDK surface.
+ */
+export class TtsMulticast {
+    queue = [];
+    waiters = [];
+    subscriberIndexes = [];
+    ended = false;
+    fatal;
+    resolvePumpDone;
+    rejectPumpDone;
+    done;
+    constructor(source) {
+        let resolve;
+        let reject;
+        this.done = new Promise((r, rj) => {
+            resolve = r;
+            reject = rj;
+        });
+        // Silence unhandled-rejection warnings when the caller never awaits
+        // `done` (e.g. only iterates the buffer stream). Re-awaits still get the
+        // rejection because the underlying promise state is unchanged.
+        this.done.catch(() => { });
+        this.resolvePumpDone = resolve;
+        this.rejectPumpDone = reject;
+        void this.pump(source);
+    }
+    subscribe() {
+        const subIdx = this.subscriberIndexes.length;
+        this.subscriberIndexes.push(0);
+        return this.drain(subIdx);
+    }
+    notify() {
+        for (const fn of this.waiters.splice(0))
+            fn();
+    }
+    trimConsumed() {
+        if (this.subscriberIndexes.length === 0)
+            return;
+        // `Number.POSITIVE_INFINITY` marks an unsubscribed slot; ignore those when
+        // computing how far every live subscriber has advanced.
+        const minIndex = Math.min(...this.subscriberIndexes);
+        if (!Number.isFinite(minIndex))
+            return;
+        if (minIndex > 0) {
+            this.queue.splice(0, minIndex);
+            for (let j = 0; j < this.subscriberIndexes.length; j++) {
+                const v = this.subscriberIndexes[j] ?? 0;
+                if (Number.isFinite(v))
+                    this.subscriberIndexes[j] = v - minIndex;
+            }
+        }
+    }
+    unsubscribe(subIdx) {
+        // Park the slot at +Infinity instead of splicing so every other
+        // subscriber's `subIdx` stays valid. `trimConsumed` filters these out.
+        this.subscriberIndexes[subIdx] = Number.POSITIVE_INFINITY;
+        this.trimConsumed();
+    }
+    async pump(source) {
+        try {
+            for await (const response of source) {
+                // The server owns this response schema; per-frame Zod .parse() adds
+                // non-trivial CPU overhead for large sentences with many PCM frames.
+                // Rely on the discriminated union narrowing at the RPC boundary and
+                // skip re-validation here.
+                this.queue.push(response);
+                this.notify();
+                if (response.done)
+                    break;
+            }
+        }
+        catch (e) {
+            this.fatal = e instanceof Error ? e : new Error(String(e));
+        }
+        finally {
+            this.ended = true;
+            this.notify();
+            if (this.fatal) {
+                // Reject rather than resolving false so callers awaiting `done`
+                // with no iteration — and callers iterating drain() — both see the
+                // real error instead of a silent sentinel.
+                this.rejectPumpDone(this.fatal);
+            }
+            else {
+                this.resolvePumpDone(true);
+            }
+        }
+    }
+    async *drain(subIdx) {
+        // If the consumer breaks out of a `for await` (or calls `.return()` /
+        // throws), this generator's finally block runs; release the slot so it
+        // no longer pins `trimConsumed`'s min-index and the queue can be GC'd.
+        try {
+            while (true) {
+                while ((this.subscriberIndexes[subIdx] ?? 0) < this.queue.length) {
+                    const currentIdx = this.subscriberIndexes[subIdx] ?? 0;
+                    const item = this.queue[currentIdx];
+                    this.subscriberIndexes[subIdx] = currentIdx + 1;
+                    this.trimConsumed();
+                    yield item;
+                }
+                if (this.fatal)
+                    throw this.fatal;
+                if (this.ended)
+                    return;
+                await new Promise((resolve) => {
+                    this.waiters.push(resolve);
+                });
+            }
+        }
+        finally {
+            this.unsubscribe(subIdx);
+        }
+    }
+}
+function buildTtsRequest(params) {
+    return {
         type: "textToSpeech",
         modelId: params.modelId,
         inputType: params.inputType,
         text: params.text,
         stream: params.stream,
+        sentenceStream: params.sentenceStream,
+        ...(params.sentenceStreamLocale !== undefined && {
+            sentenceStreamLocale: params.sentenceStreamLocale,
+        }),
+        ...(params.sentenceStreamMaxChunkScalars !== undefined && {
+            sentenceStreamMaxChunkScalars: params.sentenceStreamMaxChunkScalars,
+        }),
+    };
+}
+function buildTextToSpeechStreamRequest(params) {
+    return {
+        type: "textToSpeechStream",
+        modelId: params.modelId,
+        inputType: params.inputType ?? "text",
+        ...(params.accumulateSentences !== undefined && {
+            accumulateSentences: params.accumulateSentences,
+        }),
+        ...(params.sentenceDelimiterPreset !== undefined && {
+            sentenceDelimiterPreset: params.sentenceDelimiterPreset,
+        }),
+        ...(params.maxBufferScalars !== undefined && {
+            maxBufferScalars: params.maxBufferScalars,
+        }),
+        ...(params.flushAfterMs !== undefined && {
+            flushAfterMs: params.flushAfterMs,
+        }),
+    };
+}
+/**
+ * Converts text to speech audio using a loaded TTS model.
+ *
+ * Three modes selected by `params.stream` and `params.sentenceStream`:
+ *
+ * - `stream: false` (default) — collect all PCM samples and resolve once via
+ *   `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
+ * - `stream: true` — yield PCM samples through `result.bufferStream`
+ *   (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
+ *   array.
+ * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
+ *   (`AsyncGenerator<TtsSentenceChunkUpdate>`) so callers can mux per-sentence
+ *   metadata with the audio. Multiple consumers can iterate the response
+ *   independently via the underlying `TtsMulticast`.
+ *
+ * `result.done` resolves to `true` when synthesis completes cleanly, `false`
+ * if the consumer breaks out before the terminal frame, or rejects on a
+ * pipeline error. Awaiting `done` is safe even when no stream is iterated.
+ *
+ * @param params - TTS request parameters (see `TtsClientParamsInput`).
+ * @param options - Optional RPC options (timeout, profiling, force new connection).
+ * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
+ *          and (when `sentenceStream: true`) `chunkUpdates`.
+ * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
+ *         with `stream: false`, or when the underlying RPC stream errors.
+ */
+export function textToSpeech(params, options) {
+    const parsed = ttsClientParamsSchema.parse(params);
+    if (parsed.sentenceStream && !parsed.stream) {
+        throw new TextToSpeechStreamFailedError("textToSpeech: `sentenceStream: true` requires `stream: true`");
+    }
+    const request = buildTtsRequest(parsed);
+    if (parsed.stream && parsed.sentenceStream) {
+        return sentenceStreamTts(request, options);
+    }
+    if (parsed.stream) {
+        return plainStreamTts(request, options);
+    }
+    return collectTts(request, options);
+}
+// Adapts the raw RPC stream into the filtered `TtsResponse` source the
+// multicast expects. Kept here (not inlined) so the multicast can be
+// constructed in tests with a hand-rolled source instead.
+async function* ttsResponseSource(request, options) {
+    for await (const response of streamRpc(request, options)) {
+        if (response.type !== "textToSpeech")
+            continue;
+        yield response;
+    }
+}
+function sentenceStreamTts(request, options) {
+    const multicast = new TtsMulticast(ttsResponseSource(request, options));
+    // Subscribe eagerly, synchronously — before pump() can push its first
+    // item — so both subscribers see the full queue from index 0. If we
+    // deferred subscribing until the generators were iterated, the first
+    // consumer could trim the queue before the second ever registered,
+    // silently dropping earlier frames.
+    const bufferSubscription = multicast.subscribe();
+    const chunkSubscription = multicast.subscribe();
+    return {
+        bufferStream: sentenceBufferStream(bufferSubscription),
+        chunkUpdates: sentenceChunkUpdates(chunkSubscription),
+        buffer: Promise.resolve([]),
+        done: multicast.done,
+    };
+}
+async function* sentenceBufferStream(source) {
+    for await (const m of source) {
+        if (m.buffer.length > 0) {
+            yield* m.buffer;
+        }
+        if (m.done)
+            break;
+    }
+}
+async function* sentenceChunkUpdates(source) {
+    for await (const m of source) {
+        const hasAudio = m.buffer.length > 0;
+        const hasMeta = m.chunkIndex !== undefined ||
+            (typeof m.sentenceChunk === "string" && m.sentenceChunk.length > 0);
+        if (hasAudio || hasMeta) {
+            yield {
+                buffer: hasAudio ? [...m.buffer] : [],
+                ...(m.chunkIndex !== undefined ? { chunkIndex: m.chunkIndex } : {}),
+                ...(typeof m.sentenceChunk === "string" && m.sentenceChunk.length > 0
+                    ? { sentenceChunk: m.sentenceChunk }
+                    : {}),
+            };
+        }
+        if (m.done)
+            break;
+    }
+}
+function plainStreamTts(request, options) {
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
+    });
+    done.catch(() => { });
+    return {
+        bufferStream: plainTtsBufferStream(request, options, resolveDone, rejectDone),
+        buffer: Promise.resolve([]),
+        done,
     };
-    let doneResolver = () => { };
-    const donePromise = new Promise((resolve) => {
-        doneResolver = resolve;
+}
+async function* plainTtsBufferStream(request, options, resolveDone, rejectDone) {
+    let settled = false;
+    try {
+        for await (const response of streamRpc(request, options)) {
+            if (response.type !== "textToSpeech")
+                continue;
+            // See TtsMulticast.pump — skip per-frame Zod validation; the server is
+            // the source of truth for this wire shape.
+            if (response.buffer.length > 0) {
+                yield* response.buffer;
+            }
+            if (response.done) {
+                settled = true;
+                resolveDone(true);
+            }
+        }
+    }
+    catch (e) {
+        if (!settled) {
+            settled = true;
+            rejectDone(e);
+        }
+        throw e;
+    }
+    finally {
+        // Consumer broke out of the for-await before `done` arrived; resolve
+        // with `false` so `await result.done` never hangs.
+        if (!settled)
+            resolveDone(false);
+    }
+}
+function collectTts(request, options) {
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+        resolveDone = resolve;
+        rejectDone = reject;
     });
-    if (params.stream) {
-        const bufferStream = (async function* () {
-            for await (const response of streamRpc(request, options)) {
-                if (response.type === "textToSpeech") {
-                    const streamResponse = ttsResponseSchema.parse(response);
-                    if (streamResponse.buffer.length > 0) {
-                        yield* streamResponse.buffer;
-                    }
-                    if (streamResponse.done) {
-                        doneResolver(true);
-                    }
-                }
+    done.catch(() => { });
+    return {
+        bufferStream: emptyBufferStream(),
+        buffer: collectTtsBuffer(request, options, resolveDone, rejectDone),
+        done,
+    };
+}
+async function* emptyBufferStream() {
+    // Non-streaming mode exposes no incremental buffer stream.
+}
+async function collectTtsBuffer(request, options, resolveDone, rejectDone) {
+    let buffer = [];
+    try {
+        for await (const response of streamRpc(request, options)) {
+            if (response.type !== "textToSpeech")
+                continue;
+            buffer = buffer.concat(response.buffer);
+            if (response.done) {
+                resolveDone(true);
             }
-        })();
-        return {
-            bufferStream,
-            buffer: Promise.resolve([]),
-            done: donePromise,
-        };
-    }
-    else {
-        const bufferStream = (async function* () {
-            //Empty generator for non-streaming mode
-        })();
-        const bufferPromise = (async () => {
-            let buffer = [];
-            for await (const response of streamRpc(request, options)) {
-                if (response.type === "textToSpeech") {
-                    const streamResponse = ttsResponseSchema.parse(response);
-                    buffer = buffer.concat(streamResponse.buffer);
-                    if (streamResponse.done) {
-                        doneResolver(true);
-                    }
-                }
+        }
+        return buffer;
+    }
+    catch (e) {
+        rejectDone(e);
+        throw e;
+    }
+}
+/**
+ * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
+ * Buffer should be a complete UTF-8 fragment. The worker forwards them to ONNX TTS `runStreaming`
+ * (optional sentence accumulation via request fields). Iterate the session for `TextToSpeechStreamResponse`
+ * lines (PCM in `buffer`, optional `chunkIndex` / `sentenceChunk`) until `done`.
+ */
+export async function textToSpeechStream(params, options) {
+    const request = buildTextToSpeechStreamRequest(params);
+    const { requestStream, responseStream } = await duplex(request, options);
+    const responses = parseTextToSpeechStreamLines(responseStream);
+    let consumed = false;
+    // `closed` flips on `end()` or `destroy()`. Without this guard a late
+    // `write()` would propagate a raw Bare/Node "write after end" stream error
+    // to the caller. Throwing a typed SDK error keeps the duplex session
+    // surface predictable.
+    let closed = false;
+    return {
+        write(textFragment) {
+            if (closed) {
+                throw new TextToSpeechStreamFailedError("TextToSpeechStreamSession.write() called after end()/destroy()");
+            }
+            const buf = typeof textFragment === "string"
+                ? Buffer.from(textFragment, "utf8")
+                : textFragment;
+            requestStream.write(buf);
+        },
+        end() {
+            if (closed)
+                return;
+            closed = true;
+            requestStream.end();
+        },
+        destroy() {
+            closed = true;
+            requestStream.destroy();
+            responseStream.destroy();
+        },
+        [Symbol.asyncIterator]() {
+            if (consumed) {
+                // Return an iterator whose first .next() rejects asynchronously so
+                // `for await` surfaces the error in the normal async-iteration
+                // control flow instead of a synchronous throw from the iterator
+                // protocol (which callers commonly forget to wrap in try/catch).
+                return {
+                    next() {
+                        return Promise.reject(new TextToSpeechStreamFailedError("TextToSpeechStreamSession can only be iterated once"));
+                    },
+                };
             }
-            return buffer;
-        })();
-        return {
-            bufferStream,
-            buffer: bufferPromise,
-            done: donePromise,
-        };
+            consumed = true;
+            return responses;
+        },
+    };
+}
+async function* parseTextToSpeechStreamLines(responseStream) {
+    let buf = "";
+    for await (const chunk of responseStream) {
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() || "";
+        for (const line of lines) {
+            const yielded = processTextToSpeechStreamLine(line);
+            if (yielded === undefined)
+                continue;
+            yield yielded;
+            // Close the stream after the terminal frame so consumers don't
+            // depend on the server closing the socket to stop iteration.
+            if (yielded.done)
+                return;
+        }
+    }
+    if (buf.trim()) {
+        const yielded = processTextToSpeechStreamLine(buf);
+        if (yielded !== undefined) {
+            yield yielded;
+        }
+    }
+}
+function processTextToSpeechStreamLine(line) {
+    if (!line.trim()) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        logger.warn("textToSpeechStream: malformed JSON from server:", line);
+        return undefined;
+    }
+    const obj = parsed;
+    if (obj["type"] === "error") {
+        throw new TextToSpeechStreamFailedError(obj["message"] ?? "Unknown server error");
     }
+    return textToSpeechStreamResponseSchema.parse(parsed);
 }

package/dist/client/api/transcribe.d.ts

@@ -1,14 +1,22 @@
-import { type TranscribeClientParams, type RPCOptions, type TranscribeStreamClientParams, type TranscribeStreamSession } from "../../schemas/index";
+import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession } from "../../schemas/index";
 /**
  * Transcribe audio and return the complete text. Accepts either a file
  * path or an audio buffer.
  *
+ * @param params - Transcription parameters.
  * @param params.modelId - The identifier of the transcription model to use
  * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
  * @param params.prompt - Optional initial prompt to guide the transcription
+ * @param params.metadata - When true, resolves to an array of transcript
+ *                          segments (`{ text, startMs, endMs, append, id }`)
+ *                          instead of joined text. Whisper engine only.
  * @param options - Optional RPC options including per-call profiling
- * @returns The complete transcribed text
+ * @returns The complete transcribed text, or — when `metadata` is true —
+ *          the list of transcript segments in emission order.
  */
+export declare function transcribe(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeSegment[]>;
 export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string>;
 /**
  * @deprecated Pass audio via `transcribe()` instead. This overload will be
@@ -16,7 +24,15 @@ export declare function transcribe(params: TranscribeClientParams, options?: RPC
  *
  * Streaming transcription with upfront audio: sends full audio, yields text
  * chunks as they arrive.
+ *
+ * @overloadLabel "Upfront audio (deprecated)"
+ * @param params - Transcription parameters including audio source.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns An async generator yielding text chunks as they become available.
  */
+export declare function transcribeStream(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): AsyncGenerator<TranscribeSegment>;
 export declare function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string>;
 /**
  * Opens a bidirectional streaming transcription session. Audio is streamed
@@ -26,11 +42,20 @@ export declare function transcribeStream(params: TranscribeClientParams, options
  * The returned session is single-use. Attempting to iterate a second
  * time will throw a `TranscriptionFailedError`.
  *
+ * @overloadLabel "Bidirectional session"
+ * @param params - Streaming transcription parameters.
  * @param params.modelId - The loaded transcription model to use
  * @param params.prompt - Optional initial prompt to guide transcription
+ * @param params.metadata - When true, the session yields transcript segment
+ *                          objects (`{ text, startMs, endMs, append, id }`)
+ *                          instead of plain text. Whisper engine only.
+ * @param options - Optional RPC options including per-call profiling.
  * @returns A session object: call `write(buffer)` to feed audio,
- *          iterate with `for await (const text of session)` to receive
- *          transcription, and `end()` to signal end of audio.
+ *          iterate with `for await (...)` to receive transcription,
+ *          and `end()` to signal end of audio.
  */
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;
 export declare function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;
 //# sourceMappingURL=transcribe.d.ts.map