@rimelabs/sdk 0.1.0-alpha.1

package/dist/policy.js

@@ -0,0 +1,73 @@
+import { RimeInputError } from "./errors.js";
+export const policy = {
+    target: "coda.api.rime.ai:443",
+    audience: "coda.api.rime.ai",
+    exchangeUrl: "https://themis.api.rime.ai/v1/token",
+    sentenceBytes: 65536,
+    sourceChars: 1024,
+    outputBytes: 96000,
+    outputChunkBytes: 9600,
+    receiveBytes: 4194304,
+    authTimeout: 10,
+    connectionTimeout: 10,
+    firstAudioTimeout: 30,
+    progressTimeout: 60,
+    discoveryTimeout: 10,
+    cleanupTimeout: 2,
+};
+export function resolve(model, endpoint) {
+    // Add model defaults here only when its transport contract is supported.
+    if (model !== "coda")
+        throw new RimeInputError("This SDK supports model='coda'");
+    if (endpoint === undefined || endpoint === null)
+        return { ...policy };
+    const error = "endpoint must be a hostname with an optional port (1-65535), without a scheme or path";
+    if (typeof endpoint !== "string" || /\s/.test(endpoint))
+        throw new RimeInputError(error);
+    const [host, port, extra] = endpoint.split(":");
+    if (!host ||
+        host.length > 253 ||
+        extra !== undefined ||
+        host
+            .split(".")
+            .some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)) ||
+        (port !== undefined &&
+            (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)))
+        throw new RimeInputError(error);
+    return {
+        ...policy,
+        target: `${host.toLowerCase()}:${port === undefined ? 443 : Number(port)}`,
+        audience: host.toLowerCase(),
+    };
+}
+export function timeout(value, inherited = null) {
+    if (value === undefined)
+        return inherited;
+    if (value !== null &&
+        (typeof value !== "number" || !Number.isFinite(value) || value <= 0))
+        throw new RimeInputError("timeout must be finite positive seconds or null");
+    return value;
+}
+export function nonempty(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new RimeInputError(`${name} must be a non-empty string`);
+    return value;
+}
+export function abortable(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve(promise).then((value) => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

package/dist/queue.d.ts

@@ -0,0 +1,19 @@
+export declare class ByteQueue {
+    private readonly limit;
+    private byteCount;
+    private items;
+    private closed;
+    private error;
+    private waiters;
+    private writers;
+    private readonly chunkSize;
+    constructor(limit: number, chunkSize: number);
+    get size(): number;
+    get hasPendingOutput(): boolean;
+    private wait;
+    private wake;
+    put(data: Buffer): Promise<void>;
+    get(): Promise<IteratorResult<Uint8Array>>;
+    finish(): void;
+    fail(error: Error): void;
+}

package/dist/queue.js

@@ -0,0 +1,78 @@
+// finish() drains queued audio; fail() discards it and keeps the first error.
+// Subsequent puts discard their input. Await the last put before finish().
+// AudioStream owns consumer-observed completion and checks for cancellation
+// after awaiting get(), since cancellation can follow promise resolution.
+export class ByteQueue {
+    limit;
+    byteCount = 0;
+    items = [];
+    closed = false;
+    error = null;
+    waiters = new Set();
+    writers = 0;
+    chunkSize;
+    constructor(limit, chunkSize) {
+        this.limit = limit;
+        if (!Number.isSafeInteger(limit) ||
+            !Number.isSafeInteger(chunkSize) ||
+            limit <= 0 ||
+            chunkSize <= 0)
+            throw new RangeError("Audio queue limits must be positive integers");
+        this.chunkSize = Math.min(chunkSize, limit);
+    }
+    get size() {
+        return this.byteCount;
+    }
+    get hasPendingOutput() {
+        return this.byteCount > 0 || this.writers > 0;
+    }
+    wait() {
+        return new Promise((resolve) => this.waiters.add(resolve));
+    }
+    wake() {
+        for (const resolve of this.waiters)
+            resolve();
+        this.waiters.clear();
+    }
+    async put(data) {
+        this.writers++;
+        try {
+            for (let offset = 0; offset < data.length; offset += this.chunkSize) {
+                const part = data.subarray(offset, offset + this.chunkSize);
+                while (!this.closed && this.byteCount + part.length > this.limit)
+                    await this.wait();
+                if (this.closed)
+                    return;
+                this.items.push(part);
+                this.byteCount += part.length;
+                this.wake();
+            }
+        }
+        finally {
+            this.writers--;
+        }
+    }
+    async get() {
+        while (!this.closed && !this.items.length)
+            await this.wait();
+        if (this.error)
+            throw this.error;
+        const value = this.items.shift();
+        if (value) {
+            this.byteCount -= value.length;
+            this.wake();
+            return { done: false, value };
+        }
+        return { done: true, value: undefined };
+    }
+    finish() {
+        this.closed = true;
+        this.wake();
+    }
+    fail(error) {
+        this.error ??= error;
+        this.items = [];
+        this.byteCount = 0;
+        this.finish();
+    }
+}

package/dist/sentences.d.ts

@@ -0,0 +1,21 @@
+interface BlingFire {
+    ready: Promise<BlingFire>;
+    _malloc(n: number): number;
+    _free(p: number): void;
+    _TextToSentences(input: number, length: number, output: number, capacity: number): number;
+    HEAPU8: Uint8Array;
+}
+export declare const ready: Promise<BlingFire>;
+export declare class SentenceBuffer {
+    private limit;
+    private pending;
+    private committed;
+    private parts;
+    private untilScan;
+    private sincePunctuation;
+    private highSurrogate;
+    constructor(limit: number);
+    feed(fragment: string, final?: boolean): Generator<string>;
+    private scan;
+}
+export {};

package/dist/sentences.js

@@ -0,0 +1,142 @@
+import { createRequire } from "node:module";
+import { RimeInputError, RimeResourceLimitError } from "./errors.js";
+const require = createRequire(import.meta.url);
+const module = require("../vendor/blingfire.cjs");
+export const ready = module.ready;
+// These marks schedule scans. Only BlingFire decides sentence boundaries.
+// Keep the set and code-point counts in sync with Python's _sentences.py.
+const scanTriggers = new Set("\r\n.!?\u01c3\u06d4\u061f\u2024\u2026\u203c\u203d\u2048\u2049" +
+    "\u2404\ufe52\uff0e\uff61\u3002\uff1f\uff01\u2028\u2029\u00bf\u00a1");
+const lookahead = 16, scanInterval = 1024, contextSize = 128;
+function sentenceEnds(text) {
+    if (!text.trim())
+        return [];
+    const input = Buffer.from(text), capacity = input.length * 3 + 16;
+    const source = module._malloc(input.length + 1), output = module._malloc(capacity);
+    let normalized;
+    try {
+        module.HEAPU8.set(input, source);
+        module.HEAPU8[source + input.length] = 0;
+        const length = module._TextToSentences(source, input.length, output, capacity);
+        if (length < 0 || length > capacity)
+            throw new RimeInputError("Sentence detection failed");
+        normalized = Buffer.from(module.HEAPU8.subarray(output, output + length))
+            .toString("utf8")
+            .replace(/\0+$/, "");
+    }
+    finally {
+        module._free(source);
+        module._free(output);
+    }
+    let position = 0;
+    const ends = [];
+    for (const sentence of normalized.split("\n")) {
+        if (!sentence.trim())
+            continue;
+        for (const char of sentence) {
+            if (/\s/u.test(char))
+                continue;
+            // BlingFire removes zero-width spaces, direction marks, and BOM at
+            // boundaries. Match first to preserve marks retained inside a sentence.
+            while (position < text.length &&
+                text[position] !== char &&
+                /[\s\u200b\u200e\u200f\ufeff]/u.test(text[position]))
+                position++;
+            const original = String.fromCodePoint(text.codePointAt(position) ?? 0);
+            if (original !== char)
+                throw new RimeInputError("Sentence detector could not preserve source offsets");
+            position += char.length;
+        }
+        ends.push(position);
+    }
+    return ends;
+}
+export class SentenceBuffer {
+    limit;
+    pending = "";
+    committed = 0;
+    parts = [];
+    untilScan = scanInterval;
+    sincePunctuation = lookahead;
+    highSurrogate = "";
+    constructor(limit) {
+        this.limit = limit;
+    }
+    *feed(fragment, final = false) {
+        fragment = this.highSurrogate + fragment;
+        this.highSurrogate = "";
+        if (!final && /[\uD800-\uDBFF]$/.test(fragment)) {
+            this.highSurrogate = fragment.slice(-1);
+            fragment = fragment.slice(0, -1);
+        }
+        for (const char of fragment) {
+            this.parts.push(char);
+            this.untilScan--;
+            this.sincePunctuation = Math.min(this.sincePunctuation + 1, lookahead);
+            if (scanTriggers.has(char)) {
+                this.sincePunctuation = 0;
+                this.untilScan = Math.min(this.untilScan, lookahead);
+            }
+            if (this.untilScan === 0)
+                yield* this.scan(false);
+        }
+        if (final)
+            yield* this.scan(true);
+    }
+    *scan(final) {
+        this.pending += this.parts.join("");
+        this.parts = [];
+        if (!this.pending)
+            return;
+        const ends = sentenceEnds(this.pending);
+        if (final && ends.length)
+            ends[ends.length - 1] = this.pending.length;
+        // Retained lookahead can contain multiple separately limited sentences.
+        let start = this.committed;
+        for (const end of [...ends, this.pending.length]) {
+            if (end <= start)
+                continue;
+            if (Buffer.byteLength(this.pending.slice(start, end)) > this.limit)
+                throw new RimeResourceLimitError("Sentence exceeds the supported byte limit");
+            start = end;
+        }
+        const committedEnds = final
+            ? ends
+            : ends
+                .slice(0, -1)
+                .filter((end) => [...this.pending.slice(end).trim()].length >= lookahead);
+        for (const end of committedEnds) {
+            if (end <= this.committed)
+                continue;
+            const sentence = this.pending.slice(this.committed, end);
+            this.committed = end;
+            if (sentence.trim())
+                yield sentence;
+        }
+        if (final) {
+            const residual = this.pending.slice(this.committed);
+            if (residual.trim())
+                yield residual;
+            this.pending = "";
+            this.committed = 0;
+            this.untilScan = scanInterval;
+            this.sincePunctuation = lookahead;
+            return;
+        }
+        this.untilScan =
+            this.sincePunctuation < lookahead ? lookahead : scanInterval;
+        for (const end of ends) {
+            if (this.committed < end && end < this.pending.length) {
+                const needed = Math.max(1, lookahead - [...this.pending.slice(end).trimStart()].length);
+                this.untilScan = Math.min(this.untilScan, needed);
+                break;
+            }
+        }
+        // Bound history by code points, without cutting a UTF-16 surrogate pair.
+        const context = [...this.pending.slice(0, this.committed)]
+            .slice(-contextSize)
+            .join("");
+        this.pending = context + this.pending.slice(this.committed);
+        this.committed = context.length;
+    }
+}

package/dist/stream.d.ts

@@ -0,0 +1,48 @@
+import { AudioFormat } from "./audio.js";
+import { type PreparedConnection } from "./transport.js";
+export interface StreamOwner {
+    prepare(signal: AbortSignal): Promise<PreparedConnection>;
+    checkOpen(): void;
+    forget(stream: AudioStream): void;
+}
+export type TextSource = string | AsyncIterable<string>;
+export declare const constructionKey: unique symbol;
+export declare class AudioStream implements AsyncIterableIterator<Uint8Array> {
+    private owner;
+    private source;
+    private voice;
+    private language;
+    private formatValue;
+    private timeout;
+    private readonly controller;
+    private readonly queue;
+    private worker;
+    private timer;
+    private call;
+    private failure;
+    private finished;
+    private reading;
+    private inputDone;
+    private sourceWaiting;
+    private submitted;
+    private received;
+    private startedAt;
+    private progressAt;
+    private readonly operationId;
+    private bytesReceived;
+    private bytesDelivered;
+    constructor(key: symbol, owner: StreamOwner, source: TextSource | null, voice: string, language: string, formatValue: AudioFormat, timeout: number | null);
+    get format(): AudioFormat;
+    get requestId(): string | null;
+    private start;
+    private fail;
+    private produce;
+    private read;
+    private run;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<Uint8Array>>;
+    private cleanup;
+    cancel(): Promise<void>;
+    return(): Promise<IteratorResult<Uint8Array>>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/stream.js

@@ -0,0 +1,273 @@
+import { randomUUID } from "node:crypto";
+import { debuglog } from "node:util";
+const log = debuglog("rime-sdk");
+import { Converter } from "./audio.js";
+import { policy, abortable } from "./policy.js";
+import { ByteQueue } from "./queue.js";
+import { SentenceBuffer, ready } from "./sentences.js";
+import { SynthesisCall } from "./transport.js";
+import { RimeError, RimeInputError, RimeCancelledError, RimeTimeoutError, RimeStreamError, } from "./errors.js";
+export const constructionKey = Symbol("private stream constructor");
+export class AudioStream {
+    owner;
+    source;
+    voice;
+    language;
+    formatValue;
+    timeout;
+    controller = new AbortController();
+    queue = new ByteQueue(policy.outputBytes, policy.outputChunkBytes);
+    worker = null;
+    timer = null;
+    call = null;
+    failure = null;
+    finished = false;
+    reading = false;
+    inputDone = false;
+    sourceWaiting = false;
+    submitted = false;
+    received = false;
+    startedAt = 0;
+    progressAt = 0;
+    operationId = randomUUID();
+    bytesReceived = 0;
+    bytesDelivered = 0;
+    constructor(key, owner, source, voice, language, formatValue, timeout) {
+        this.owner = owner;
+        this.source = source;
+        this.voice = voice;
+        this.language = language;
+        this.formatValue = formatValue;
+        this.timeout = timeout;
+        if (key !== constructionKey)
+            throw new TypeError("AudioStream is returned by client.tts.stream()");
+    }
+    get format() {
+        return this.formatValue;
+    }
+    get requestId() {
+        return this.call?.requestId ?? null;
+    }
+    start() {
+        if (this.failure)
+            throw this.failure;
+        if (this.finished || this.worker)
+            return;
+        this.owner.checkOpen();
+        this.startedAt = performance.now();
+        this.worker = this.run();
+        this.timer = setInterval(() => {
+            if (this.finished || this.failure)
+                return;
+            const now = performance.now();
+            if (this.timeout !== null &&
+                now - this.startedAt >= this.timeout * 1000) {
+                this.fail(new RimeTimeoutError("Overall synthesis deadline expired", this.requestId));
+                return;
+            }
+            if (this.call &&
+                !this.call.done &&
+                this.submitted &&
+                !this.sourceWaiting &&
+                !this.queue.hasPendingOutput) {
+                const limit = this.received
+                    ? policy.progressTimeout
+                    : policy.firstAudioTimeout;
+                if (now - this.progressAt >= limit * 1000)
+                    this.fail(new RimeTimeoutError("Synthesis output stopped making progress", this.requestId));
+            }
+            else
+                this.progressAt = now;
+        }, 20);
+    }
+    fail(error) {
+        if (this.finished || this.failure)
+            return;
+        if (error.requestId === null && this.requestId !== null)
+            error = new error.constructor(error.message, this.requestId, { cause: error.cause });
+        this.failure = error;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.queue.fail(error);
+        this.controller.abort(error);
+        this.call?.cancel();
+    }
+    async produce() {
+        const source = this.source;
+        let iterator;
+        const buffer = new SentenceBuffer(policy.sentenceBytes);
+        let meaningful = false;
+        try {
+            try {
+                iterator = (typeof source === "string"
+                    ? (async function* () {
+                        yield source;
+                    })()
+                    : source)[Symbol.asyncIterator]();
+            }
+            catch (error) {
+                if (this.controller.signal.aborted)
+                    throw this.controller.signal.reason;
+                throw new RimeInputError("The text source failed", this.requestId, {
+                    cause: error,
+                });
+            }
+            for (;;) {
+                this.sourceWaiting = true;
+                let result;
+                try {
+                    result = await abortable(iterator.next(), this.controller.signal);
+                }
+                catch (error) {
+                    if (this.controller.signal.aborted)
+                        throw this.controller.signal.reason;
+                    throw new RimeInputError("The text source failed", this.requestId, {
+                        cause: error,
+                    });
+                }
+                finally {
+                    this.sourceWaiting = false;
+                }
+                if (result.done)
+                    break;
+                const chunk = result.value;
+                if (typeof chunk !== "string")
+                    throw new RimeInputError("The text source must yield strings");
+                if (chunk.trim())
+                    meaningful = true;
+                // Never split a surrogate pair when limiting native detector input size.
+                for (let offset = 0; offset < chunk.length;) {
+                    let end = Math.min(chunk.length, offset + policy.sourceChars);
+                    if (end < chunk.length && /[\uD800-\uDBFF]/.test(chunk[end - 1]))
+                        end++;
+                    for (const sentence of buffer.feed(chunk.slice(offset, end))) {
+                        if (!this.submitted)
+                            this.progressAt = performance.now();
+                        this.submitted = true;
+                        await this.call.write(sentence);
+                    }
+                    offset = end;
+                }
+            }
+            if (!meaningful)
+                throw new RimeInputError("The text source contained no meaningful text");
+            for (const sentence of buffer.feed("", true)) {
+                if (!this.submitted)
+                    this.progressAt = performance.now();
+                this.submitted = true;
+                await this.call.write(sentence);
+            }
+            this.call.finishInput();
+            this.inputDone = true;
+        }
+        catch (error) {
+            if (error instanceof RimeError || this.controller.signal.aborted)
+                throw error;
+            throw new RimeInputError("The text source failed", this.requestId, {
+                cause: error,
+            });
+        }
+        finally {
+            if (iterator?.return) {
+                const cleanup = Promise.resolve(iterator.return());
+                cleanup.catch(() => { });
+                let timer;
+                await Promise.race([
+                    cleanup,
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, policy.cleanupTimeout * 1000);
+                    }),
+                ]).catch(() => { });
+                clearTimeout(timer);
+            }
+        }
+    }
+    async read() {
+        const converter = new Converter(this.format);
+        for await (const data of this.call.audio()) {
+            this.progressAt = performance.now();
+            if (data.length) {
+                this.received = true;
+                this.bytesReceived += data.length;
+                await this.queue.put(converter.process(data));
+            }
+        }
+        if (!this.inputDone)
+            throw new RimeStreamError("The service completed before input finished", this.requestId);
+        await this.queue.put(converter.process(new Uint8Array(), true));
+    }
+    async run() {
+        let tasks = [];
+        try {
+            await abortable(ready, this.controller.signal);
+            const prepared = await this.owner.prepare(this.controller.signal);
+            this.call = new SynthesisCall(prepared, this.controller.signal);
+            await this.call.start(this.voice, this.language);
+            tasks = [this.produce(), this.read()];
+            await Promise.all(tasks);
+            this.queue.finish();
+        }
+        catch (error) {
+            if (error instanceof RimeError)
+                this.fail(error);
+            else
+                this.fail(new RimeStreamError("Synthesis failed", this.requestId, {
+                    cause: error,
+                }));
+        }
+        finally {
+            if (this.failure)
+                this.controller.abort(this.failure);
+            await Promise.allSettled(tasks);
+            this.source = null;
+            if (this.failure)
+                this.owner.forget(this);
+            log("operation=%s request=%s received=%d delivered=%d duration_ms=%d", this.operationId, this.requestId, this.bytesReceived, this.bytesDelivered, Math.round(performance.now() - this.startedAt));
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    async next() {
+        if (this.reading)
+            throw new RimeInputError("AudioStream permits only one concurrent reader");
+        this.reading = true;
+        try {
+            this.start();
+            const result = await this.queue.get();
+            if (this.failure)
+                throw this.failure;
+            if (result.done) {
+                await this.cleanup();
+                if (this.failure)
+                    throw this.failure;
+                this.finished = true;
+            }
+            if (!result.done)
+                this.bytesDelivered += result.value.byteLength;
+            return result;
+        }
+        finally {
+            this.reading = false;
+        }
+    }
+    async cleanup() {
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.worker;
+        this.owner.forget(this);
+    }
+    async cancel() {
+        if (!this.finished && !this.failure)
+            this.fail(new RimeCancelledError("Synthesis cancelled", this.requestId));
+        await this.cleanup();
+        this.source = null;
+    }
+    async return() {
+        await this.cancel();
+        return { done: true, value: undefined };
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cancel();
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,34 @@
+import * as grpc from "@grpc/grpc-js";
+import * as errors from "./errors.js";
+export type Connection = grpc.Client;
+export interface PreparedConnection {
+    client: Connection;
+    metadata: grpc.Metadata;
+}
+export type DiscoveryKind = "voices" | "languages";
+export declare function rpcError(code: number, requestId?: string | null): errors.RimeError;
+export declare const transport: {
+    makeClient: (target: string) => grpc.Client;
+};
+export declare function connect(client: grpc.Client, signal: AbortSignal): Promise<void>;
+export declare function metadata(value: string): grpc.Metadata;
+export declare function discover(prepared: PreparedConnection, kind: DiscoveryKind, language: string | null | undefined, signal: AbortSignal): Promise<string[]>;
+export declare class SynthesisCall {
+    private signal;
+    private readonly call;
+    private readonly metadataPromise;
+    private readonly statusPromise;
+    private status;
+    private id;
+    constructor(prepared: PreparedConnection, signal: AbortSignal);
+    get requestId(): string | null;
+    get done(): boolean;
+    cancel(): void;
+    private error;
+    private writeMessage;
+    start(voice: string, language: string): Promise<void>;
+    write(sentence: string): Promise<void>;
+    finishInput(): void;
+    private checkFormat;
+    audio(): AsyncGenerator<Uint8Array>;
+}