@rimelabs/sdk 0.1.0-alpha.1 → 0.1.0-alpha.12

package/dist/tts/transport.js

@@ -0,0 +1,116 @@
+import { connect as connectGrpc } from "../grpc.js";
+export { metadata } from "../grpc.js";
+import { BidiCall, serializer, deserializer, requestId, nativeError, } from "../grpc.js";
+export { rpcError } from "../grpc.js";
+import * as grpc from "@grpc/grpc-js";
+import { create, } from "@bufbuild/protobuf";
+import * as schema from "@rimelabs/api";
+import { policy } from "./policy.js";
+import { abortable } from "../cancellation.js";
+import * as errors from "../errors.js";
+export const transport = {
+    makeClient: (target) => new grpc.Client(target, grpc.credentials.createSsl(), {
+        "grpc.enable_retries": 0,
+        "grpc.max_receive_message_length": policy.receiveBytes,
+        "grpc.max_send_message_length": policy.sentenceBytes + 65536,
+    }),
+};
+export function connect(client, signal) {
+    return connectGrpc(client, signal, policy.connectionTimeout);
+}
+function openStream(client, auth) {
+    return client.makeBidiStreamRequest("/rime.TextToSpeech/SynthesizeStreaming", serializer(schema.StreamingSynthesisRequestSchema), deserializer(schema.SynthesisResponseStreamSchema), auth);
+}
+function header(voice, language) {
+    return create(schema.StreamingSynthesisRequestSchema, {
+        payload: {
+            case: "header",
+            value: create(schema.SynthesisRequestSchema, {
+                speaker: voice,
+                language,
+                audioParameters: { audioFormat: "audio/pcm", samplingRate: 24000 },
+            }),
+        },
+    });
+}
+function textMessage(text) {
+    return create(schema.StreamingSynthesisRequestSchema, {
+        payload: { case: "textChunk", value: text },
+    });
+}
+async function unary(prepared, name, input, output, request, signal) {
+    let call;
+    let id = null;
+    try {
+        signal.throwIfAborted();
+        const operation = new Promise((resolve, reject) => {
+            call = prepared.client.makeUnaryRequest("/rime.TextToSpeech/" + name, serializer(input), deserializer(output), request, prepared.metadata, (error, result) => (error ? reject(error) : resolve(result)));
+            call.once("metadata", (metadata) => {
+                id = requestId(metadata);
+            });
+        });
+        return await abortable(operation, signal);
+    }
+    catch (error) {
+        call?.cancel();
+        if (signal.aborted) {
+            if (signal.reason instanceof errors.RimeTimeoutError)
+                throw new errors.RimeTimeoutError(signal.reason.message, id, {
+                    cause: signal.reason.cause,
+                });
+            throw signal.reason;
+        }
+        throw nativeError(error, id);
+    }
+}
+export async function discover(prepared, kind, language, signal) {
+    // Exactly one attempt. The client owns retries and the shared deadline.
+    if (kind === "voices") {
+        const method = schema.TextToSpeech.method.getSupportedSpeakers;
+        const response = await unary(prepared, method.name, method.input, method.output, create(method.input, { language: language ?? undefined }), signal);
+        return response.speakers;
+    }
+    const method = schema.TextToSpeech.method.getSupportedLanguages;
+    const response = await unary(prepared, method.name, method.input, method.output, create(method.input), signal);
+    return response.languages;
+}
+export class SynthesisCall {
+    rpc;
+    constructor(prepared, signal) {
+        this.rpc = new BidiCall(openStream(prepared.client, prepared.metadata), signal);
+    }
+    get requestId() {
+        return this.rpc.requestId;
+    }
+    get done() {
+        return this.rpc.done;
+    }
+    cancel() {
+        this.rpc.cancel();
+    }
+    start(voice, language) {
+        return this.rpc.write(header(voice, language));
+    }
+    write(sentence) {
+        return this.rpc.write(textMessage(sentence));
+    }
+    finishInput() {
+        this.rpc.finishInput();
+    }
+    checkFormat(contentType) {
+        if (contentType !== "audio/pcm")
+            throw new errors.RimeAudioFormatError("Expected raw audio/pcm from the service", this.requestId);
+    }
+    async *audio() {
+        const headers = await this.rpc.headers();
+        const contentType = headers.get("x-rime-audio-content-type")[0];
+        for await (const response of this.rpc.responses()) {
+            if (response.payload.case !== "audio")
+                continue;
+            if (response.payload.value.length)
+                this.checkFormat(contentType);
+            yield response.payload.value;
+        }
+        this.checkFormat(contentType);
+    }
+}

package/dist/validation.d.ts

@@ -0,0 +1,5 @@
+export declare function endpointAddress(endpoint: string): {
+    target: string;
+    audience: string;
+};
+export declare function timeout(value: unknown, inherited?: number | null): number | null;

package/dist/validation.js

@@ -0,0 +1,28 @@
+import { RimeInputError } from "./errors.js";
+export function endpointAddress(endpoint) {
+    const error = "endpoint must be a hostname with an optional port (1-65535), without a scheme or path";
+    if (typeof endpoint !== "string" || /\s/.test(endpoint))
+        throw new RimeInputError(error);
+    const [host, port, extra] = endpoint.split(":");
+    if (!host ||
+        host.length > 253 ||
+        extra !== undefined ||
+        host
+            .split(".")
+            .some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)) ||
+        (port !== undefined &&
+            (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)))
+        throw new RimeInputError(error);
+    return {
+        target: `${host.toLowerCase()}:${port === undefined ? 443 : Number(port)}`,
+        audience: host.toLowerCase(),
+    };
+}
+export function timeout(value, inherited = null) {
+    if (value === undefined)
+        return inherited;
+    if (value !== null &&
+        (typeof value !== "number" || !Number.isFinite(value) || value <= 0))
+        throw new RimeInputError("timeout must be finite positive seconds or null");
+    return value;
+}

package/docs/realtime.md

@@ -0,0 +1,220 @@
+# Realtime / Prism for Node.js
+
+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.
+
+Start with the [recorded-speech quick start](../README.md#prism-send-recorded-speech)
+to save a spoken reply without audio hardware.
+
+For live conversations, keep the session open after normal cancellation and
+report playback from the output clock. Saving a file is not playback.
+Typed turns also support mixed text and voice applications.
+
+## Connect
+
+Use `await client.realtime.connect(options)`. It opens a WebSocket, initializes
+one conversation, and returns a `RealtimeSession`. Settings apply once. Open a
+new session to change them.
+
+| Option | Required? | Default and behavior |
+| --- | --- | --- |
+| `endpoint` | Yes | Full `wss://host/v1/realtime` URL. Plain `ws://` is allowed only for localhost. |
+| `voice` | If the server has no default voice | Omitted or `null` uses the server default. Supplied strings must be nonblank. |
+| `instructions` | No | Omitted or `null` uses server defaults. Supplied strings must be nonblank. |
+| `tools` | No | `[]`. Each tool requires `name` and a JSON Schema `parameters` object. `description` defaults to `""`. |
+| `interruptOnSpeech` | No | `true`. Requests interruption when the server confirms user speech. |
+| `timeouts` | No | `{ connectS: 10, readyS: 30, requestS: 10 }`. Each field is optional. Units are seconds. |
+| `model` | No | `"prism"`, the only accepted value. |
+| `signal` | No | An `AbortSignal` that cancels connection setup. It does not cancel an established session. |
+
+Credentials come from `new Rime({ apiKey: "..." })` or `RIME_API_KEY`. Prism uses
+`Authorization: Bearer <key>`, without a TTS token exchange. TTS endpoint, model,
+voice, and timeout settings do not apply to Realtime.
+
+After connection, `session.info` contains `sessionId`, `model`, `voice`,
+`interruptOnSpeech`, `toolResultTimeoutS`, and `toolContinuationTimeoutS`.
+Check the effective interruption setting there. Tool wait durations are total
+server deadlines, not remaining time. A `null` duration can mean an omitted
+field; it does not prove that no deadline exists.
+
+Close the session in `finally` with `await session.close()`. Closing the parent
+client closes all its TTS and Realtime operations. Both objects also support
+`Symbol.asyncDispose`. Repeated close calls are safe.
+
+## Choose an operation
+
+Every method returns a promise. Arguments without `?` are required.
+
+| Method | Result and behavior |
+| --- | --- |
+| `sendText(text, options?)` | Starts a typed user turn after readiness; returns `ResponseRef` at response creation. |
+| `sendAudio(chunk, options?)` | Sends microphone audio with transport backpressure. |
+| `requestReply(options?)` | Requests a reply without new user input; returns `ResponseRef`. Options can include `instruction` and `toolCall`. |
+| `addMessage(role, text, options?)` | Adds user or assistant history without a reply; returns `ItemRef` after acknowledgment. |
+| `submitToolResult(call, output, options?)` | Records a string result and waits for acknowledgment. |
+| `continueReply(parent, options?)` | Waits for parent completion and all tool result acknowledgments, then returns a new `ResponseRef`. |
+| `cancel(response, options?)` | Requests generation cancellation and waits for a terminal response or refusal. |
+| `clearAudio(options?)` | Clears buffered input and resets audio conversion after acknowledgment. |
+| `reportPlayback(report, options?)` | Reports interrupted or finished playback. |
+| `close()` | Closes the session and releases its resources. |
+
+Operation options accept `signal?: AbortSignal`. `requestReply` accepts its
+instruction, tool call, and signal in one object. Methods other than `sendText`,
+`requestReply`, `addMessage`, and `continueReply` return `Promise<void>`.
+
+Text must be nonblank and contain at most 4,000 Unicode characters. History
+roles are `"user"` and `"assistant"`. A reply instruction applies to one response;
+it does not replace session instructions.
+
+A returned `ResponseRef` means generation started. Read `response.ended` for the
+terminal status. Generation can finish before cancellation takes effect, so a
+successful `cancel()` does not guarantee a `"cancelled"` status.
+
+## Send audio
+
+Pass a plain object with `data: Uint8Array`. Node.js `Buffer` is also accepted.
+The optional `format` object defaults to 16 kHz mono signed little-endian PCM16.
+
+```typescript
+await session.sendAudio({
+  data: pcmBytes,
+  format: { sampleRate: 48000, channels: 2 },
+});
+```
+
+Supported `sampleRate` values are `8000`, `16000`, `24000`, and `48000`.
+Channels can be `1` or `2`; `encoding` can only be `"pcm_s16le"`. Each field in
+`format` is optional. Chunks must contain complete sample frames and at most
+192,000 bytes. The SDK downmixes and resamples to 16 kHz mono, retaining state
+across calls. A format change or acknowledged `clearAudio()` resets that state.
+
+Await each send and bound your capture queue. Keep audio flowing, including
+silence and while the assistant speaks or tools run. Prism detects and commits
+speech; there is no manual commit method. Echo cancellation belongs to your app.
+
+Received `audio.delta` events carry 24 kHz mono PCM16. The outgoing chunk limit
+does not apply to received audio.
+
+## Handle tools
+
+Declare tools with plain `ToolDefinition` objects. Names must be nonblank and
+unique; schemas must contain finite JSON values. The SDK copies schemas before
+connection setup, so later caller changes cannot alter initialization.
+
+Execute a tool once for each `tool.call` event. Validate its parsed `arguments`,
+then submit a string result with `submitToolResult(payload.call, output)`.
+Use `JSON.stringify(...)` for a structured result. Call
+`continueReply(payload.call)` when the assistant should answer; a tool call
+reference also carries its parent response identity.
+
+Keep the event consumer running while submitting tool results and requesting
+continuation. Run slow tools asynchronously or in a worker so they do not block
+the event loop.
+
+A new user turn or proactive reply supersedes the old tool round. Late results
+can still be recorded. Use `requestReply({ toolCall: call })` to ask the assistant
+to report a recorded result. Repeating the same result is safe within the live
+session; changing it is rejected. Do not rerun a tool because delivery failed.
+
+## Read events and references
+
+Use `for await (const event of session.events)`. Each `SessionEvent` has
+`sessionId`, `eventId`, nullable `requestId`, and a `payload`. Switch on
+`payload.kind` to narrow the TypeScript union. All public types and error classes
+are exported from `@rimelabs/sdk`.
+
+| Kind | Payload fields |
+| --- | --- |
+| `input.ready` | No data fields. Turn methods handle the readiness wait. |
+| `speech.started`, `speech.stopped` | `itemId` and `audioStartMs` or `audioEndMs` |
+| `input.committed` | `itemId` |
+| `transcript.delta`, `transcript.final` | `itemId` and `delta` or `text` |
+| `transcript.failed` | `itemId`, `error` |
+| `response.started` | `response`, `cause`, nullable `parent` and `inputItemId` |
+| `message.started` | `output` |
+| `text.delta`, `text.done` | `output` and `delta` or `text` |
+| `audio.delta`, `audio.done` | `output`; a delta also has `audio.data` and a complete `audio.format` |
+| `tool.call` | `call`, `itemId`, `name`, parsed `arguments` |
+| `response.ended` | `response`, `status`, nullable `reason` |
+| `response.abandoned` | `response`; the SDK requests cancellation after the requesting caller aborted. |
+| `error` | `error`, a `RealtimeFault` |
+
+References come from the SDK. Pass them back to identify the object you mean.
+
+| Reference | Fields |
+| --- | --- |
+| `ResponseRef` | `sessionId`, `responseId` |
+| `ItemRef` | `sessionId`, `itemId` |
+| `ToolCallRef` | `sessionId`, `responseId`, `callId` |
+| `OutputRef` | `response`, `itemId`, `outputIndex`, `contentIndex` |
+
+Every reference belongs to one session. Only the last 128 responses are retained;
+older references expire. Current output uses `contentIndex: 0`.
+
+Unknown event kinds and extra fields are ignored. Unknown response causes,
+terminal statuses, and error scopes become `"unknown"`. An absent response cause
+means speech. The local `response.abandoned` event has an empty `eventId` and
+`requestId: null`; it can follow `response.ended` when completion races cancellation.
+
+## Report playback
+
+Generation completion and playback completion are separate. Report the player's
+actual state, including output latency and queued audio.
+
+| Report object | Required fields | Optional fields |
+| --- | --- | --- |
+| Interrupted | `kind: "interrupted"`, `output`, `audioEndMs` | None |
+| Finished | `kind: "finished"`, `response` | `playedMs`, `audibleTailMs`; both default to `null` |
+
+Pass the object to `await session.reportPlayback(report)`. Interruption records
+the point where caller speech stopped an assistant message. `audioEndMs` must
+be an integer from 0 through 4,294,967,295. Finished playback means all queued
+audio has played or has permanently stopped. Optional durations must be finite,
+nonnegative milliseconds. The SDK waits for generation completion and supplies
+the server's drain token.
+
+Saving audio does not establish playback. Reports are optional. If you cannot
+measure playback, omit them and let the server use its estimate. The recorded and typed examples have no player and omit these reports.
+The voice examples report actual playback.
+
+## Timeouts and failures
+
+Configure positive, finite seconds through `timeouts`. `connectS` bounds the
+WebSocket handshake and initial session event. `readyS` bounds turn admission,
+tool readiness, and waiting for generation to end before a playback report.
+Once a request is submitted, `requestS` bounds its write and acknowledgment.
+
+These limits do not bound the entire conversation or generation after creation.
+Set an application deadline and close the session when it expires. The recorded and typed examples use a 60-second deadline. Voice conversations
+run until stopped or the connection fails.
+
+`RealtimeAdmissionTimeout` means readiness expired with no request outstanding;
+the session remains usable. An unknown request outcome closes the connection and
+is never replayed. The SDK retries typed-turn admission only after named refusals
+that confirm the request made no change.
+
+Protocol faults appear as `error` events and can also reject an affected method
+with `RimeRealtimeError`. Its `.fault` has `code`, `message`, `scope`, nullable
+`requestId`, `responseId`, `itemId`, `correlationId`, `parameter`, and a `callIds`
+array. A response fault does not itself end generation. Session faults and lost
+connections end the session.
+
+Malformed fields in known events and mismatched request acknowledgments close
+the session with `RimeStreamError`. Unknown event kinds and extra fields remain
+accepted and ignored. The SDK does not replay a request after a protocol failure.
+
+Aborting an operation rejects it with `RimeCancelledError`. For reply requests,
+the SDK prevents an unsent request or cancels a late accepted response. Control
+operations can wait for acknowledgment before rejecting, to keep acknowledgment
+matching correct. A submitted tool result keeps matching its acknowledgment even
+if its caller aborts. Aborting audio after submission starts closes the session;
+before submission, it restores conversion state. Do not resend a chunk with an
+unknown outcome.
+
+Keep up with the event stream. The queue holds 256 events; incoming messages
+are limited to 1 MiB. A slow consumer ends the session. There is no automatic
+reconnect, history replay, or live configuration update.
+
+Local peer tests cover the SDK protocol handling. Validate the gateway handshake
+and endpoint behavior for the deployment you use.

package/docs/stt.md

@@ -0,0 +1,103 @@
+# Streaming speech recognition
+
+`client.stt.stream` transcribes one utterance from an async source of `Uint8Array` chunks (including Node buffers).
+The SDK handles the gRPC protocol, authentication, audio conversion, transcript
+revisions, backpressure, and cancellation. Your application decides when speech
+ends by exhausting the source.
+
+```typescript
+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",
+    inputFormat: { sampleRate: 16000, channels: 1 },
+    mode: "written",
+    contextTerms: ["Super-G", "USOC"],
+    timeout: 120,
+  });
+  for await (const update of transcript) {
+    if (update.kind === "partial") console.log("Current transcript:", update.text);
+    else console.log("Final:", update.text, "Language:", update.language);
+  }
+  console.log("Request:", transcript.requestId);
+} finally {
+  await client.close();
+}
+```
+
+The runnable [example](../examples/stt/stream.mjs) reads a PCM file
+without loading it all into memory. Use Node.js 22 or later; browsers are not supported.
+Open files inside the async generator so file errors are reported through the
+SDK and resources are opened only after the service accepts the utterance.
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| `language` | Required spoken BCP-47 tag. Passed unchanged to the service; no detection or SDK language allowlist. The deployed catalog currently supports English and Spanish. |
+| `mode` | `"written"` (default) or `"verbatim"`. Formatting intent, not a guarantee of exact tokens. |
+| `contextTerms` | Sequence of recognition hints, copied unchanged and in order. The service validates terms and prompt budgets. |
+| `inputFormat` | `PCMFormat`: signed little-endian PCM16 at 8, 16, 24 or 48 kHz, mono or interleaved stereo. Defaults to 16 kHz mono. |
+| `timeout` | Optional positive overall timeout in seconds. Includes connection time, source pauses and consumer pauses. `null` disables this SDK deadline, but not internal or server deadlines. |
+
+Input contains raw samples, with no WAV header or compressed codec. Chunks may
+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.
+The existing `model`, `endpoint` and client `timeout` settings remain TTS settings.
+There is no STT voice/model selector; the service selects its recognizer.
+
+## Results and completion
+
+`TranscriptionPartial` and `TranscriptionFinal` are discriminated TypeScript types, exported from `@rimelabs/sdk`. Every update contains the complete current `text`.
+**Replace the previous transcript. Do not concatenate partials.** Later partials
+can change earlier words. `TranscriptionFinal.language` is the canonical language
+selected by the service.
+
+The source is not consumed until the server accepts the configuration. Audio
+upload and transcript reading run concurrently. Decoding currently uses cumulative
+two-second audio windows, so a partial is not promised for each audio packet.
+Silence can finish successfully with empty final text and no partials.
+
+Exhausting the source half-closes gRPC input. The SDK continues reading and emits
+one final result only after a matching `done` and successful gRPC completion.
+EOF, an error status, or cancellation cannot turn a partial into a final result.
+No audio is automatically replayed after a connection failure.
+
+## Lifetime and limits
+
+Construction is lazy: starting iteration begins work. Consume each stream with
+one reader. Breaking a `for await` loop calls the iterator's `return` and cancels
+unfinished work. `await transcript.cancel()` and async disposal also cancel it.
+Pass an `AbortSignal` through the stream's `signal` option to cancel just that
+utterance. Client close cancels all STT, TTS and realtime operations; cancelling
+one stream leaves its siblings running.
+
+The SDK bounds the transcript queue to 16 updates, each with at most 64 KiB of
+UTF-8 text, and bounds gRPC responses to 256 KiB. Slow consumers apply backpressure.
+Internal connection and acceptance waits are 10 seconds; completion after source
+exhaustion is bounded to 120 seconds. The completion timer stops after successful
+gRPC completion. The optional overall timeout remains active until the final
+result is consumed. An outstanding source `next()` cannot be forcibly stopped by
+JavaScript; the SDK stops waiting for it and attempts `return()` for at most two
+seconds. Sources that own devices should support cancellation themselves.
+
+Server input-idle, utterance-size, request-duration and model-context limits still
+apply. The current wire limit is 16 MiB per utterance; model context can impose a
+smaller limit depending on audio and recognition terms. There is no SDK VAD,
+server endpointing, word timing, diarization, or file-format detection.
+
+Failures use the shared SDK error hierarchy: caller/input errors, cancellation,
+authentication, permission, resource limits, timeouts, transient availability and
+protocol failures stay distinct. `requestId` is retained on streams and failures
+when the server supplies it. Keep it when reporting a problem.

package/docs/tts.md

@@ -0,0 +1,139 @@
+# TTS for Node.js
+
+You supply text; the SDK handles sentence boundaries and streams audio back.
+Your application owns playback. Start with the complete WAV example in the
+[package quick start](../README.md#tts-save-speech).
+
+## Complete text
+
+Use `client.tts.synthesize(text)` for one nonblank string. It returns an audio
+stream; it does not wait for all audio to be generated. Do not await this call.
+Use the audio loop and cleanup shown in the package quick start.
+
+## Stream incoming text
+
+Use `client.tts.stream(chunks)` for an async iterable of strings. A plain string
+belongs in `synthesize`, not `stream`. The source can supply partial sentences:
+
+```javascript
+async function* text() {
+  yield "Hello. ";
+  yield "This text arrives in separate chunks.";
+}
+```
+
+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. The quick start collects chunks before writing a WAV file.
+
+## Configuration
+
+Select Mist v3 with `new Rime({ model: "mistv3" })`. Mist v1 and v2 are not supported.
+
+| Model | Standard endpoint | Default voice |
+| --- | --- | --- |
+| `coda` | `coda.api.rime.ai:443` | `clementine` |
+| `mistv3` | `mist.api.rime.ai:443` | `astra` |
+
+### Client 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 |
+
+Authentication uses bearer tokens over TLS. The SDK does not load `.env` files.
+
+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.
+
+### 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:
+
+| 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 |
+
+### Audio formats
+
+Both profiles return raw audio without a file header.
+
+| `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 |
+
+Chunks are `Uint8Array` values with complete sample frames; sizes vary. Inspect the
+read-only `audio.format.encoding`, `audio.format.sampleRate`, and `audio.format.channels`.
+
+### Timeouts
+
+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.
+
+## Discover voices and languages
+
+List voices and languages while the client is open:
+
+```javascript
+const voices = await client.voices.list({ language: "en" });
+const languages = await client.languages.list();
+console.log(voices, languages);
+```
+
+Both return string arrays and accept `timeout`. Omit `language` to disable filtering.
+
+## Errors and cancellation
+
+Report SDK errors and request IDs while closing the client on failure:
+
+```javascript
+import { writeFile } from "node:fs/promises";
+import { Rime, RimeError } from "@rimelabs/sdk";
+
+let client;
+try {
+  client = new Rime();
+  await writeFile("speech.pcm", client.tts.synthesize("Hello. This is Rime."));
+} catch (error) {
+  if (error instanceof RimeError) {
+    console.error(`Speech failed: ${error.message}; requestId=${error.requestId}`);
+  }
+  throw error;
+} finally {
+  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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.1",
-  "description": "Rime streaming text-to-speech SDK for Node.js",
+  "version": "0.1.0-alpha.12",
+  "description": "Rime streaming TTS, STT and Prism realtime SDK for Node.js",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -16,8 +16,11 @@
   },
   "files": [
     "dist",
+    "docs",
     "vendor",
     "LICENSE",
+    "LICENSE-PRISM",
+    "NOTICE-PRISM",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -26,16 +29,21 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test tests/*.test.mjs",
     "prepack": "npm run build",
-    "lint": "prettier --check src tests"
+    "lint": "prettier --check src tests examples/tts examples/realtime examples/common examples/browser examples/tests examples/stt"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
     "@grpc/grpc-js": "^1.14.0",
-    "@rimelabs/api": "0.0.1"
+    "@rimelabs/api": "0.4.0",
+    "ws": "^8.22.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.2",
+    "ajv": "^8.20.0",
     "prettier": "3.9.8",
-    "typescript": "^5.9.0"
-  }
+    "typescript": "^5.9.0",
+    "yaml": "^2.9.1"
+  },
+  "homepage": "https://docs.rime.ai/"
 }