@qvac/sdk 0.18.2 → 0.19.0

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

@@ -1,455 +0,0 @@
-import { textToSpeechStreamResponseSchema, textToSpeechStreamRequestSchema, ttsClientParamsSchema } from '../../schemas/index.js';
-import { stream as streamRpc, duplex } from '../../client/rpc/rpc-client.js';
-import { getClientLogger } from '../../logging/index.js';
-import { TextToSpeechStreamFailedError } from '../../utils/errors-client.js';
-import { parseClientInput } from '../../client/parse-input.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
-        }),
-        ...(params.description !== undefined && { description: params.description }),
-        ...(params.voiceDescription !== undefined && { voiceDescription: params.voiceDescription }),
-        ...(params.voice !== undefined && { voice: params.voice }),
-        ...(params.emotion !== undefined && { emotion: params.emotion }),
-        ...(params.pitch !== undefined && { pitch: params.pitch }),
-        ...(params.pace !== undefined && { pace: params.pace }),
-        ...(params.expressivity !== undefined && { expressivity: params.expressivity }),
-        ...(params.noise !== undefined && { noise: params.noise }),
-        ...(params.reverb !== undefined && { reverb: params.reverb }),
-        ...(params.quality !== undefined && { quality: params.quality })
-    };
-}
-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
-        }),
-        ...(params.description !== undefined && { description: params.description }),
-        ...(params.voiceDescription !== undefined && { voiceDescription: params.voiceDescription }),
-        ...(params.voice !== undefined && { voice: params.voice }),
-        ...(params.emotion !== undefined && { emotion: params.emotion }),
-        ...(params.pitch !== undefined && { pitch: params.pitch }),
-        ...(params.pace !== undefined && { pace: params.pace }),
-        ...(params.expressivity !== undefined && { expressivity: params.expressivity }),
-        ...(params.noise !== undefined && { noise: params.noise }),
-        ...(params.reverb !== undefined && { reverb: params.reverb }),
-        ...(params.quality !== undefined && { quality: params.quality })
-    };
-}
-/**
- * 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 = parseClientInput(ttsClientParamsSchema, 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
-    };
-}
-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;
-    });
-    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 buffer;
-    }
-    catch (e) {
-        rejectDone(e);
-        throw e;
-    }
-}
-export function encodeTextToSpeechFragment(textFragment) {
-    return typeof textFragment === 'string' ? new TextEncoder().encode(textFragment) : textFragment;
-}
-/**
- * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
- * Uint8Array 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 = parseClientInput(textToSpeechStreamRequestSchema, 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()');
-            }
-            requestStream.write(encodeTextToSpeechFragment(textFragment));
-        },
-        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'));
-                    }
-                };
-            }
-            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,93 +0,0 @@
-import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamRequest, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStats } from '../../schemas/index.js';
-import { duplex } from '../../client/rpc/rpc-client.js';
-type TranscribeDuplexFactory = (request: TranscribeStreamRequest, options?: RPCOptions) => ReturnType<typeof duplex>;
-/**
- * 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 A promise (decorated with `requestId`) resolving to the
- *          complete transcribed text, or — when `metadata` is true —
- *          the list of transcript segments in emission order. The
- *          `requestId` is reachable synchronously so callers can target
- *          this in-flight transcription with `cancel({ requestId })`
- *          before `await` resolves.
- */
-export declare function transcribe(params: TranscribeClientParams & {
-    metadata: true;
-}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
-    requestId: string;
-};
-export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-/**
- * @deprecated Pass audio via `transcribe()` instead. This overload will be
- * removed in the next major version.
- *
- * 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
- * in via `write()`, and transcription text is yielded as the model's VAD
- * detects complete speech segments.
- *
- * 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(audioChunk)` with a `Uint8Array`
- *          (Node `Buffer` is a `Uint8Array` subtype) to feed audio,
- *          iterate with `for await (...)` to receive transcription, and
- *          `end()` to signal end of audio. After consuming the iterator,
- *          await `session.stats` for terminal engine statistics.
- */
-export declare function transcribeStream(params: TranscribeStreamClientParams & {
-    emitVadEvents: true;
-}, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
-export declare function transcribeStream(params: TranscribeStreamClientParams & {
-    parakeetStreamingConfig: NonNullable<TranscribeStreamClientParams['parakeetStreamingConfig']>;
-}, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
-export declare function transcribeStream(params: TranscribeStreamClientParams & {
-    metadata: true;
-}, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;
-export declare function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;
-/**
- * Shared duplex session factory. The per-call line processor decides whether
- * to surface strings or segments; `sessionName` is only used to label the
- * "already iterated" error so callers see the correct session type.
- */
-export declare function createTranscribeStreamSession<T>(params: TranscribeStreamClientParams, options: RPCOptions | undefined, process: (line: string, onStats: (stats: TranscribeStats | undefined) => void) => T | undefined | null, sessionName: string, duplexFactory?: TranscribeDuplexFactory): Promise<{
-    stats: Promise<TranscribeStats | undefined>;
-    write(audioChunk: Uint8Array): void;
-    end(): void;
-    destroy(): void;
-    [Symbol.asyncIterator](): AsyncIterator<T>;
-}>;
-export declare function processLine(line: string, onStats: (stats: TranscribeStats | undefined) => void): string | undefined | null;
-export {};
-//# sourceMappingURL=transcribe.d.ts.map