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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/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/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.14",
   "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",