@rimelabs/sdk 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/client.js

@@ -1,18 +1,18 @@
-import { AudioFormat } from "./audio.js";
-import { AudioStream, constructionKey } from "./stream.js";
+import { STT } from "./stt/client.js";
 import { Credentials } from "./auth.js";
-import { policy, resolve, timeout, nonempty, abortable } from "./policy.js";
-import { transport, connect, metadata, discover, } from "./transport.js";
-import { RimeAuthenticationError, RimeInputError, RimeAudioFormatError, RimeCancelledError, RimeTimeoutError, RimeUnavailableError, } from "./errors.js";
+import { RimeAuthenticationError, RimeInputError } from "./errors.js";
+import { TTS, } from "./tts/client.js";
+import { resolve, timeout } from "./tts/policy.js";
+import { Realtime } from "./realtime/client.js";
 export class Rime {
-    deployment;
     credentials;
-    client = null;
+    ttsClient;
+    sttClient;
+    stt;
+    realtimeClient;
+    realtime;
     closed = false;
-    streams = new Set();
-    discoveryControllers = new Set();
     closing = null;
-    defaultTimeout;
     tts;
     voices;
     languages;
@@ -22,99 +22,48 @@ export class Rime {
             : options.apiKey;
         if (typeof key !== "string" || !key.trim())
             throw new RimeAuthenticationError("Provide apiKey or set RIME_API_KEY");
-        this.defaultTimeout = timeout(options.timeout);
-        this.deployment = resolve(options.model ?? "coda", options.endpoint);
-        this.credentials = new Credentials(key, this.deployment);
-        this.tts = { stream: (text, options = {}) => this.stream(text, options) };
-        this.voices = {
-            list: async (options = {}) => {
-                if (options.language !== undefined && options.language !== null)
-                    nonempty(options.language, "language");
-                return this.discover("voices", options.language, options.timeout);
-            },
+        const defaultTimeout = timeout(options.timeout);
+        const deployment = resolve(options.model ?? "coda", options.endpoint);
+        this.credentials = new Credentials(key, deployment);
+        this.sttClient = new STT(this.credentials, () => this.checkOpen());
+        this.stt = {
+            transcribe: (audio, options) => this.sttClient.transcribe(audio, options),
+            stream: (audio, options) => this.sttClient.stream(audio, options),
         };
-        this.languages = {
-            list: (options = {}) => this.discover("languages", undefined, options.timeout),
+        this.realtimeClient = new Realtime(this.credentials, () => this.checkOpen());
+        this.realtime = {
+            connect: (options) => this.realtimeClient.connect(options),
         };
+        this.ttsClient = new TTS(this.credentials, deployment, defaultTimeout, () => this.checkOpen());
+        this.tts = {
+            synthesize: (text, options) => this.ttsClient.synthesize(text, options),
+            synthesizeToBuffer: (text, options) => this.ttsClient.synthesizeToBuffer(text, options),
+            stream: (text, options) => this.ttsClient.stream(text, options),
+        };
+        this.voices = this.ttsClient.voices;
+        this.languages = this.ttsClient.languages;
     }
     checkOpen() {
         if (this.closed)
             throw new RimeInputError("The Rime client is closed");
     }
-    async prepare(signal) {
-        this.checkOpen();
-        const auth = await this.credentials.metadata(signal);
-        this.checkOpen();
-        this.client ??= transport.makeClient(this.deployment.target);
-        await connect(this.client, signal);
-        return { client: this.client, metadata: metadata(auth) };
-    }
-    stream(text, options) {
-        this.checkOpen();
-        if (typeof text === "string") {
-            if (!text.trim())
-                throw new RimeInputError("Text must contain non-whitespace characters");
-        }
-        else if (!text || typeof text[Symbol.asyncIterator] !== "function")
-            throw new RimeInputError("text must be a string or an async iterable of strings");
-        const voice = options.voice === undefined || options.voice === null
-            ? this.deployment.defaultVoice
-            : nonempty(options.voice, "voice");
-        const language = nonempty(options.language ?? "en", "language");
-        const format = options.audioFormat ?? AudioFormat.PCM_24000;
-        if (format !== AudioFormat.PCM_24000 && format !== AudioFormat.MULAW_8000)
-            throw new RimeAudioFormatError("Select a named AudioFormat profile");
-        const audio = new AudioStream(constructionKey, {
-            prepare: (s) => this.prepare(s),
-            checkOpen: () => this.checkOpen(),
-            forget: (s) => this.streams.delete(s),
-        }, text, voice, language, format, timeout(options.timeout, this.defaultTimeout));
-        this.streams.add(audio);
-        return audio;
-    }
-    async discover(kind, language, override) {
-        this.checkOpen();
-        const budget = Math.min(timeout(override, this.defaultTimeout) ?? Infinity, policy.discoveryTimeout);
-        const controller = new AbortController();
-        let requestId = null;
-        this.discoveryControllers.add(controller);
-        const timer = setTimeout(() => controller.abort(new RimeTimeoutError("Discovery deadline expired")), budget * 1000);
-        try {
-            const prepared = await this.prepare(controller.signal);
-            for (let attempt = 0;; attempt++) {
-                requestId = null;
-                try {
-                    return await discover(prepared, kind, language, controller.signal);
-                }
-                catch (error) {
-                    if (!(error instanceof RimeUnavailableError) || attempt === 2)
-                        throw error;
-                    requestId = error.requestId;
-                    await abortable(new Promise((resolve) => setTimeout(resolve, 50 * 2 ** attempt)), controller.signal);
-                }
-            }
-        }
-        catch (error) {
-            if (error instanceof RimeTimeoutError && requestId !== null)
-                throw new RimeTimeoutError(error.message, requestId, {
-                    cause: error.cause,
-                });
-            throw error;
-        }
-        finally {
-            clearTimeout(timer);
-            this.discoveryControllers.delete(controller);
-        }
-    }
     async close() {
         if (!this.closing) {
             this.closed = true;
             this.closing = (async () => {
-                for (const controller of this.discoveryControllers)
-                    controller.abort(new RimeCancelledError("Client closed during discovery"));
-                await Promise.all([...this.streams].map((stream) => stream.cancel()));
-                await this.credentials.close();
-                this.client?.close();
+                try {
+                    const results = await Promise.allSettled([
+                        this.ttsClient.close(),
+                        this.sttClient.close(),
+                        this.realtimeClient.close(),
+                    ]);
+                    for (const result of results)
+                        if (result.status === "rejected")
+                            throw result.reason;
+                }
+                finally {
+                    await this.credentials.close();
+                }
             })();
         }
         await this.closing;

package/dist/grpc.d.ts

@@ -0,0 +1,27 @@
+import * as grpc from "@grpc/grpc-js";
+import { type DescMessage, type MessageShape } from "@bufbuild/protobuf";
+import * as errors from "./errors.js";
+export declare function rpcError(code: number, requestId?: string | null, details?: string): errors.RimeError;
+export declare function serializer<D extends DescMessage>(desc: D): (message: MessageShape<D>) => Buffer<ArrayBuffer>;
+export declare function deserializer<D extends DescMessage>(desc: D): (data: Buffer) => MessageShape<D>;
+export declare function requestId(metadata?: grpc.Metadata): string | null;
+export declare function nativeError(error: unknown, id: string | null): errors.RimeError;
+export declare class BidiCall<Input, Output> {
+    private readonly call;
+    private signal;
+    private readonly metadataPromise;
+    private readonly statusPromise;
+    private status;
+    private id;
+    constructor(call: grpc.ClientDuplexStream<Input, Output>, signal: AbortSignal);
+    get requestId(): string | null;
+    get done(): boolean;
+    cancel(): void;
+    private error;
+    headers(): Promise<grpc.Metadata>;
+    responses(): AsyncGenerator<Output>;
+    write(message: Input): Promise<void>;
+    finishInput(): void;
+}
+export declare function connect(client: grpc.Client, signal: AbortSignal, seconds: number): Promise<void>;
+export declare function metadata(value: string): grpc.Metadata;

package/dist/grpc.js

@@ -0,0 +1,175 @@
+import { abortable } from "./cancellation.js";
+import * as grpc from "@grpc/grpc-js";
+import { fromBinary, toBinary, } from "@bufbuild/protobuf";
+import * as errors from "./errors.js";
+export function rpcError(code, requestId = null, details) {
+    const classes = {
+        [grpc.status.UNAUTHENTICATED]: errors.RimeAuthenticationError,
+        [grpc.status.PERMISSION_DENIED]: errors.RimePermissionError,
+        [grpc.status.INVALID_ARGUMENT]: errors.RimeInputError,
+        [grpc.status.RESOURCE_EXHAUSTED]: errors.RimeResourceLimitError,
+        [grpc.status.UNAVAILABLE]: errors.RimeUnavailableError,
+        [grpc.status.DEADLINE_EXCEEDED]: errors.RimeTimeoutError,
+        [grpc.status.CANCELLED]: errors.RimeCancelledError,
+    };
+    const ErrorType = classes[code] ?? errors.RimeStreamError;
+    return new ErrorType(details?.trim()
+        ? details
+        : `Rime operation failed: ${grpc.status[code] ?? "UNKNOWN"}`, requestId);
+}
+export function serializer(desc) {
+    return (message) => Buffer.from(toBinary(desc, message));
+}
+export function deserializer(desc) {
+    return (data) => fromBinary(desc, data);
+}
+export function requestId(metadata) {
+    return metadata?.get("x-request-id")[0]?.toString() ?? null;
+}
+export function nativeError(error, id) {
+    if (error instanceof errors.RimeError)
+        return error;
+    if (error &&
+        typeof error === "object" &&
+        "code" in error &&
+        typeof error.code === "number") {
+        const metadata = "metadata" in error ? error.metadata : null;
+        return rpcError(error.code, id ?? (metadata instanceof grpc.Metadata ? requestId(metadata) : null), "details" in error && typeof error.details === "string"
+            ? error.details
+            : undefined);
+    }
+    return new errors.RimeStreamError("Rime transport failed", id, {
+        cause: error,
+    });
+}
+export class BidiCall {
+    call;
+    signal;
+    metadataPromise;
+    statusPromise;
+    status = null;
+    id = null;
+    constructor(call, signal) {
+        this.call = call;
+        this.signal = signal;
+        this.metadataPromise = new Promise((resolve, reject) => {
+            this.call.once("metadata", (metadata) => {
+                this.id = requestId(metadata);
+                resolve(metadata);
+            });
+            // A trailers-only response has no metadata event.
+            this.call.once("status", () => resolve(new grpc.Metadata()));
+            this.call.once("error", reject);
+        });
+        this.metadataPromise.catch(() => { });
+        this.statusPromise = new Promise((resolve) => {
+            this.call.once("status", (status) => {
+                this.status = status;
+                this.id ??= requestId(status.metadata);
+                resolve(status);
+            });
+        });
+        this.call.on("error", () => { });
+    }
+    get requestId() {
+        return this.id;
+    }
+    get done() {
+        return this.status !== null || this.call.destroyed;
+    }
+    cancel() {
+        this.call.cancel();
+    }
+    error(error) {
+        const failure = nativeError(error, this.id);
+        this.id ??= failure.requestId;
+        return failure;
+    }
+    async headers() {
+        try {
+            return await abortable(this.metadataPromise, this.signal);
+        }
+        catch (error) {
+            if (this.signal.aborted)
+                throw this.signal.reason;
+            throw this.error(error);
+        }
+    }
+    async *responses() {
+        try {
+            await this.headers();
+            const responses = this.call;
+            for await (const response of responses)
+                yield response;
+            const status = await abortable(this.statusPromise, this.signal);
+            if (status.code !== grpc.status.OK)
+                throw rpcError(status.code, this.id, status.details);
+        }
+        catch (error) {
+            if (this.signal.aborted)
+                throw this.signal.reason;
+            throw this.error(error);
+        }
+    }
+    async write(message) {
+        try {
+            this.signal.throwIfAborted();
+            if (this.status) {
+                if (this.status.code !== grpc.status.OK)
+                    throw rpcError(this.status.code, this.id, this.status.details);
+                throw new errors.RimeStreamError("The service completed before input finished", this.id);
+            }
+            await abortable(new Promise((resolve, reject) => {
+                const finish = (error) => {
+                    this.call.removeListener("status", onStatus);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                // A rejected native write can emit final status without invoking its
+                // callback (for example, when exceeding the send-message limit).
+                const onStatus = (status) => finish(status.code === grpc.status.OK
+                    ? new errors.RimeStreamError("The service completed before input finished", this.id)
+                    : rpcError(status.code, this.id, status.details));
+                this.call.once("status", onStatus);
+                try {
+                    this.call.write(message, finish);
+                }
+                catch (error) {
+                    finish(error);
+                }
+            }), this.signal);
+        }
+        catch (error) {
+            if (this.signal.aborted)
+                throw this.signal.reason;
+            if (error instanceof errors.RimeError)
+                throw error;
+            // A native write error can precede the final status event. Preserve the
+            // server rejection even if the reader has not consumed a response.
+            const status = await abortable(this.statusPromise, this.signal);
+            if (status.code !== grpc.status.OK)
+                throw rpcError(status.code, this.id, status.details);
+            throw this.error(error);
+        }
+    }
+    finishInput() {
+        try {
+            this.call.end();
+        }
+        catch (error) {
+            throw this.error(error);
+        }
+    }
+}
+export async function connect(client, signal, seconds) {
+    await abortable(new Promise((resolve, reject) => client.waitForReady(Date.now() + seconds * 1000, (error) => error
+        ? reject(new errors.RimeTimeoutError("Connection establishment timed out"))
+        : resolve())), signal);
+}
+export function metadata(value) {
+    const result = new grpc.Metadata();
+    result.set("authorization", value);
+    return result;
+}

package/dist/index.d.ts

@@ -1,4 +1,12 @@
 export { Rime, type RimeOptions, type SynthesisOptions, type DiscoveryOptions, type VoiceListOptions, } from "./client.js";
-export { AudioStream } from "./stream.js";
-export { AudioFormat } from "./audio.js";
+export { AudioStream } from "./tts/stream.js";
+export { AudioFormat } from "./tts/audio.js";
+export type { PronunciationEntry } from "./tts/lexicon.js";
+export type { TimestampResult, TimestampStatus, WordTimestamp, } from "./tts/timestamps.js";
 export * from "./errors.js";
+export { RealtimeSession } from "./realtime/session.js";
+export * from "./realtime/types.js";
+export { TranscriptStream } from "./stt/stream.js";
+export type { AudioSource, TranscribeOptions, Transcription, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionDelta, TranscriptionOutputContract, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";
+export { runConversation } from "./realtime/conversation.js";
+export type { ConversationSource, ConversationOutput, ConversationPlayback, ConversationOptions, } from "./realtime/conversation.js";

package/dist/index.js

@@ -1,4 +1,8 @@
 export { Rime, } from "./client.js";
-export { AudioStream } from "./stream.js";
-export { AudioFormat } from "./audio.js";
+export { AudioStream } from "./tts/stream.js";
+export { AudioFormat } from "./tts/audio.js";
 export * from "./errors.js";
+export { RealtimeSession } from "./realtime/session.js";
+export * from "./realtime/types.js";
+export { TranscriptStream } from "./stt/stream.js";
+export { runConversation } from "./realtime/conversation.js";

package/dist/pcm.d.ts

@@ -0,0 +1,21 @@
+/** Headerless signed little-endian PCM16; stereo samples are interleaved. */
+export interface PCMFormat {
+    /** Input frames per second; omitted means 16000. */
+    readonly sampleRate?: 8000 | 16000 | 24000 | 48000;
+    /** Samples per frame; omitted means one (mono). */
+    readonly channels?: 1 | 2;
+    /** Two-byte signed samples with no file header. */
+    readonly encoding?: "pcm_s16le";
+}
+export declare function resolvePCMFormat(input?: PCMFormat): Required<PCMFormat>;
+/** Streaming linear interpolation, matching Python audioop.ratecv with no filter.
+ * Integer phase remains bounded and preserves samples across chunk boundaries.
+ */
+export declare class InputConverter {
+    readonly format: Required<PCMFormat>;
+    private phase;
+    private previous;
+    constructor(format: Required<PCMFormat>);
+    clone(): InputConverter;
+    process(input: Uint8Array): Buffer;
+}

package/dist/pcm.js

@@ -0,0 +1,52 @@
+import { RimeAudioFormatError } from "./errors.js";
+export function resolvePCMFormat(input) {
+    if (input !== undefined &&
+        (input === null || typeof input !== "object" || Array.isArray(input)))
+        throw new RimeAudioFormatError("Input format must be a PCM format object");
+    const format = {
+        sampleRate: input?.sampleRate ?? 16000,
+        channels: input?.channels ?? 1,
+        encoding: input?.encoding ?? "pcm_s16le",
+    };
+    if (![8000, 16000, 24000, 48000].includes(format.sampleRate) ||
+        ![1, 2].includes(format.channels) ||
+        format.encoding !== "pcm_s16le")
+        throw new RimeAudioFormatError("Use PCM16 at 8, 16, 24 or 48 kHz, with one or two channels");
+    return format;
+}
+/** Streaming linear interpolation, matching Python audioop.ratecv with no filter.
+ * Integer phase remains bounded and preserves samples across chunk boundaries.
+ */
+export class InputConverter {
+    format;
+    phase = -16000;
+    previous = 0;
+    constructor(format) {
+        this.format = format;
+    }
+    clone() {
+        const copy = new InputConverter(this.format);
+        copy.phase = this.phase;
+        copy.previous = this.previous;
+        return copy;
+    }
+    process(input) {
+        const data = Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+        const samples = [];
+        for (let offset = 0; offset < data.length; offset += this.format.channels * 2) {
+            const current = this.format.channels === 1
+                ? data.readInt16LE(offset)
+                : Math.floor((data.readInt16LE(offset) + data.readInt16LE(offset + 2)) / 2);
+            this.phase += 16000;
+            while (this.phase >= 0) {
+                samples.push(Math.floor((this.previous * this.phase + current * (16000 - this.phase)) /
+                    16000));
+                this.phase -= this.format.sampleRate;
+            }
+            this.previous = current;
+        }
+        const output = Buffer.alloc(samples.length * 2);
+        samples.forEach((sample, index) => output.writeInt16LE(sample, index * 2));
+        return output;
+    }
+}

package/dist/realtime/async.d.ts

@@ -0,0 +1,23 @@
+export { scope } from "../cancellation.js";
+export declare class Deferred<T> {
+    readonly promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: unknown) => void;
+    constructor();
+}
+export declare class Flag {
+    private waiters;
+    isSet: boolean;
+    set(): void;
+    clear(): void;
+    wait(signal: AbortSignal): Promise<void>;
+}
+export declare class Mutex {
+    private locked;
+    private waiters;
+    acquire(signal: AbortSignal): Promise<() => void>;
+}
+export declare function cancellation(signal?: AbortSignal): {
+    signal: AbortSignal;
+    dispose: () => void | undefined;
+};

package/dist/realtime/async.js

@@ -0,0 +1,87 @@
+export { scope } from "../cancellation.js";
+import { abortable } from "../cancellation.js";
+import { RimeCancelledError } from "../errors.js";
+export class Deferred {
+    promise;
+    resolve;
+    reject;
+    constructor() {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        // Session failures can arrive before a caller starts waiting.
+        this.promise.catch(() => { });
+    }
+}
+export class Flag {
+    waiters = new Set();
+    isSet = false;
+    set() {
+        this.isSet = true;
+        for (const wake of this.waiters)
+            wake();
+    }
+    clear() {
+        this.isSet = false;
+    }
+    wait(signal) {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        if (this.isSet)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.waiters.delete(wake);
+                signal.removeEventListener("abort", abort);
+            };
+            const wake = () => {
+                cleanup();
+                resolve();
+            };
+            const abort = () => {
+                cleanup();
+                reject(signal.reason);
+            };
+            this.waiters.add(wake);
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+}
+export class Mutex {
+    locked = false;
+    waiters = new Set();
+    async acquire(signal) {
+        signal.throwIfAborted();
+        while (this.locked) {
+            const wake = new Deferred();
+            const notify = () => wake.resolve();
+            this.waiters.add(notify);
+            try {
+                await abortable(wake.promise, signal);
+            }
+            finally {
+                this.waiters.delete(notify);
+            }
+            signal.throwIfAborted();
+        }
+        this.locked = true;
+        return () => {
+            this.locked = false;
+            for (const wake of this.waiters)
+                wake();
+        };
+    }
+}
+export function cancellation(signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(new RimeCancelledError("Realtime operation cancelled"));
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => signal?.removeEventListener("abort", abort),
+    };
+}

package/dist/realtime/audio.d.ts

@@ -0,0 +1,2 @@
+import type { AudioChunk, PCMFormat } from "./types.js";
+export declare function formatOf(chunk: AudioChunk): Required<PCMFormat>;

package/dist/realtime/audio.js

@@ -0,0 +1,11 @@
+import { RimeAudioFormatError } from "../errors.js";
+import { resolvePCMFormat } from "../pcm.js";
+export function formatOf(chunk) {
+    const format = resolvePCMFormat(chunk.format);
+    if (!(chunk.data instanceof Uint8Array) ||
+        chunk.data.length % (2 * format.channels))
+        throw new RimeAudioFormatError("Audio must contain complete PCM16 frames as Uint8Array");
+    if (chunk.data.length > 192000)
+        throw new RimeAudioFormatError("Send audio in chunks of at most 192000 bytes");
+    return format;
+}

package/dist/realtime/client.d.ts

@@ -0,0 +1,12 @@
+import { Credentials } from "../auth.js";
+import { RealtimeSession } from "./session.js";
+import type { RealtimeConnectOptions } from "./types.js";
+export declare class Realtime {
+    private readonly credentials;
+    private readonly checkOpen;
+    private readonly sessions;
+    private readonly opening;
+    constructor(credentials: Credentials, checkOpen: () => void);
+    connect(options?: RealtimeConnectOptions): Promise<RealtimeSession>;
+    close(): Promise<void>;
+}