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

package/README.md

@@ -1,166 +1,331 @@
-# Rime SDK for Node.js
+# Rime SDK for TypeScript and Node.js
 
-Stream speech from a string or async text source with Rime.
+Generate speech with Coda or Mist v3, transcribe audio with STT, and build spoken
+conversations with Prism through the `Rime` client. Your application handles
+audio capture and playback.
 
-## Install
+## Installation
 
-Requires Node.js 22 or later. This alpha package uses ESM and includes TypeScript
-types. Browser use is not supported.
+Requires **Node.js 22 or later**. Install the alpha package from npm. It uses
+ESM, includes TypeScript types, and runs on a server; browsers are not supported.
 
 ```sh
-npm install @rimelabs/sdk@next
+mkdir rime-quickstart
+cd rime-quickstart
+npm init -y
+npm install @rimelabs/sdk wavefile
 export RIME_API_KEY="your-api-key"
 ```
 
-## Quick start
+For an existing project, skip the first three commands. Get an API key from the
+[Rime dashboard](https://app.rime.ai/). A key is required: `new Rime()` reads
+`RIME_API_KEY`, or you can pass `new Rime({ apiKey: "..." })` to override it.
+The SDK does not load `.env` files. Shell commands below assume macOS or Linux.
 
-Save this as `speech.mjs` and run `node speech.mjs`:
+Examples use JavaScript `.mjs` files so you can run them without a TypeScript build.
+The additional `wavefile` dependency is only needed by the Prism example; TTS and
+STT use the SDK and Node.js built-ins.
+
+## Prism: send recorded speech
+
+With `RIME_API_KEY` set, the SDK connects to
+`wss://prism.api.rime.ai/v1/realtime` and uses the server's default voice.
+Pass `endpoint` or `voice` to select another deployment or voice.
+
+Record a short question and export it as `question.wav`, using **16 kHz, mono, signed 16-bit PCM WAV**.
+Save the following as `prism.mjs` beside that file. It sends the recording at capture speed,
+then sends silence so Prism can detect the end of speech. The spoken reply goes to `reply.wav`.
 
 ```javascript
-import { writeFile } from "node:fs/promises";
-import { Rime } from "@rimelabs/sdk";
+import { readFileSync, writeFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import wavefile from "wavefile";
+import { Rime, RimeRealtimeError } from "@rimelabs/sdk";
+
+const input = new wavefile.WaveFile(readFileSync("question.wav"));
+if (
+  input.container !== "RIFF" ||
+  input.fmt.audioFormat !== 1 ||
+  input.fmt.numChannels !== 1 ||
+  input.fmt.sampleRate !== 16000 ||
+  input.bitDepth !== "16"
+) {
+  throw new Error("question.wav must be 16 kHz mono PCM16");
+}
+const data = Buffer.from(input.data.samples);
+if (!data.length || data.length % 2)
+  throw new Error("question.wav has no complete PCM16 audio");
 
 const client = new Rime();
+const stop = new AbortController();
+const deadline = setTimeout(() => {
+  stop.abort();
+  void client.close();
+}, 60_000);
+let sending;
+let reading;
 try {
-  const audio = client.tts.stream("Hello. This is Rime.");
-  await writeFile("speech.pcm", audio);
-  console.log(audio.requestId);
+  const session = await client.realtime.connect({
+    instructions: "Give short, clear answers.",
+  });
+  sending = (async () => {
+    for (let offset = 0; ; offset += 1280) {
+      const frame = Buffer.alloc(1280);
+      if (offset < data.length)
+        data.copy(frame, 0, offset, Math.min(offset + 1280, data.length));
+      await session.sendAudio({ data: frame });
+      await sleep(40, undefined, { signal: stop.signal });
+    }
+  })();
+  const chunks = [];
+  reading = (async () => {
+    for await (const { payload } of session.events) {
+      if (payload.kind === "audio.delta")
+        chunks.push(Buffer.from(payload.audio.data));
+      if (payload.kind === "error") throw new RimeRealtimeError(payload.error);
+      if (payload.kind === "response.ended") {
+        if (payload.status !== "completed") {
+          throw new Error(`Response ${payload.status}: ${payload.reason}`);
+        }
+        return;
+      }
+    }
+    throw new Error("Session closed before the reply ended");
+  })();
+  await Promise.race([sending, reading]);
+  const pcm = Buffer.concat(chunks);
+  const samples = Array.from({ length: pcm.length / 2 }, (_, i) =>
+    pcm.readInt16LE(i * 2),
+  );
+  const wav = new wavefile.WaveFile();
+  wav.fromScratch(1, 24000, "16", samples);
+  writeFileSync("reply.wav", wav.toBuffer());
+  console.log("Saved reply.wav");
 } finally {
+  stop.abort();
+  clearTimeout(deadline);
   await client.close();
+  await Promise.allSettled([sending, reading]);
 }
 ```
 
-Output is raw mono 24 kHz signed 16-bit little-endian PCM. Configure your player
-for this format; there is no WAV header.
+Run `node prism.mjs`, then open `reply.wav`. This example has a 60-second deadline
+and collects the reply in memory. It saves audio without playing it, so it sends no playback receipt.
+For live conversations, your application must capture microphone audio, play replies,
+stop playback on interruption, and report the actual played position to Prism.
+Keep the API key on your server when you add a browser interface.
+TTS settings do not configure Prism sessions.
 
-## Stream incoming text
-
-Add this async text source before the client declaration in the quick start:
-
-```javascript
-async function* text() {
-  yield "Hello. ";
-  yield "This text arrives in separate chunks.";
-}
-```
+## TTS
 
-Use `client.tts.stream(text())` with the same file write and cleanup.
-The SDK handles sentence boundaries. Do not await `tts.stream()`; the first
-iterator read starts work. `writeFile` consumes the stream for you.
+Use `client.tts.synthesize(text, options)` for a complete string, or
+`client.tts.stream(textChunks, options)` for an async iterable of strings.
+Both return an `AudioStream` immediately; consume it with `for await`, without
+awaiting the method call. For complete audio in memory, await
+`client.tts.synthesizeToBuffer(text, options)` to receive a Node.js `Buffer`.
+Text is required and must contain non-whitespace characters.
 
-## Configuration
+### Client options
 
-Select Mist v3 with `new Rime({ model: "mistv3" })`. Mist v1 and v2 are not supported.
+These optional `new Rime({...})` fields configure TTS. They do not configure STT or Prism.
 
-| Model | Standard endpoint | Default voice |
-| --- | --- | --- |
-| `coda` | `coda.api.rime.ai:443` | `clementine` |
-| `mistv3` | `mist.api.rime.ai:443` | `astra` |
+| Option | Purpose and values | Required | Default |
+| --- | --- | --- | --- |
+| `model` | Select `"coda"` or `"mistv3"`. | No | `"coda"` |
+| `endpoint` | Override the TTS TLS hostname and optional port, such as `"coda.api.rime.ai:443"`; no scheme or path. | No | `coda.api.rime.ai:443` for Coda; `mist.api.rime.ai:443` for Mist v3. |
+| `timeout` | Overall TTS timeout in positive seconds, such as `60`; `null` disables it. | No | No overall timeout. |
 
-### Client options
+### Synthesis options
 
-| `new Rime({ ... })` option | Default | Meaning |
-| --- | --- | --- |
-| `apiKey` | `RIME_API_KEY` | API key; an explicit value overrides the environment |
-| `model` | `"coda"` | Model for speech and discovery |
-| `endpoint` | Model's standard endpoint | Custom hostname and optional port for speech and discovery |
-| `timeout` | No overall deadline | Positive seconds; `null` disables the overall deadline |
+All three TTS methods accept the same `SynthesisOptions` fields. Import
+`AudioFormat` from `@rimelabs/sdk` when selecting an encoding.
 
-Authentication uses bearer tokens over TLS. The SDK does not load `.env` files.
+| Option | Purpose and values | Required | Default |
+| --- | --- | --- | --- |
+| `voice` | Voice name for the selected model, such as `"clementine"` or `"astra"`. | No | `"clementine"` for Coda; `"astra"` for Mist v3. |
+| `language` | Spoken language code, such as `"en"` or `"es"`; the service validates support. | No | `"en"` |
+| `audioFormat` | Output encoding: `AudioFormat.PCM`, `.WAV`, `.MP3`, `.PCM_24000`, or `.MULAW_8000`. | No | Raw PCM16 at 24 kHz (`PCM_24000`). |
+| `sampleRate` | Requested output rate in Hz: `8000`, `16000`, or `24000`. | No | `24000`; `8000` for `MULAW_8000`. |
+| `timeScaleFactor` | Duration multiplier from `0.4` to `2.5`; below `1` speeds speech up, above `1` slows it down. | No | Omitted; normal duration (`1`). |
+| `timestamps` | `true` requests word timings; supported only with Mist v3. | No | `false` |
+| `customLexicon` | Array of `{ spelling, pronunciation }` entries for Coda; pronunciations use space-separated X-SAMPA strings. | No | Empty array. |
+| `timeout` | Override the overall timeout with positive seconds, or `null` to disable it. | No | Inherits the client timeout. |
 
-Custom deployments use `new Rime({ model: "coda", endpoint: "host:8443" })`.
-Omit the scheme and path. TLS is required; the default port is `443`.
-Model defaults still apply.
+Discover valid values with `await client.voices.list({ language: "en" })` and
+`await client.languages.list()`. Omit the voice language filter to list all voices
+for the selected model. Both calls accept an options object with `timeout` in
+seconds; discovery has an additional ten-second maximum.
 
-### Synthesis options
+### Example: save an IVR greeting
 
-Pass these options to `client.tts.stream(text, { ... })`:
+Save as `tts.mjs`. This writes a complete 16 kHz WAV file, ready for playback or upload.
 
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `voice` | Model's default voice | Voice name from `client.voices.list()` |
-| `language` | `"en"` | Language code |
-| `audioFormat` | `AudioFormat.PCM_24000` | Output profile, imported from `@rimelabs/sdk` |
-| `timeout` | Client setting | Seconds; pass `null` to disable the overall deadline |
+```javascript
+import { writeFile } from "node:fs/promises";
+import { AudioFormat, Rime } from "@rimelabs/sdk";
 
-### Audio formats
+const client = new Rime({ timeout: 60 });
+try {
+  const audio = await client.tts.synthesizeToBuffer(
+    "Thank you for calling. Your appointment is confirmed for tomorrow.",
+    {
+      audioFormat: AudioFormat.WAV,
+      sampleRate: 16000,
+      timeScaleFactor: 0.9,
+    },
+  );
+  await writeFile("greeting.wav", audio);
+  console.log("Saved greeting.wav");
+} finally {
+  await client.close();
+}
+```
 
-Both profiles return raw audio without a file header.
+Run `node tts.mjs`, then open `greeting.wav` in an audio player.
+
+### Audio and stream behavior
+
+All output is mono. PCM is signed 16-bit little-endian audio without a header;
+WAV contains PCM16; MP3 is encoded by the service. PCM/WAV rates are requested
+from the server. MP3 headers determine the actual encoded rate. The fixed
+`PCM_24000` and `MULAW_8000` presets reject conflicting sample rates; mu-law is
+converted locally from 24 kHz PCM. Read `audio.sampleRate` on an `AudioStream`
+for the requested rate.
+
+The buffer helper waits for successful completion and finalizes WAV lengths.
+Its fixed limit is **64 MiB per call**, including headers; exceeding it throws
+`RimeResourceLimitError` without returning partial audio. WAV/MP3 stream chunks
+are fragments of one file. Use the buffer helper when you need a complete WAV.
+
+For incremental text, send fragments as they arrive; the service combines them
+into sentences. Consume streaming audio to the end to confirm success, since an
+error can follow earlier audio. Use `await audio.cancel()` when stopping early
+and `await client.close()` in a `finally` block to release the client. Synthesis
+is not retried automatically, and overall timeouts include pauses by the caller;
+connection and progress limits also apply.
+
+For timestamps, enable `timestamps: true`, consume the audio stream fully, then
+call `await audio.timestamps()`. The result has `status` and `spans` with word
+text and start/end seconds. Nonzero alignment status does not fail the audio.
+The buffer helper returns only bytes, so use an audio stream to access timings.
+Custom lexicons apply to the whole request; the service validates pronunciations
+and model/language support.
+
+## STT
+
+### Transcribe a complete WAV recording
+
+For a complete recording, use the native unary `Transcribe` RPC through the SDK.
+Pass **complete WAV bytes, including the header**, up to **16 MiB (16,777,216
+bytes)**. PCM16 mono 16 kHz WAV is the portable format. The SDK sends the file
+unchanged; it does not decode, resample, or add a header. The service validates
+its encoding and the supplied language and recognition hints.
+
+The result is a `Transcription` containing final text, resolved language, and a
+request ID when available. Silence may return empty text. There are no partial
+updates or automatic retries. TTS client settings do not apply. An optional
+overall timeout includes connection and upload; the SDK also bounds connection
+time and the unary request (120 seconds). Timeout, cancellation, and service
+errors use the existing SDK error categories. A request ID is included when the
+transport has made it available.
+
+```typescript
+import { readFile } from "node:fs/promises";
+import { Rime } from "@rimelabs/sdk";
 
-| `AudioFormat` profile | Encoding | Sample rate | Channels |
-| --- | --- | --- | --- |
-| `PCM_24000` | Signed 16-bit little-endian PCM | 24 kHz | Mono |
-| `MULAW_8000` | G.711 mu-law | 8 kHz | Mono |
+const client = new Rime();
+try {
+  const result = await client.stt.transcribe(await readFile("utterance.wav"), {
+    language: "en",
+    mode: "written",
+    contextTerms: ["Super-G", "USOC"],
+    timeout: 120,
+  });
+  console.log(result.text, result.language, result.requestId);
+} finally {
+  await client.close();
+}
+```
 
-Chunks are `Uint8Array` values with complete sample frames; sizes vary. Inspect the
-read-only `audio.format.encoding`, `audio.format.sampleRate`, and `audio.format.channels`.
+`TranscribeOptions` also accepts an `AbortSignal` as `signal`. Aborting it or
+closing the client cancels pending requests with `RimeCancelledError`.
 
-### Timeouts
+### Stream an utterance
 
-An overall deadline includes pauses between reads. Disabling it leaves internal
-connection and progress limits active. Discovery allows at most 10 seconds;
-a shorter supplied timeout takes precedence. Omit an operation's `timeout` or
-pass `undefined` to inherit the client setting.
+Use `client.stt.stream(audioChunks, options)` to transcribe one utterance.
+The required source is an async iterable of headerless signed PCM16 little-endian
+`Uint8Array` chunks (`Buffer` also works). Ending the source ends the utterance;
+your application decides when to stop.
 
-## Discover voices and languages
+STT uses gRPC over TLS to `stt.api.rime.ai:443`, with the client's API
+key. There is no STT model, endpoint, or protocol selector. TTS client settings,
+including its timeout, do not apply to STT.
 
-List voices and languages inside the quick start's `try` block:
+### Transcription options
 
-```javascript
-const voices = await client.voices.list({ language: "en" });
-const languages = await client.languages.list();
-console.log(voices, languages);
-```
+Pass these fields in the required `TranscriptionOptions` object.
 
-Both return string arrays and accept `timeout`. Omit `language` to disable filtering.
+| Option | Purpose and values | Required | Default |
+| --- | --- | --- | --- |
+| `language` | Spoken BCP-47 language tag, such as `"en"` or `"es"`; passed to the service. | Yes | None; no automatic detection. |
+| `mode` | `"written"` normalizes written text; `"verbatim"` prefers spoken wording. | No | `"written"` |
+| `contextTerms` | Array of recognition hints, such as `["Rime"]`; hints do not force a match. | No | Empty array. |
+| `inputFormat` | Object with `sampleRate` (`8000`, `16000`, `24000`, `48000`), `channels` (`1` or `2`), and `encoding` (only `"pcm_s16le"`). | No | 16 kHz mono PCM16; each field is optional. |
+| `timeout` | Overall timeout in positive seconds, including source/consumer pauses; `null` disables it. | No | No overall timeout; independent of the client timeout. |
+| `signal` | An `AbortSignal`, such as `controller.signal`, to cancel this utterance. | No | No signal. |
 
-## Errors and cancellation
+### Example: transcribe a recording
 
-Report SDK errors and request IDs while closing the client on failure:
+Save a short recording as `utterance.pcm`: **16 kHz, mono, signed PCM16
+little-endian, with no WAV header**. Save this as `stt.mjs`.
 
 ```javascript
-import { writeFile } from "node:fs/promises";
-import { Rime, RimeError } from "@rimelabs/sdk";
+import { createReadStream } from "node:fs";
+import { Rime } from "@rimelabs/sdk";
+
+async function* audioChunks() {
+  yield* createReadStream("utterance.pcm");
+}
 
-let client;
+const client = new Rime();
 try {
-  client = new Rime();
-  await writeFile("speech.pcm", client.tts.stream("Hello. This is Rime."));
-} catch (error) {
-  if (error instanceof RimeError) {
-    console.error(`Speech failed: ${error.message}; requestId=${error.requestId}`);
+  const transcript = client.stt.stream(audioChunks(), {
+    language: "en",
+    timeout: 120,
+  });
+  for await (const update of transcript) {
+    console.log(update.kind, update.text);
   }
-  throw error;
 } finally {
-  await client?.close();
+  await client.close();
 }
 ```
 
-Each SDK error inherits from `RimeError`:
-
-| Error | Meaning |
-| --- | --- |
-| `RimeAuthenticationError` | Missing or rejected credentials |
-| `RimePermissionError` | Access denied |
-| `RimeInputError` | Invalid input or client use |
-| `RimeResourceLimitError` | Service resource limit reached |
-| `RimeUnavailableError` | Service unavailable |
-| `RimeTimeoutError` | Overall or internal deadline reached |
-| `RimeAudioFormatError` | Unsupported or unexpected audio format |
-| `RimeCancelledError` | Operation cancelled |
-| `RimeStreamError` | Other stream or transport failure |
-
-Partial audio can arrive before an error. Output is complete only after successful
-iteration. Synthesis is not retried automatically.
-
-Keep cleanup when stopping early. A `for await` loop exit cancels the stream.
-For manual reads, call `await audio.cancel()` in `finally`. `await client.close()`
-stops all client work. Both calls are safe to repeat; both objects support
-`Symbol.asyncDispose`. Cancellation stops the RPC and limits cleanup time, but
-cannot force your text source to finish an unrelated promise.
-
-## License
-
-The SDK uses the [MIT License](LICENSE). BlingFire retains its
-[upstream license](vendor/LICENSE.blingfire). The package includes its WASM runtime
-and downloads no code or models at runtime. See [vendor provenance](vendor/README.md).
+Run `node stt.mjs`. Each partial update replaces the **complete current
+transcript**; do not append snapshots. A final update confirms successful
+completion and may be empty for silence. Errors do not turn partials into finals.
+
+The SDK converts supported input formats to 16 kHz mono. Stereo must be
+interleaved. WAV headers, MP3, and mu-law input are not accepted. Chunks may split
+sample frames, but an incomplete final frame fails the request. The SDK does not
+provide microphone capture, automatic end-of-speech detection, word timings, or
+diarization. Recognition is not retried automatically.
+
+Use `await transcript.cancel()` or the supplied `AbortSignal` to stop one
+utterance. Closing the client cancels all its operations. Audio sources must
+yield without blocking the event loop. Connection, acceptance, and completion
+limits still apply when the overall timeout is disabled.
+
+## Help and licenses
+
+See the [TTS guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/tts.md),
+[STT guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/stt.md), and
+[Prism guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/realtime.md)
+for more examples. Visit [Rime documentation](https://docs.rime.ai/) for service
+information, or report SDK issues on [GitHub](https://github.com/rimelabs/rime-sdk/issues).
+Include the SDK version and the error's `requestId` when available; omit API keys.
+For Prism, include `session.info.requestId`.
+
+SDK code uses the [MIT license](LICENSE). The Prism protocol module uses
+[Apache 2.0](LICENSE-PRISM); see its [notices](NOTICE-PRISM).
+License texts and notices are included in the distribution.

package/dist/auth.d.ts

@@ -1,10 +1,14 @@
-import { policy } from "./policy.js";
+export interface AuthenticationConfiguration {
+    exchangeUrl: string;
+    audience: string;
+    authTimeout: number;
+}
 export interface Token {
     value: string;
     expiresAt: number;
     audience: string;
 }
-export declare function exchangeKey(key: string, signal: AbortSignal, configuration?: Readonly<typeof policy>): Promise<Token>;
+export declare function exchangeKey(key: string, signal: AbortSignal, configuration: Readonly<AuthenticationConfiguration>): Promise<Token>;
 export declare const authentication: {
     exchangeKey: typeof exchangeKey;
 };
@@ -16,7 +20,9 @@ export declare class Credentials {
     private refreshAt;
     private controller;
     private closed;
-    constructor(key: string, configuration?: Readonly<typeof policy>);
+    constructor(key: string, configuration: Readonly<AuthenticationConfiguration>);
+    authorization(): string;
+    realtimeAuthorization(): string;
     metadata(signal: AbortSignal): Promise<string>;
     themisMetadata(signal: AbortSignal): Promise<string>;
     close(): Promise<void>;

package/dist/auth.js

@@ -1,6 +1,6 @@
-import { policy, abortable } from "./policy.js";
+import { abortable } from "./cancellation.js";
 import { RimeError, RimeAuthenticationError, RimePermissionError, RimeTimeoutError, RimeCancelledError, RimeResourceLimitError, RimeUnavailableError, } from "./errors.js";
-export async function exchangeKey(key, signal, configuration = policy) {
+export async function exchangeKey(key, signal, configuration) {
     try {
         const response = await fetch(configuration.exchangeUrl, {
             method: "POST",
@@ -77,17 +77,25 @@ export class Credentials {
     refreshAt = 0;
     controller = new AbortController();
     closed = false;
-    constructor(key, configuration = policy) {
+    constructor(key, configuration) {
         this.key = key;
         this.configuration = configuration;
     }
+    authorization() {
+        if (this.closed)
+            throw new RimeAuthenticationError("Credentials are closed");
+        return `Bearer ${this.key}`;
+    }
+    realtimeAuthorization() {
+        return this.authorization();
+    }
     async metadata(signal) {
         // TEMPORARY until Themis is ready: replace this body with the call below.
         // return this.themisMetadata(signal);
         if (this.closed)
             throw new RimeAuthenticationError("Credentials are closed");
         signal.throwIfAborted();
-        return `Bearer ${this.key}`;
+        return this.authorization();
     }
     async themisMetadata(signal) {
         if (this.closed)

package/dist/cancellation.d.ts

@@ -0,0 +1,6 @@
+export declare function abortable<T>(promise: PromiseLike<T>, signal: AbortSignal): Promise<T>;
+/** A disposable deadline avoids retaining timers and caller abort listeners. */
+export declare function scope(signals: (AbortSignal | undefined)[], seconds?: number, error?: Error): {
+    signal: AbortSignal;
+    dispose(): void;
+};

package/dist/cancellation.js

@@ -0,0 +1,54 @@
+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);
+        });
+    });
+}
+/** A disposable deadline avoids retaining timers and caller abort listeners. */
+export function scope(signals, seconds, error) {
+    const controller = new AbortController();
+    const handlers = new Map();
+    for (const signal of new Set(signals)) {
+        if (!signal)
+            continue;
+        const abort = () => controller.abort(signal.reason);
+        if (signal.aborted)
+            abort();
+        else {
+            signal.addEventListener("abort", abort, { once: true });
+            handlers.set(signal, abort);
+        }
+    }
+    let timer;
+    if (seconds !== undefined) {
+        const end = performance.now() + seconds * 1000;
+        const expire = () => {
+            const remaining = end - performance.now();
+            if (remaining <= 0)
+                controller.abort(error);
+            else
+                timer = setTimeout(expire, Math.min(remaining, 2147483647));
+        };
+        expire();
+    }
+    return {
+        signal: controller.signal,
+        dispose() {
+            clearTimeout(timer);
+            for (const [signal, handler] of handlers)
+                signal.removeEventListener("abort", handler);
+        },
+    };
+}

package/dist/client.d.ts

@@ -1,5 +1,10 @@
-import { AudioFormat } from "./audio.js";
-import { AudioStream, type TextSource } from "./stream.js";
+import type { AudioSource, TranscriptionOptions, TranscribeOptions, Transcription } from "./stt/types.js";
+import type { TranscriptStream } from "./stt/stream.js";
+import { type SynthesisOptions, type DiscoveryOptions, type VoiceListOptions } from "./tts/client.js";
+import { type AudioStream, type TextSource } from "./tts/stream.js";
+import type { RealtimeConnectOptions } from "./realtime/types.js";
+import type { RealtimeSession } from "./realtime/session.js";
+export type { SynthesisOptions, DiscoveryOptions, VoiceListOptions, } from "./tts/client.js";
 export interface RimeOptions {
     apiKey?: string | null;
     /** Select "coda" (default) or "mistv3" for speech and discovery. */
@@ -7,28 +12,27 @@ export interface RimeOptions {
     endpoint?: string | null;
     timeout?: number | null;
 }
-export interface SynthesisOptions {
-    voice?: string | null;
-    language?: string;
-    audioFormat?: AudioFormat | null;
-    timeout?: number | null;
-}
-export interface DiscoveryOptions {
-    timeout?: number | null;
-}
-export interface VoiceListOptions extends DiscoveryOptions {
-    language?: string | null;
-}
 export declare class Rime {
-    private readonly deployment;
-    private credentials;
-    private client;
+    private readonly credentials;
+    private readonly ttsClient;
+    private readonly sttClient;
+    readonly stt: {
+        /** Transcribe complete WAV bytes. PCM16 mono 16 kHz is the portable format; maximum 16 MiB. */
+        transcribe: (audio: Uint8Array, options: TranscribeOptions) => Promise<Transcription>;
+        stream: (audio: AudioSource, options: TranscriptionOptions) => TranscriptStream;
+    };
+    private readonly realtimeClient;
+    readonly realtime: {
+        connect: (options?: RealtimeConnectOptions) => Promise<RealtimeSession>;
+    };
     private closed;
-    private streams;
-    private discoveryControllers;
     private closing;
-    private defaultTimeout;
     readonly tts: {
+        /** Synthesize complete text and return streaming audio. Do not await this call. */
+        synthesize: (text: string, options?: SynthesisOptions) => AudioStream;
+        /** Await complete audio bytes, finalizing WAV lengths. Fixed output limit: 64 MiB. */
+        synthesizeToBuffer: (text: string, options?: SynthesisOptions) => Promise<Buffer>;
+        /** Supply incremental text and return streaming audio. Do not await this call. */
         stream: (text: TextSource, options?: SynthesisOptions) => AudioStream;
     };
     readonly voices: {
@@ -39,9 +43,6 @@ export declare class Rime {
     };
     constructor(options?: RimeOptions);
     private checkOpen;
-    private prepare;
-    private stream;
-    private discover;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }