@rimelabs/sdk 0.1.0-alpha.13 → 0.1.0-alpha.15

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.0-alpha.15](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.14...typescript-v0.1.0-alpha.15) (2026-10-13)
+
+
+### Bug Fixes
+
+* **realtime:** align Prism protocol names and contract fixtures ([#68](https://github.com/rimelabs/rime-sdk/issues/68)) ([806d8a4](https://github.com/rimelabs/rime-sdk/commit/806d8a4811f0baf6b220487dfc6ccd21cfe8ea18))
+
+## [0.1.0-alpha.14](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.13...typescript-v0.1.0-alpha.14) (2026-10-12)
+
+
+### Features
+
+* **tts:** add sample rates, time-scale control, and buffered audio output ([1856d0d](https://github.com/rimelabs/rime-sdk/commit/1856d0d6c00a46d7917b61d73bc7f2a8526c8bb0))
+
 ## [0.1.0-alpha.13](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.12...typescript-v0.1.0-alpha.13) (2026-10-11)
 
 

package/README.md

@@ -1,13 +1,13 @@
-# Rime SDK for Node.js
+# Rime SDK for TypeScript and Node.js
 
-Generate speech with TTS, transcribe audio with STT, or send speech to Prism
-and receive a spoken reply. All use the `Rime` client. Your application handles
+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.
-Run it on a server. 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
 mkdir rime-quickstart
@@ -17,83 +17,14 @@ npm install @rimelabs/sdk wavefile
 export RIME_API_KEY="your-api-key"
 ```
 
-Get a TTS API key from the [Rime dashboard](https://app.rime.ai/).
-An explicit `new Rime({ apiKey: "..." })` overrides `RIME_API_KEY`. The SDK does not load `.env` files.
-The commands below use a macOS or Linux shell.
+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.
 
-These examples use JavaScript `.mjs` files so you can run them without a TypeScript build.
-The additional [wavefile package](https://github.com/rochars/wavefile) reads and writes WAV files
-for the examples. It is not required by the SDK.
-
-## TTS: save speech
-
-Save this as `tts.mjs`. It writes a playable `speech.wav` file with no audio-device dependencies.
-
-```javascript
-import { writeFileSync } from "node:fs";
-import wavefile from "wavefile";
-import { Rime } from "@rimelabs/sdk";
-
-const client = new Rime({ timeout: 60 });
-try {
-  const chunks = [];
-  for await (const chunk of client.tts.synthesize(
-    "Your appointment is confirmed for tomorrow.",
-  )) {
-    chunks.push(Buffer.from(chunk));
-  }
-  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("speech.wav", wav.toBuffer());
-  console.log("Saved speech.wav");
-} finally {
-  await client.close();
-}
-```
-
-Run `node tts.mjs`, then open `speech.wav` in your audio player.
-This short example collects the audio in memory before writing the file.
-For long responses, write audio chunks as they arrive.
-
-Coda is the default model. Use `new Rime({ model: "mistv3" })` for Mist v3, or pass
-`{ voice: "your-voice" }` as the second argument to `client.tts.synthesize(...)` to select a voice.
-The default output is mono 24 kHz PCM16. The example adds its WAV header.
-Use `client.tts.synthesize(text)` for a complete string. To supply text from an LLM,
-pass an async iterable of strings to `client.tts.stream(chunks)`. Both methods
-return streaming audio. Rime automatically combines text fragments into
-sentences for speech.
-
-## STT quick start
-
-Stream one utterance of headerless signed PCM16 little-endian audio. Specify the
-spoken language; exhaust the audio source when the utterance ends. Each update
-replaces the complete current transcript.
-
-```javascript
-import { createReadStream } from "node:fs";
-import { Rime } from "@rimelabs/sdk";
-
-async function* audioChunks() {
-  yield* createReadStream("utterance.pcm");
-}
-
-const client = new Rime();
-try {
-  const transcript = client.stt.stream(audioChunks(), {
-    language: "en",
-  });
-  for await (const update of transcript) console.log(update.kind, update.text);
-} finally {
-  await client.close();
-}
-```
-
-Input defaults to 16 kHz mono. The [STT guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/stt.md)
-covers other PCM formats, written/verbatim output, recognition hints and cancellation.
+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
 
@@ -196,10 +127,176 @@ 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.
 
+## TTS
+
+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.
+
+### Client options
+
+These optional `new Rime({...})` fields configure TTS. They do not configure STT or Prism.
+
+| 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. |
+
+### Synthesis options
+
+All three TTS methods accept the same `SynthesisOptions` fields. Import
+`AudioFormat` from `@rimelabs/sdk` when selecting an encoding.
+
+| 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. |
+
+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.
+
+### Example: save an IVR greeting
+
+Save as `tts.mjs`. This writes a complete 16 kHz WAV file, ready for playback or upload.
+
+```javascript
+import { writeFile } from "node:fs/promises";
+import { AudioFormat, Rime } from "@rimelabs/sdk";
+
+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();
+}
+```
+
+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
+
+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.
+
+STT uses streaming 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.
+
+### Transcription options
+
+Pass these fields in the required `TranscriptionOptions` object.
+
+| 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. |
+
+### Example: transcribe a recording
+
+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 { createReadStream } from "node:fs";
+import { Rime } from "@rimelabs/sdk";
+
+async function* audioChunks() {
+  yield* createReadStream("utterance.pcm");
+}
+
+const client = new Rime();
+try {
+  const transcript = client.stt.stream(audioChunks(), {
+    language: "en",
+    timeout: 120,
+  });
+  for await (const update of transcript) {
+    console.log(update.kind, update.text);
+  }
+} finally {
+  await client.close();
+}
+```
+
+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 [Rime documentation](https://docs.rime.ai/) for API keys, TTS models, and deployment information.
-The examples above run with the installed package. No source checkout is required.
+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.
 
-SDK code uses the MIT license. The Prism protocol module uses Apache 2.0.
-The SDK downloads no code or models at runtime.
+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/client.d.ts

@@ -11,8 +11,6 @@ export interface RimeOptions {
     model?: string;
     endpoint?: string | null;
     timeout?: number | null;
-    /** Recognition hostname and optional port; defaults to stt.api.rime.ai:443. */
-    sttEndpoint?: string | null;
 }
 export declare class Rime {
     private readonly credentials;
@@ -30,6 +28,8 @@ export declare class Rime {
     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;
     };

package/dist/client.js

@@ -25,7 +25,7 @@ export class Rime {
         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, options.sttEndpoint, () => this.checkOpen());
+        this.sttClient = new STT(this.credentials, () => this.checkOpen());
         this.stt = {
             stream: (audio, options) => this.sttClient.stream(audio, options),
         };
@@ -36,6 +36,7 @@ export class Rime {
         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;

package/dist/realtime/protocol.js

@@ -66,15 +66,15 @@ function duration(value, field) {
 }
 function session(value) {
     const view = object(value, "session");
-    const waits = view.prsm_tool_waits === undefined
+    const waits = view.prism_tool_waits === undefined
         ? {}
-        : object(view.prsm_tool_waits, "session.prsm_tool_waits");
-    if (view.prsm_tool_waits !== undefined &&
+        : object(view.prism_tool_waits, "session.prism_tool_waits");
+    if (view.prism_tool_waits !== undefined &&
         (!("result_timeout_s" in waits) || !("continuation_timeout_s" in waits)))
-        invalid("session.prsm_tool_waits");
-    const interrupt = view.prsm_effective_interrupt_response;
+        invalid("session.prism_tool_waits");
+    const interrupt = view.prism_effective_interrupt_response;
     if (interrupt !== undefined && typeof interrupt !== "boolean")
-        invalid("session.prsm_effective_interrupt_response");
+        invalid("session.prism_effective_interrupt_response");
     return {
         id: id(view.id, "session.id"),
         voice: view.voice === undefined ? "" : string(view.voice, "session.voice"),
@@ -189,7 +189,7 @@ function decodeValue(value, sessionId) {
                 contentIndex: integer(event.content_index, "content_index"),
             };
             break;
-        case "prsm.typed_input.ready":
+        case "prism.typed_input.ready":
             payload = { kind: "input.ready" };
             break;
         case "input_audio_buffer.speech_started":
@@ -244,10 +244,10 @@ function decodeValue(value, sessionId) {
             const response = object(event.response, "response"), metadata = response.metadata == null
                 ? {}
                 : object(response.metadata, "metadata");
-            const cause = metadata.prsm_cause === undefined
+            const cause = metadata.prism_cause === undefined
                 ? undefined
-                : string(metadata.prsm_cause, "prsm_cause");
-            const parent = optionalString(metadata.prsm_parent_response_id, "prsm_parent_response_id");
+                : string(metadata.prism_cause, "prism_cause");
+            const parent = optionalString(metadata.prism_parent_response_id, "prism_parent_response_id");
             payload = {
                 kind: "response.started",
                 response: ref(response.id),
@@ -261,7 +261,7 @@ function decodeValue(value, sessionId) {
                                 ? "proactive"
                                 : "unknown",
                 parent: parent === null ? null : ref(parent),
-                inputItemId: optionalString(metadata.prsm_input_item_id, "prsm_input_item_id"),
+                inputItemId: optionalString(metadata.prism_input_item_id, "prism_input_item_id"),
             };
             break;
         }
@@ -282,7 +282,7 @@ function decodeValue(value, sessionId) {
                     ? status
                     : "unknown",
                 reason: optionalString(details.reason, "reason"),
-                drainToken: optionalString(metadata.prsm_drain_token, "prsm_drain_token"),
+                drainToken: optionalString(metadata.prism_drain_token, "prism_drain_token"),
             };
             break;
         }
@@ -348,7 +348,7 @@ function decodeValue(value, sessionId) {
     }
     return {
         eventId: event.event_id === undefined ? "" : string(event.event_id, "event_id"),
-        requestId: optionalString(event.prsm_request_event_id, "prsm_request_event_id"),
+        requestId: optionalString(event.prism_request_event_id, "prism_request_event_id"),
         payload,
     };
 }

package/dist/realtime/session.js

@@ -348,21 +348,21 @@ export class RealtimeSession {
     }
     async sendText(value, options = {}) {
         text(value);
-        return this.operation(options, (signal) => this.create({ prsm_input_text: value, metadata: { prsm_cause: "user_text" } }, signal, p.requests.text));
+        return this.operation(options, (signal) => this.create({ prism_input_text: value, metadata: { prism_cause: "user_text" } }, signal, p.requests.text));
     }
     async requestReply(options = {}) {
         const body = {
-            metadata: { prsm_cause: "proactive" },
+            metadata: { prism_cause: "proactive" },
         };
         if (options.instruction != null) {
             text(options.instruction);
-            body.prsm_instruction = options.instruction;
+            body.prism_instruction = options.instruction;
         }
         if (options.toolCall != null) {
             const state = this.response(options.toolCall);
             if (state.calls.get(options.toolCall.callId) === null)
                 throw new RimeInputError("Record the tool result before requesting its report");
-            body.prsm_call_id = options.toolCall.callId;
+            body.prism_call_id = options.toolCall.callId;
         }
         return this.operation(options, (signal) => this.create(body, signal));
     }
@@ -434,8 +434,8 @@ export class RealtimeSession {
             return (await this.request(p.requests.create, {
                 response: {
                     metadata: {
-                        prsm_cause: "tool_continuation",
-                        prsm_parent_response_id: ref.responseId,
+                        prism_cause: "tool_continuation",
+                        prism_parent_response_id: ref.responseId,
                     },
                 },
             }, signal, undefined, state)).response;
@@ -524,7 +524,7 @@ export class RealtimeSession {
             this.check();
             if (state.token)
                 await this.send({
-                    type: "prsm.playback.drained",
+                    type: "prism.playback.drained",
                     response_id: state.ref.responseId,
                     drain_token: state.token,
                     played_ms: played,

package/dist/stt/client.d.ts

@@ -3,11 +3,10 @@ import { TranscriptStream } from "./stream.js";
 import type { AudioSource, TranscriptionOptions } from "./types.js";
 export declare class STT {
     private readonly credentials;
-    private readonly endpoint;
     private readonly checkOpen;
     private connection;
     private streams;
-    constructor(credentials: Credentials, endpoint: string | null | undefined, checkOpen: () => void);
+    constructor(credentials: Credentials, checkOpen: () => void);
     stream(source: AudioSource, options: TranscriptionOptions): TranscriptStream;
     close(): Promise<void>;
 }

package/dist/stt/client.js

@@ -1,5 +1,5 @@
 import { connect, metadata } from "../grpc.js";
-import { endpointAddress, timeout } from "../validation.js";
+import { timeout } from "../validation.js";
 import { RimeInputError } from "../errors.js";
 import { resolvePCMFormat } from "../pcm.js";
 import { transport, requireSchema } from "./transport.js";
@@ -7,13 +7,11 @@ import { TranscriptStream } from "./stream.js";
 import { policy } from "./policy.js";
 export class STT {
     credentials;
-    endpoint;
     checkOpen;
     connection = null;
     streams = new Set();
-    constructor(credentials, endpoint, checkOpen) {
+    constructor(credentials, checkOpen) {
         this.credentials = credentials;
-        this.endpoint = endpoint;
         this.checkOpen = checkOpen;
     }
     stream(source, options) {
@@ -29,9 +27,7 @@ export class STT {
         if (!Array.isArray(terms) || terms.some((term) => typeof term !== "string"))
             throw new RimeInputError("contextTerms must be an array of strings");
         const format = resolvePCMFormat(options.inputFormat);
-        const target = this.endpoint == null
-            ? policy.target
-            : endpointAddress(this.endpoint).target;
+        const target = policy.target;
         const stream = new TranscriptStream({
             checkOpen: this.checkOpen,
             forget: (stream) => this.streams.delete(stream),

package/dist/tts/audio.d.ts

@@ -1,11 +1,20 @@
 export declare class AudioFormat {
     readonly encoding: string;
+    /** Fixed preset rate, or zero when selected per request. See AudioStream.sampleRate. */
     readonly sampleRate: number;
     readonly channels: number;
+    static readonly PCM: Readonly<AudioFormat>;
+    static readonly WAV: Readonly<AudioFormat>;
+    static readonly MP3: Readonly<AudioFormat>;
     static readonly PCM_24000: Readonly<AudioFormat>;
     static readonly MULAW_8000: Readonly<AudioFormat>;
     private constructor();
 }
+export declare function wireFormat(format: AudioFormat): string;
+export declare function resolveAudio(format: AudioFormat | null | undefined, sampleRate: number | null | undefined, timeScaleFactor: number | null | undefined): {
+    format: AudioFormat;
+    sampleRate: number;
+};
 export declare class Converter {
     private profile;
     private tail;

package/dist/tts/audio.js

@@ -1,16 +1,52 @@
-import { RimeAudioFormatError } from "../errors.js";
+import { RimeAudioFormatError, RimeInputError } from "../errors.js";
 export class AudioFormat {
     encoding;
     sampleRate;
     channels;
+    static PCM = Object.freeze(new AudioFormat("pcm_s16le", 0, 1));
+    static WAV = Object.freeze(new AudioFormat("wav", 0, 1));
+    static MP3 = Object.freeze(new AudioFormat("mp3", 0, 1));
     static PCM_24000 = Object.freeze(new AudioFormat("pcm_s16le", 24000, 1));
     static MULAW_8000 = Object.freeze(new AudioFormat("mulaw", 8000, 1));
-    constructor(encoding, sampleRate, channels) {
+    constructor(encoding, 
+    /** Fixed preset rate, or zero when selected per request. See AudioStream.sampleRate. */
+    sampleRate, channels) {
         this.encoding = encoding;
         this.sampleRate = sampleRate;
         this.channels = channels;
     }
 }
+export function wireFormat(format) {
+    if (format === AudioFormat.WAV)
+        return "audio/wav";
+    if (format === AudioFormat.MP3)
+        return "audio/mpeg";
+    return "audio/pcm";
+}
+export function resolveAudio(format, sampleRate, timeScaleFactor) {
+    format ??= AudioFormat.PCM;
+    if (![
+        AudioFormat.PCM,
+        AudioFormat.PCM_24000,
+        AudioFormat.MULAW_8000,
+        AudioFormat.WAV,
+        AudioFormat.MP3,
+    ].includes(format))
+        throw new RimeAudioFormatError("Select a named AudioFormat");
+    sampleRate ??= format.sampleRate || 24000;
+    if (![8000, 16000, 24000].includes(sampleRate))
+        throw new RimeAudioFormatError("sampleRate must be 8000, 16000, or 24000");
+    if (format.sampleRate && sampleRate !== format.sampleRate)
+        throw new RimeAudioFormatError("sampleRate conflicts with the fixed AudioFormat preset");
+    if (timeScaleFactor != null &&
+        (!Number.isFinite(timeScaleFactor) ||
+            timeScaleFactor < 0.4 ||
+            timeScaleFactor > 2.5))
+        throw new RimeInputError("timeScaleFactor must be a finite number from 0.4 to 2.5");
+    if (format === AudioFormat.PCM && sampleRate === 24000)
+        format = AudioFormat.PCM_24000;
+    return { format, sampleRate };
+}
 const raw = Array.from({ length: 63 }, (_, i) => (i === 31
     ? (2 * 3400) / 24000
     : Math.sin(((2 * Math.PI * 3400) / 24000) * (i - 31)) /
@@ -47,12 +83,15 @@ export class Converter {
         return null;
     }
     process(input, final = false) {
+        if (this.profile === AudioFormat.WAV || this.profile === AudioFormat.MP3)
+            return Buffer.from(input);
         const data = Buffer.concat([this.tail, input]);
         const size = Math.floor(data.length / 2) * 2;
         this.tail = Buffer.from(data.subarray(size));
         if (final && this.tail.length)
             throw new RimeAudioFormatError("Incomplete final PCM sample frame");
-        if (this.profile === AudioFormat.PCM_24000)
+        if (this.profile === AudioFormat.PCM ||
+            this.profile === AudioFormat.PCM_24000)
             return data.subarray(0, size);
         const result = [];
         for (let i = 0; i < size; i += 2) {

package/dist/tts/buffer.d.ts

@@ -0,0 +1,3 @@
+export declare const maxBufferBytes: number;
+/** Validate mono PCM16 WAV and replace unknown streaming chunk lengths. */
+export declare function finalizeWav(data: Buffer, sampleRate: number, requestId: string | null): void;

package/dist/tts/buffer.js

@@ -0,0 +1,53 @@
+import { RimeAudioFormatError } from "../errors.js";
+export const maxBufferBytes = 64 * 1024 * 1024;
+/** Validate mono PCM16 WAV and replace unknown streaming chunk lengths. */
+export function finalizeWav(data, sampleRate, requestId) {
+    const invalid = () => new RimeAudioFormatError("Expected a complete mono PCM16 WAV at the requested sample rate", requestId);
+    if (data.length < 12 ||
+        data.toString("latin1", 0, 4) !== "RIFF" ||
+        data.toString("latin1", 8, 12) !== "WAVE")
+        throw invalid();
+    if (data.length - 8 > 0xffffffff)
+        throw new RimeAudioFormatError("Audio exceeds the WAV size limit", requestId);
+    if (![0xffffffff, data.length - 8].includes(data.readUInt32LE(4)))
+        throw invalid();
+    let offset = 12;
+    let foundFormat = false;
+    let dataSizeOffset;
+    let dataSize = 0;
+    while (offset < data.length) {
+        if (data.length - offset < 8)
+            throw invalid();
+        const name = data.toString("latin1", offset, offset + 4);
+        let size = data.readUInt32LE(offset + 4);
+        const start = offset + 8;
+        if (name === "data" && size === 0xffffffff)
+            size = data.length - start;
+        const end = start + size;
+        if (end > data.length)
+            throw invalid();
+        if (name === "fmt ") {
+            if (foundFormat ||
+                size < 16 ||
+                data.readUInt16LE(start) !== 1 ||
+                data.readUInt16LE(start + 2) !== 1 ||
+                data.readUInt32LE(start + 4) !== sampleRate ||
+                data.readUInt32LE(start + 8) !== sampleRate * 2 ||
+                data.readUInt16LE(start + 12) !== 2 ||
+                data.readUInt16LE(start + 14) !== 16)
+                throw invalid();
+            foundFormat = true;
+        }
+        else if (name === "data") {
+            if (!foundFormat || dataSizeOffset !== undefined || size % 2)
+                throw invalid();
+            dataSizeOffset = offset + 4;
+            dataSize = size;
+        }
+        offset = end + (size % 2);
+    }
+    if (offset !== data.length || dataSizeOffset === undefined)
+        throw invalid();
+    data.writeUInt32LE(data.length - 8, 4);
+    data.writeUInt32LE(dataSize, dataSizeOffset);
+}

package/dist/tts/client.d.ts

@@ -7,6 +7,10 @@ export interface SynthesisOptions {
     voice?: string | null;
     language?: string;
     audioFormat?: AudioFormat | null;
+    /** Requested output rate: 8000, 16000, or 24000 Hz. Defaults to 24000 for PCM/WAV/MP3. */
+    sampleRate?: number | null;
+    /** Duration multiplier from 0.4 to 2.5. Below 1 speeds speech up; above 1 slows it down. */
+    timeScaleFactor?: number | null;
     /** Request final word timestamps. Supported only with model="mistv3". */
     timestamps?: boolean;
     /** Request-wide pronunciation overrides; requires a phoneme-capable Coda deployment. */
@@ -37,6 +41,11 @@ export declare class TTS {
     private prepare;
     /** Synthesize complete text and return an audio stream. Do not await this call. */
     synthesize(text: string, options?: SynthesisOptions): AudioStream;
+    /** Await complete audio in memory, finalizing WAV lengths. Never returns partial audio.
+     * The fixed output limit is 64 MiB (67,108,864 bytes); exceeding it raises
+     * RimeResourceLimitError. Use streaming synthesis for larger outputs or timestamps.
+     */
+    synthesizeToBuffer(text: string, options?: SynthesisOptions): Promise<Buffer>;
     /** Stream text chunks into synthesis and return an audio stream. Do not await this call. */
     stream(text: TextSource, options?: SynthesisOptions): AudioStream;
     private discover;

package/dist/tts/client.js

@@ -1,10 +1,11 @@
-import { AudioFormat } from "./audio.js";
+import { AudioFormat, resolveAudio } from "./audio.js";
+import { maxBufferBytes, finalizeWav } from "./buffer.js";
 import { snapshot } from "./lexicon.js";
 import { AudioStream, constructionKey } from "./stream.js";
 import { policy, timeout, nonempty } from "./policy.js";
 import { abortable } from "../cancellation.js";
 import { transport, connect, metadata, discover, } from "./transport.js";
-import { RimeInputError, RimeAudioFormatError, RimeCancelledError, RimeTimeoutError, RimeUnavailableError, } from "../errors.js";
+import { RimeInputError, RimeResourceLimitError, RimeCancelledError, RimeTimeoutError, RimeUnavailableError, } from "../errors.js";
 export class TTS {
     credentials;
     deployment;
@@ -50,6 +51,30 @@ export class TTS {
             yield text;
         })(), options);
     }
+    /** Await complete audio in memory, finalizing WAV lengths. Never returns partial audio.
+     * The fixed output limit is 64 MiB (67,108,864 bytes); exceeding it raises
+     * RimeResourceLimitError. Use streaming synthesis for larger outputs or timestamps.
+     */
+    async synthesizeToBuffer(text, options = {}) {
+        const audio = this.synthesize(text, options);
+        const chunks = [];
+        let size = 0;
+        try {
+            for await (const chunk of audio) {
+                if (chunk.byteLength > maxBufferBytes - size)
+                    throw new RimeResourceLimitError("Audio exceeds the 64 MiB buffer limit", audio.requestId);
+                chunks.push(chunk);
+                size += chunk.byteLength;
+            }
+            const data = Buffer.concat(chunks, size);
+            if (audio.format === AudioFormat.WAV)
+                finalizeWav(data, audio.sampleRate, audio.requestId);
+            return data;
+        }
+        finally {
+            await audio.cancel();
+        }
+    }
     /** Stream text chunks into synthesis and return an audio stream. Do not await this call. */
     stream(text, options = {}) {
         this.checkOpen();
@@ -67,14 +92,12 @@ export class TTS {
             ? 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 { format, sampleRate } = resolveAudio(options.audioFormat, options.sampleRate, options.timeScaleFactor);
         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), timestamps, lexicon);
+        }, text, voice, language, format, timeout(options.timeout, this.defaultTimeout), timestamps, lexicon, sampleRate, options.timeScaleFactor ?? undefined);
         this.streams.add(audio);
         return audio;
     }

package/dist/tts/stream.d.ts

@@ -18,6 +18,8 @@ export declare class AudioStream implements AsyncIterableIterator<Uint8Array> {
     private timeout;
     private timestampsRequested;
     private customLexicon;
+    private sampleRateValue;
+    private timeScaleFactor?;
     private readonly controller;
     private readonly queue;
     private worker;
@@ -35,8 +37,10 @@ export declare class AudioStream implements AsyncIterableIterator<Uint8Array> {
     private readonly operationId;
     private bytesReceived;
     private bytesDelivered;
-    constructor(key: symbol, owner: StreamOwner, source: TextSource | null, voice: string, language: string, formatValue: AudioFormat, timeout: number | null, timestampsRequested?: boolean, customLexicon?: readonly PronunciationEntry[]);
+    constructor(key: symbol, owner: StreamOwner, source: TextSource | null, voice: string, language: string, formatValue: AudioFormat, timeout: number | null, timestampsRequested?: boolean, customLexicon?: readonly PronunciationEntry[], sampleRateValue?: number, timeScaleFactor?: number | undefined);
     get format(): AudioFormat;
+    /** Requested output rate. MP3 headers describe the encoded rate. */
+    get sampleRate(): number;
     get requestId(): string | null;
     /** Read requested timestamps after consuming all audio; never drains audio.
      * Calling before iteration completes rejects with RimeInputError. Synthesis

package/dist/tts/stream.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { debuglog } from "node:util";
 const log = debuglog("rime-sdk");
-import { Converter } from "./audio.js";
+import { AudioFormat, Converter, wireFormat } from "./audio.js";
 import { policy } from "./policy.js";
 import { abortable } from "../cancellation.js";
 import { ByteQueue } from "./queue.js";
@@ -17,6 +17,8 @@ export class AudioStream {
     timeout;
     timestampsRequested;
     customLexicon;
+    sampleRateValue;
+    timeScaleFactor;
     controller = new AbortController();
     queue = new ByteQueue(policy.outputBytes, policy.outputChunkBytes);
     worker = null;
@@ -34,7 +36,7 @@ export class AudioStream {
     operationId = randomUUID();
     bytesReceived = 0;
     bytesDelivered = 0;
-    constructor(key, owner, source, voice, language, formatValue, timeout, timestampsRequested = false, customLexicon = []) {
+    constructor(key, owner, source, voice, language, formatValue, timeout, timestampsRequested = false, customLexicon = [], sampleRateValue = 24000, timeScaleFactor) {
         this.owner = owner;
         this.source = source;
         this.voice = voice;
@@ -43,12 +45,18 @@ export class AudioStream {
         this.timeout = timeout;
         this.timestampsRequested = timestampsRequested;
         this.customLexicon = customLexicon;
+        this.sampleRateValue = sampleRateValue;
+        this.timeScaleFactor = timeScaleFactor;
         if (key !== constructionKey)
             throw new TypeError("AudioStream is returned by client.tts.synthesize() or client.tts.stream()");
     }
     get format() {
         return this.formatValue;
     }
+    /** Requested output rate. MP3 headers describe the encoded rate. */
+    get sampleRate() {
+        return this.sampleRateValue;
+    }
     get requestId() {
         return this.call?.requestId ?? null;
     }
@@ -218,7 +226,7 @@ export class AudioStream {
         try {
             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, this.timestampsRequested, this.customLexicon);
+            await this.call.start(this.voice, this.language, this.timestampsRequested, this.customLexicon, wireFormat(this.format), this.format === AudioFormat.MULAW_8000 ? 24000 : this.sampleRate, this.timeScaleFactor);
             tasks = [this.produce(), this.read()];
             await Promise.all(tasks);
             this.queue.finish();

package/dist/tts/transport.d.ts

@@ -14,6 +14,7 @@ export declare const transport: {
 export declare function connect(client: grpc.Client, signal: AbortSignal): Promise<void>;
 export declare function discover(prepared: PreparedConnection, kind: DiscoveryKind, language: string | null | undefined, signal: AbortSignal): Promise<string[]>;
 export declare class SynthesisCall {
+    private audioFormat;
     private timestampsRequested;
     private readonly timestampTrailer;
     private readonly rpc;
@@ -21,7 +22,7 @@ export declare class SynthesisCall {
     get requestId(): string | null;
     get done(): boolean;
     cancel(): void;
-    start(voice: string, language: string, timestamps?: boolean, customLexicon?: readonly PronunciationEntry[]): Promise<void>;
+    start(voice: string, language: string, timestamps?: boolean, customLexicon?: readonly PronunciationEntry[], audioFormat?: string, sampleRate?: number, timeScaleFactor?: number): Promise<void>;
     timestampResult(): import("./timestamps.js").TimestampResult;
     write(text: string): Promise<void>;
     finishInput(): void;

package/dist/tts/transport.js

@@ -22,7 +22,7 @@ export function connect(client, signal) {
 function openStream(client, auth) {
     return client.makeBidiStreamRequest("/rime.TextToSpeech/SynthesizeStreaming", serializer(schema.StreamingSynthesisRequestSchema), deserializer(schema.SynthesisResponseStreamSchema), auth);
 }
-function header(voice, language, timestamps, customLexicon) {
+function header(voice, language, timestamps, customLexicon, audioFormat, samplingRate, timeScaleFactor) {
     return create(schema.StreamingSynthesisRequestSchema, {
         payload: {
             case: "header",
@@ -30,7 +30,7 @@ function header(voice, language, timestamps, customLexicon) {
                 speaker: voice,
                 language,
                 splitStrategy: schema.SplitStrategy.ACCUMULATE_SENTENCE,
-                audioParameters: { audioFormat: "audio/pcm", samplingRate: 24000 },
+                audioParameters: { audioFormat, samplingRate, timeScaleFactor },
                 timestamps: timestamps ? { enable: true } : undefined,
                 customLexicon: [...customLexicon],
             }),
@@ -79,6 +79,7 @@ export async function discover(prepared, kind, language, signal) {
     return response.languages;
 }
 export class SynthesisCall {
+    audioFormat = "audio/pcm";
     timestampsRequested = false;
     timestampTrailer = new TimestampTrailer();
     rpc;
@@ -94,9 +95,10 @@ export class SynthesisCall {
     cancel() {
         this.rpc.cancel();
     }
-    start(voice, language, timestamps = false, customLexicon = []) {
+    start(voice, language, timestamps = false, customLexicon = [], audioFormat = "audio/pcm", sampleRate = 24000, timeScaleFactor) {
         this.timestampsRequested = timestamps;
-        const message = header(voice, language, timestamps, customLexicon);
+        this.audioFormat = audioFormat;
+        const message = header(voice, language, timestamps, customLexicon, audioFormat, sampleRate, timeScaleFactor);
         return this.rpc.write(message);
     }
     timestampResult() {
@@ -109,8 +111,8 @@ export class SynthesisCall {
         this.rpc.finishInput();
     }
     checkFormat(contentType) {
-        if (contentType !== "audio/pcm")
-            throw new errors.RimeAudioFormatError("Expected raw audio/pcm from the service", this.requestId);
+        if (contentType !== this.audioFormat)
+            throw new errors.RimeAudioFormatError(`Expected ${this.audioFormat} from the service`, this.requestId);
     }
     async *audio() {
         const headers = await this.rpc.headers();

package/docs/realtime.md

@@ -1,5 +1,8 @@
 # Realtime / Prism for Node.js
 
+The endpoint must use Rime's `prism.` events and `prism_` fields. Endpoints
+that use the former `prsm` names are not supported.
+
 Keep one event consumer running while your application sends input, runs tools,
 and plays audio. The SDK manages the protocol state. Your application owns
 microphone capture, tool execution, and playback.

package/docs/stt.md

@@ -52,8 +52,8 @@ split sample frames; the SDK carries incomplete bytes into the next chunk. A
 truncated final frame raises `RimeAudioFormatError`, without committing the
 utterance. Each gRPC audio payload is at most 64 KiB of 16 kHz mono PCM16.
 
-The default recognition endpoint is `stt.api.rime.ai:443`, using TLS and the same
-API key as the other features. `new Rime({ sttEndpoint: "host:443" })` overrides only STT.
+Recognition connects to `stt.api.rime.ai:443` using TLS and the same API key as
+the other features. No endpoint configuration is needed.
 The existing `model`, `endpoint` and client `timeout` settings remain TTS settings.
 There is no STT voice/model selector; the service selects its recognizer.
 

package/docs/tts.md

@@ -60,29 +60,68 @@ Model defaults still apply.
 
 ### Synthesis options
 
-Both methods require text input: a nonblank string for `synthesize`, or an
-async iterable of strings for `stream`. Both accept the following optional settings:
+`synthesize` and `synthesizeToBuffer` require a nonblank string; `stream` requires
+an async iterable of strings. All three accept the following settings:
 
 | 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` |
+| `audioFormat` | `AudioFormat.PCM` (24 kHz) | Output encoding, imported from `@rimelabs/sdk` |
+| `sampleRate` | `24000` (or fixed preset rate) | Requested output rate: `8000`, `16000`, or `24000` Hz |
+| `timeScaleFactor` | Omitted (normal duration) | Duration multiplier from `0.4` to `2.5`; below 1 is faster, above 1 is slower |
 | `timestamps` | `false` | Request final word timestamps; requires `model: "mistv3"` |
 | `customLexicon` | `[]` | Array of pronunciation overrides for this request; requires Coda |
 | `timeout` | Client setting | Seconds; pass `null` to disable the overall deadline |
 
 ### Audio formats
 
-Both profiles return raw audio without a file header.
+All output is mono. PCM and WAV use signed 16-bit little-endian samples.
 
-| `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 |
+| `AudioFormat` | Encoding | Requested rate |
+| --- | --- | --- |
+| `PCM` | Headerless PCM16 | 8, 16, or 24 kHz |
+| `WAV` | PCM16 WAV | 8, 16, or 24 kHz |
+| `MP3` | MP3 (`audio/mpeg`) | 8, 16, or 24 kHz; encoded headers determine the actual rate |
+| `PCM_24000` | Headerless PCM16 compatibility preset | Fixed 24 kHz |
+| `MULAW_8000` | G.711 mu-law compatibility preset | Fixed 8 kHz |
+
+PCM/WAV sample rates are requested from the server; the SDK does not resample
+these formats. The existing mu-law preset still converts 24 kHz PCM locally.
+An explicit rate conflicting with a fixed preset fails locally. For configurable
+formats, `audio.format.sampleRate` is zero; use `audio.sampleRate` for the rate requested
+by the operation. Existing default streams still report `PCM_24000` as their format.
+
+PCM chunks contain complete sample frames. WAV and MP3 chunks are fragments of
+one encoded stream, not independent files. Streaming WAV may contain unknown
+lengths in its header; use `synthesizeToBuffer` for a completed IVR file.
+
+### Complete audio in memory
+
+Await `synthesizeToBuffer` to get all audio bytes. It uses the same streaming RPC,
+waits for successful completion, and finalizes WAV file lengths. On failure it
+raises an error and releases the stream; it never returns partial audio.
+The output limit is fixed at **64 MiB (67,108,864 bytes)** per call, including
+file headers. Exceeding it raises `RimeResourceLimitError` and returns no partial
+audio. For mono PCM16/WAV, this is approximately 70 minutes at 8 kHz, 35 minutes
+at 16 kHz, or 23 minutes at 24 kHz. Use streaming synthesis for larger outputs.
+Collection can temporarily use more memory than the output limit.
+Timeouts and client shutdown still apply. Use the streaming API to retrieve word timestamps.
 
-Chunks are `Uint8Array` values with complete sample frames; sizes vary. Inspect the
-read-only `audio.format.encoding`, `audio.format.sampleRate`, and `audio.format.channels`.
+```javascript
+import { writeFile } from "node:fs/promises";
+import { AudioFormat, Rime } from "@rimelabs/sdk";
+
+const client = new Rime();
+try {
+  const audio = await client.tts.synthesizeToBuffer("Thank you for calling.", {
+    audioFormat: AudioFormat.WAV, sampleRate: 16000, timeScaleFactor: 0.9,
+  });
+  await writeFile("greeting.wav", audio);
+} finally {
+  await client.close();
+}
+```
 
 ### Timeouts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",