@rimelabs/sdk 0.1.0-alpha.16 → 0.1.0-alpha.18

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.1.0-alpha.18](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.17...typescript-v0.1.0-alpha.18) (2026-10-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rust TranscriptionUpdate and TypeScript TranscriptionUpdate include Delta/delta; exhaustive handlers must handle the new variant.
+
+### Features
+
+* add append-fragment STT streaming across SDKs ([369f04d](https://github.com/rimelabs/rime-sdk/commit/369f04dadfea9d3d8593d14283d64e3a1f36e4d1))
+* default realtime connections to public Prism and add optional turn timing controls ([#86](https://github.com/rimelabs/rime-sdk/issues/86)) ([0e07f68](https://github.com/rimelabs/rime-sdk/commit/0e07f6852bf0cefb60b8a42c48c2b76f95ac2362))
+
+## [0.1.0-alpha.17](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.16...typescript-v0.1.0-alpha.17) (2026-10-16)
+
+
+### Features
+
+* add unary STT transcription to all SDKs ([#80](https://github.com/rimelabs/rime-sdk/issues/80)) ([39427eb](https://github.com/rimelabs/rime-sdk/commit/39427eba7738e4f2fe0514a2cddaa219137dcc4d))
+
 ## [0.1.0-alpha.16](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.15...typescript-v0.1.0-alpha.16) (2026-10-16)
 
 

package/README.md

@@ -28,16 +28,10 @@ STT use the SDK and Node.js built-ins.
 
 ## Prism: send recorded speech
 
-Prism needs a deployment that serves its realtime API. Obtain the endpoint,
-credentials, and voice from your deployment operator. The TTS endpoint does not serve Prism.
-Set `RIME_API_KEY` to the credential for that deployment if it differs from your TTS key.
+With `RIME_API_KEY` set, the SDK connects to
+`wss://prism.api.rime.ai/v1/realtime` and uses the server's default voice.
+Pass `endpoint` or `voice` to select another deployment or voice.
 
-```sh
-export PRISM_URL="wss://your-prism-host/v1/realtime"
-export PRISM_VOICE="your-deployment-voice"
-```
-
-You can omit `PRISM_VOICE` if the deployment has a default voice.
 Record a short question and export it as `question.wav`, using **16 kHz, mono, signed 16-bit PCM WAV**.
 Save the following as `prism.mjs` beside that file. It sends the recording at capture speed,
 then sends silence so Prism can detect the end of speech. The spoken reply goes to `reply.wav`.
@@ -61,9 +55,6 @@ if (
 const data = Buffer.from(input.data.samples);
 if (!data.length || data.length % 2)
   throw new Error("question.wav has no complete PCM16 audio");
-const endpoint = process.env.PRISM_URL;
-if (!endpoint)
-  throw new Error("Set PRISM_URL to your deployment's /v1/realtime URL");
 
 const client = new Rime();
 const stop = new AbortController();
@@ -75,8 +66,6 @@ let sending;
 let reading;
 try {
   const session = await client.realtime.connect({
-    endpoint,
-    voice: process.env.PRISM_VOICE,
     instructions: "Give short, clear answers.",
   });
   sending = (async () => {
@@ -224,12 +213,51 @@ and model/language support.
 
 ## STT
 
+### Transcribe a complete WAV recording
+
+For a complete recording, use the native unary `Transcribe` RPC through the SDK.
+Pass **complete WAV bytes, including the header**, up to **16 MiB (16,777,216
+bytes)**. PCM16 mono 16 kHz WAV is the portable format. The SDK sends the file
+unchanged; it does not decode, resample, or add a header. The service validates
+its encoding and the supplied language and recognition hints.
+
+The result is a `Transcription` containing final text, resolved language, and a
+request ID when available. Silence may return empty text. There are no partial
+updates or automatic retries. TTS client settings do not apply. An optional
+overall timeout includes connection and upload; the SDK also bounds connection
+time and the unary request (120 seconds). Timeout, cancellation, and service
+errors use the existing SDK error categories. A request ID is included when the
+transport has made it available.
+
+```typescript
+import { readFile } from "node:fs/promises";
+import { Rime } from "@rimelabs/sdk";
+
+const client = new Rime();
+try {
+  const result = await client.stt.transcribe(await readFile("utterance.wav"), {
+    language: "en",
+    mode: "written",
+    contextTerms: ["Super-G", "USOC"],
+    timeout: 120,
+  });
+  console.log(result.text, result.language, result.requestId);
+} finally {
+  await client.close();
+}
+```
+
+`TranscribeOptions` also accepts an `AbortSignal` as `signal`. Aborting it or
+closing the client cancels pending requests with `RimeCancelledError`.
+
+### Stream an utterance
+
 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
+STT uses gRPC over TLS to `stt.api.rime.ai:443`, with the client's API
 key. There is no STT model, endpoint, or protocol selector. TTS client settings,
 including its timeout, do not apply to STT.
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioSource, TranscriptionOptions } from "./stt/types.js";
+import type { AudioSource, TranscriptionOptions, TranscribeOptions, Transcription } from "./stt/types.js";
 import type { TranscriptStream } from "./stt/stream.js";
 import { type SynthesisOptions, type DiscoveryOptions, type VoiceListOptions } from "./tts/client.js";
 import { type AudioStream, type TextSource } from "./tts/stream.js";
@@ -17,11 +17,13 @@ export declare class Rime {
     private readonly ttsClient;
     private readonly sttClient;
     readonly stt: {
+        /** Transcribe complete WAV bytes. PCM16 mono 16 kHz is the portable format; maximum 16 MiB. */
+        transcribe: (audio: Uint8Array, options: TranscribeOptions) => Promise<Transcription>;
         stream: (audio: AudioSource, options: TranscriptionOptions) => TranscriptStream;
     };
     private readonly realtimeClient;
     readonly realtime: {
-        connect: (options: RealtimeConnectOptions) => Promise<RealtimeSession>;
+        connect: (options?: RealtimeConnectOptions) => Promise<RealtimeSession>;
     };
     private closed;
     private closing;

package/dist/client.js

@@ -27,6 +27,7 @@ export class Rime {
         this.credentials = new Credentials(key, deployment);
         this.sttClient = new STT(this.credentials, () => this.checkOpen());
         this.stt = {
+            transcribe: (audio, options) => this.sttClient.transcribe(audio, options),
             stream: (audio, options) => this.sttClient.stream(audio, options),
         };
         this.realtimeClient = new Realtime(this.credentials, () => this.checkOpen());

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export * from "./errors.js";
 export { RealtimeSession } from "./realtime/session.js";
 export * from "./realtime/types.js";
 export { TranscriptStream } from "./stt/stream.js";
-export type { AudioSource, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";
+export type { AudioSource, TranscribeOptions, Transcription, TranscriptionOptions, TranscriptionMode, TranscriptionPartial, TranscriptionDelta, TranscriptionOutputContract, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";

package/dist/realtime/client.d.ts

@@ -7,6 +7,6 @@ export declare class Realtime {
     private readonly sessions;
     private readonly opening;
     constructor(credentials: Credentials, checkOpen: () => void);
-    connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
+    connect(options?: RealtimeConnectOptions): Promise<RealtimeSession>;
     close(): Promise<void>;
 }

package/dist/realtime/client.js

@@ -3,6 +3,7 @@ import { RimeCancelledError, RimeInputError, RimeUnavailableError, } from "../er
 import { cancellation, scope } from "./async.js";
 import { RealtimeSession } from "./session.js";
 import { RealtimeConnection } from "./transport.js";
+const DEFAULT_ENDPOINT = "wss://prism.api.rime.ai/v1/realtime";
 function endpoint(value) {
     let url;
     try {
@@ -56,9 +57,9 @@ export class Realtime {
         this.credentials = credentials;
         this.checkOpen = checkOpen;
     }
-    async connect(options) {
+    async connect(options = {}) {
         this.checkOpen();
-        const address = endpoint(options.endpoint);
+        const address = endpoint(options.endpoint === undefined ? DEFAULT_ENDPOINT : options.endpoint);
         const limits = timeouts(options.timeouts);
         if ((options.model ?? "prism") !== "prism")
             throw new RimeInputError("The realtime model must be prism");
@@ -103,6 +104,24 @@ export class Realtime {
                 };
             }),
         };
+        if (options.turnDetection !== undefined) {
+            const detection = options.turnDetection;
+            if (!detection ||
+                typeof detection !== "object" ||
+                Array.isArray(detection))
+                throw new RimeInputError("turnDetection must be an object");
+            if (detection.eagerness !== undefined) {
+                if (!["low", "medium", "high", "auto"].includes(detection.eagerness))
+                    throw new RimeInputError("Turn eagerness must be low, medium, high, or auto");
+                settings.turn_detection.eagerness = detection.eagerness;
+            }
+            if (detection.endOfTurnTimeoutMs !== undefined) {
+                const value = detection.endOfTurnTimeoutMs;
+                if (!Number.isInteger(value) || value < 1000 || value > 10000)
+                    throw new RimeInputError("End-of-turn timeout must be an integer from 1000 to 10000 ms");
+                settings.turn_detection.prism_end_of_turn_timeout_ms = value;
+            }
+        }
         for (const name of ["voice", "instructions"]) {
             const value = options[name];
             if (value !== undefined && value !== null) {

package/dist/realtime/protocol.d.ts

@@ -4,6 +4,8 @@ export interface SessionSettings {
     input_audio_format: "pcm16";
     turn_detection: {
         interrupt_response: boolean;
+        eagerness?: t.TurnEagerness;
+        prism_end_of_turn_timeout_ms?: number;
     };
     tools: {
         type: "function";
@@ -22,6 +24,7 @@ export interface SessionView {
     interruptOnSpeech: boolean | null;
     toolResultTimeoutS: number | null;
     toolContinuationTimeoutS: number | null;
+    turnDetection: t.TurnDetectionInfo;
 }
 export interface SessionCreated {
     kind: "session.created";

package/dist/realtime/protocol.js

@@ -66,6 +66,30 @@ function duration(value, field) {
 }
 function session(value) {
     const view = object(value, "session");
+    const detection = view.turn_detection === undefined
+        ? {}
+        : object(view.turn_detection, "session.turn_detection");
+    let eagerness = null;
+    if (detection.eagerness !== undefined) {
+        const value = string(detection.eagerness, "session.turn_detection.eagerness");
+        eagerness =
+            value === "low" ||
+                value === "medium" ||
+                value === "high" ||
+                value === "auto"
+                ? value
+                : "unknown";
+    }
+    let endOfTurnTimeoutMs = null;
+    if (detection.prism_end_of_turn_timeout_ms !== undefined) {
+        const value = detection.prism_end_of_turn_timeout_ms;
+        if (typeof value !== "number" ||
+            !Number.isInteger(value) ||
+            value < 1000 ||
+            value > 10000)
+            invalid("session.turn_detection.prism_end_of_turn_timeout_ms");
+        endOfTurnTimeoutMs = value;
+    }
     const waits = view.prism_tool_waits === undefined
         ? {}
         : object(view.prism_tool_waits, "session.prism_tool_waits");
@@ -79,6 +103,7 @@ function session(value) {
         id: id(view.id, "session.id"),
         voice: view.voice === undefined ? "" : string(view.voice, "session.voice"),
         interruptOnSpeech: interrupt ?? null,
+        turnDetection: Object.freeze({ eagerness, endOfTurnTimeoutMs }),
         toolResultTimeoutS: duration(waits.result_timeout_s, "result_timeout_s"),
         toolContinuationTimeoutS: duration(waits.continuation_timeout_s, "continuation_timeout_s"),
     };

package/dist/realtime/session.js

@@ -109,6 +109,7 @@ export class RealtimeSession {
             interruptOnSpeech: view.interruptOnSpeech ?? settings.turn_detection.interrupt_response,
             toolResultTimeoutS: view.toolResultTimeoutS ?? null,
             toolContinuationTimeoutS: view.toolContinuationTimeoutS ?? null,
+            turnDetection: view.turnDetection,
         });
     }
     get info() {

package/dist/realtime/types.d.ts

@@ -19,13 +19,28 @@ export interface ToolDefinition {
     readonly parameters: JsonObject;
     readonly description?: string;
 }
+export type TurnEagerness = "low" | "medium" | "high" | "auto";
+/** Omitted fields use the server's turn timing defaults. */
+export interface TurnDetection {
+    /** How readily Prism decides that the user has finished speaking. */
+    readonly eagerness?: TurnEagerness;
+    /** Maximum silence before ending a turn: an integer from 1000 to 10000 ms. */
+    readonly endOfTurnTimeoutMs?: number;
+}
+/** Effective server settings. Null means the server did not publish the field. */
+export interface TurnDetectionInfo {
+    readonly eagerness: TurnEagerness | "unknown" | null;
+    readonly endOfTurnTimeoutMs: number | null;
+}
 export interface RealtimeConnectOptions extends RealtimeOperationOptions {
-    readonly endpoint: string;
+    /** Defaults to wss://prism.api.rime.ai/v1/realtime. */
+    readonly endpoint?: string;
     readonly model?: "prism";
     readonly voice?: string | null;
     readonly instructions?: string | null;
     readonly tools?: readonly ToolDefinition[];
     readonly interruptOnSpeech?: boolean;
+    readonly turnDetection?: TurnDetection;
     readonly timeouts?: RealtimeTimeouts;
 }
 export interface ReplyOptions extends RealtimeOperationOptions {
@@ -60,6 +75,7 @@ export interface SessionInfo {
     readonly interruptOnSpeech: boolean;
     readonly toolResultTimeoutS: number | null;
     readonly toolContinuationTimeoutS: number | null;
+    readonly turnDetection: TurnDetectionInfo;
 }
 export interface RealtimeFault {
     readonly code: string;

package/dist/stt/client.d.ts

@@ -1,12 +1,17 @@
 import { Credentials } from "../auth.js";
 import { TranscriptStream } from "./stream.js";
-import type { AudioSource, TranscriptionOptions } from "./types.js";
+import type { AudioSource, TranscriptionOptions, TranscribeOptions, Transcription } from "./types.js";
 export declare class STT {
     private readonly credentials;
     private readonly checkOpen;
     private connection;
     private streams;
+    private readonly cancellation;
+    private readonly requests;
     constructor(credentials: Credentials, checkOpen: () => void);
+    /** Transcribe complete WAV bytes (at most 16 MiB), without replay or retries. */
+    transcribe(audio: Uint8Array, options: TranscribeOptions): Promise<Transcription>;
+    private prepare;
     stream(source: AudioSource, options: TranscriptionOptions): TranscriptStream;
     close(): Promise<void>;
 }

package/dist/stt/client.js

@@ -1,8 +1,9 @@
 import { connect, metadata } from "../grpc.js";
 import { timeout } from "../validation.js";
-import { RimeInputError } from "../errors.js";
+import { RimeInputError, RimeAudioFormatError, RimeResourceLimitError, RimeCancelledError, RimeTimeoutError, } from "../errors.js";
+import { scope } from "../cancellation.js";
 import { resolvePCMFormat } from "../pcm.js";
-import { transport, requireSchema } from "./transport.js";
+import { transport, requireSchema, transcribe, MAX_WAV_BYTES, } from "./transport.js";
 import { TranscriptStream } from "./stream.js";
 import { policy } from "./policy.js";
 export class STT {
@@ -10,42 +11,79 @@ export class STT {
     checkOpen;
     connection = null;
     streams = new Set();
+    cancellation = new AbortController();
+    requests = new Set();
     constructor(credentials, checkOpen) {
         this.credentials = credentials;
         this.checkOpen = checkOpen;
     }
+    /** Transcribe complete WAV bytes (at most 16 MiB), without replay or retries. */
+    transcribe(audio, options) {
+        this.checkOpen();
+        if (!(audio instanceof Uint8Array) || audio.byteLength === 0)
+            throw new RimeAudioFormatError("audio must contain complete WAV bytes");
+        if (audio.byteLength > MAX_WAV_BYTES)
+            throw new RimeResourceLimitError("WAV input exceeds 16 MiB");
+        validateOptions(options);
+        const settings = {
+            ...options,
+            contextTerms: [...(options.contextTerms ?? [])],
+        };
+        const data = Buffer.from(audio);
+        const deadline = scope([options.signal, this.cancellation.signal], timeout(options.timeout) ?? undefined, new RimeTimeoutError("Overall transcription deadline expired"));
+        const operation = (async () => {
+            try {
+                const prepared = await this.prepare(deadline.signal, policy.target);
+                return await transcribe(prepared.client, prepared.metadata, data, settings, deadline.signal);
+            }
+            catch (error) {
+                if (deadline.signal.aborted &&
+                    !(error instanceof RimeTimeoutError) &&
+                    !(error instanceof RimeCancelledError)) {
+                    if (deadline.signal.reason instanceof RimeTimeoutError)
+                        throw deadline.signal.reason;
+                    throw new RimeCancelledError("Transcription cancelled");
+                }
+                throw error;
+            }
+            finally {
+                deadline.dispose();
+            }
+        })();
+        this.requests.add(operation);
+        void operation.then(() => this.requests.delete(operation), () => this.requests.delete(operation));
+        return operation;
+    }
+    async prepare(signal, target) {
+        this.checkOpen();
+        requireSchema();
+        signal.throwIfAborted();
+        const headers = metadata(this.credentials.authorization());
+        this.connection ??= transport.makeClient(target);
+        await connect(this.connection, signal, policy.connectionTimeout);
+        signal.throwIfAborted();
+        return { client: this.connection, metadata: headers };
+    }
     stream(source, options) {
         this.checkOpen();
         if (!source || typeof source[Symbol.asyncIterator] !== "function")
             throw new RimeInputError("audio must be an async iterable of Uint8Array chunks");
-        if (!options || typeof options.language !== "string")
-            throw new RimeInputError("language must be a string");
+        validateOptions(options);
+        const outputContract = options.outputContract ?? "revised_hypotheses";
+        if (outputContract !== "revised_hypotheses" &&
+            outputContract !== "append_fragments")
+            throw new RimeInputError("outputContract must be revised_hypotheses or append_fragments");
         const mode = options.mode ?? "written";
-        if (mode !== "written" && mode !== "verbatim")
-            throw new RimeInputError("mode must be written or verbatim");
         const terms = options.contextTerms ?? [];
-        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 = policy.target;
         const stream = new TranscriptStream({
             checkOpen: this.checkOpen,
             forget: (stream) => this.streams.delete(stream),
-            prepare: async (signal) => {
-                this.checkOpen();
-                requireSchema();
-                signal.throwIfAborted();
-                const headers = metadata(this.credentials.authorization());
-                this.connection ??= transport.makeClient(target);
-                await connect(this.connection, signal, policy.connectionTimeout);
-                signal.throwIfAborted();
-                return {
-                    client: this.connection,
-                    metadata: headers,
-                };
-            },
+            prepare: (signal) => this.prepare(signal, target),
         }, source, {
             language: options.language,
+            outputContract,
             mode,
             contextTerms: [...terms],
             inputFormat: format,
@@ -56,8 +94,12 @@ export class STT {
         return stream;
     }
     async close() {
+        this.cancellation.abort(new RimeCancelledError("Client closed"));
         try {
-            const results = await Promise.allSettled([...this.streams].map((stream) => stream.cancel()));
+            const results = await Promise.allSettled([
+                ...[...this.streams].map((stream) => stream.cancel()),
+                ...[...this.requests].map((request) => request.catch(() => { })),
+            ]);
             for (const result of results)
                 if (result.status === "rejected")
                     throw result.reason;
@@ -67,3 +109,13 @@ export class STT {
         }
     }
 }
+function validateOptions(options) {
+    if (!options || typeof options.language !== "string")
+        throw new RimeInputError("language must be a string");
+    const mode = options.mode ?? "written";
+    if (mode !== "written" && mode !== "verbatim")
+        throw new RimeInputError("mode must be written or verbatim");
+    const terms = options.contextTerms ?? [];
+    if (!Array.isArray(terms) || terms.some((term) => typeof term !== "string"))
+        throw new RimeInputError("contextTerms must be an array of strings");
+}

package/dist/stt/policy.js

@@ -5,7 +5,7 @@ export const policy = {
     acceptanceTimeout: 10,
     completionTimeout: 120,
     cleanupTimeout: 2,
-    receiveBytes: 262144,
-    transcriptBytes: 65536,
+    receiveBytes: 1048576 + 65536,
+    transcriptBytes: 1048576,
     queuedUpdates: 16,
 };

package/dist/stt/protocol.d.ts

@@ -1,13 +1,14 @@
 import * as schema from "@rimelabs/api";
-import type { TranscriptionPartial, TranscriptionFinal } from "./types.js";
+import type { TranscriptionPartial, TranscriptionDelta, TranscriptionFinal, TranscriptionOutputContract } from "./types.js";
 /** Validate the wire sequence before exposing any final result. */
 export declare class TranscriptState {
     private readonly textLimit;
+    private readonly outputContract;
     language: string | null;
     private revision;
     private text;
     private final;
-    constructor(textLimit: number);
-    accept(message: schema.StreamingTranscriptionResponse, inputDone: boolean): TranscriptionPartial | null;
+    constructor(textLimit: number, outputContract?: TranscriptionOutputContract);
+    accept(message: schema.StreamingTranscriptionResponse, inputDone: boolean): TranscriptionPartial | TranscriptionDelta | null;
     finish(): TranscriptionFinal;
 }

package/dist/stt/protocol.js

@@ -3,12 +3,14 @@ import { RimeStreamError, RimeResourceLimitError } from "../errors.js";
 /** Validate the wire sequence before exposing any final result. */
 export class TranscriptState {
     textLimit;
+    outputContract;
     language = null;
     revision = 0n;
     text = "";
     final = null;
-    constructor(textLimit) {
+    constructor(textLimit, outputContract = "revised_hypotheses") {
         this.textLimit = textLimit;
+        this.outputContract = outputContract;
     }
     accept(message, inputDone) {
         const payload = message.payload;
@@ -21,7 +23,9 @@ export class TranscriptState {
             if (this.language !== null)
                 throw new RimeStreamError("Received duplicate transcription acceptance");
             if (accepted.outputContract !==
-                schema.StreamingOutputContract.REVISED_HYPOTHESES)
+                (this.outputContract === "append_fragments"
+                    ? schema.StreamingOutputContract.APPEND_FRAGMENTS
+                    : schema.StreamingOutputContract.REVISED_HYPOTHESES))
                 throw new RimeStreamError("The service accepted a different transcript contract");
             if (!accepted.language?.tag || !accepted.language.source)
                 throw new RimeStreamError("The service did not confirm a resolved language");
@@ -30,8 +34,19 @@ export class TranscriptState {
         }
         if (this.language === null)
             throw new RimeStreamError("Received a transcript before acceptance");
+        const append = this.outputContract === "append_fragments";
+        if (payload.case === "delta" && append) {
+            const text = payload.value.text;
+            if (Buffer.byteLength(this.text) + Buffer.byteLength(text) >
+                this.textLimit)
+                throw new RimeResourceLimitError("The transcript exceeds the SDK text limit");
+            this.text += text;
+            return { kind: "delta", text };
+        }
         if (payload.case !== "hypothesis" && payload.case !== "done")
             throw new RimeStreamError("Received an unexpected transcription response");
+        if (payload.case === "hypothesis" && append)
+            throw new RimeStreamError("Received an unexpected transcription response");
         const value = payload.value;
         if (Buffer.byteLength(value.text, "utf8") > this.textLimit)
             throw new RimeResourceLimitError("The transcript exceeds the SDK text limit");
@@ -46,7 +61,7 @@ export class TranscriptState {
         if (!inputDone)
             throw new RimeStreamError("The service completed before input finished");
         if (value.revision !== this.revision || value.text !== this.text)
-            throw new RimeStreamError("Final transcript does not match the last hypothesis");
+            throw new RimeStreamError("Final transcript does not match prior updates");
         const language = payload.value.language;
         if (language?.tag !== this.language || !language.source)
             throw new RimeStreamError("Final language does not match the accepted language");

package/dist/stt/stream.js

@@ -130,7 +130,7 @@ export class TranscriptStream {
         }
     }
     async read() {
-        const state = new TranscriptState(policy.transcriptBytes);
+        const state = new TranscriptState(policy.transcriptBytes, this.options.outputContract);
         for await (const message of this.call.responses()) {
             const update = state.accept(message, this.inputDone);
             if (state.language !== null) {
@@ -149,7 +149,7 @@ export class TranscriptStream {
             this.controller.signal.throwIfAborted();
             this.call = new TranscriptionCall(prepared.client, prepared.metadata, this.controller.signal);
             this.admission = this.deadline(policy.acceptanceTimeout, "Transcription acceptance timed out");
-            await this.call.start(this.options.language, this.options.mode ?? "written", this.options.contextTerms ?? []);
+            await this.call.start(this.options.language, this.options.mode ?? "written", this.options.contextTerms ?? [], this.options.outputContract);
             const producer = this.produce(), reader = this.read();
             tasks = [producer, reader];
             const [, final] = await Promise.all([producer, reader]);

package/dist/stt/transport.d.ts

@@ -1,13 +1,15 @@
 import * as grpc from "@grpc/grpc-js";
 import * as schema from "@rimelabs/api";
 import { BidiCall } from "../grpc.js";
-import type { TranscriptionMode } from "./types.js";
+import type { TranscriptionMode, TranscribeOptions, Transcription } from "./types.js";
+export declare const MAX_WAV_BYTES: number;
 export declare function requireSchema(): void;
 export declare const transport: {
     makeClient: (target: string) => grpc.Client;
 };
+export declare function transcribe(client: grpc.Client, auth: grpc.Metadata, audio: Uint8Array, options: TranscribeOptions, signal: AbortSignal): Promise<Transcription>;
 export declare class TranscriptionCall extends BidiCall<schema.StreamingTranscriptionRequest, schema.StreamingTranscriptionResponse> {
     constructor(client: grpc.Client, auth: grpc.Metadata, signal: AbortSignal);
-    start(language: string, mode: TranscriptionMode, contextTerms: readonly string[]): Promise<void>;
+    start(language: string, mode: TranscriptionMode, contextTerms: readonly string[], outputContract?: import("./types.js").TranscriptionOutputContract): Promise<void>;
     writeAudio(audio: Uint8Array): Promise<void>;
 }

package/dist/stt/transport.js

@@ -1,9 +1,11 @@
 import * as grpc from "@grpc/grpc-js";
 import { create } from "@bufbuild/protobuf";
 import * as schema from "@rimelabs/api";
-import { BidiCall, serializer, deserializer } from "../grpc.js";
-import { RimeInputError } from "../errors.js";
+import { BidiCall, serializer, deserializer, requestId, nativeError, } from "../grpc.js";
+import { abortable, scope } from "../cancellation.js";
+import { RimeInputError, RimeStreamError, RimeResourceLimitError, RimeTimeoutError, RimeCancelledError, } from "../errors.js";
 import { policy } from "./policy.js";
+export const MAX_WAV_BYTES = 16 * 1024 * 1024;
 export function requireSchema() {
     if (!schema.SpeechToText)
         throw new RimeInputError("STT requires @rimelabs/api with SpeechToText definitions");
@@ -12,9 +14,54 @@ 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": 131072,
+        "grpc.max_send_message_length": MAX_WAV_BYTES + 65536,
     }),
 };
+export async function transcribe(client, auth, audio, options, signal) {
+    const method = schema.SpeechToText.method.transcribe;
+    const deadline = scope([signal], policy.completionTimeout, new RimeTimeoutError("Transcription request timed out"));
+    let call;
+    let id = null;
+    try {
+        deadline.signal.throwIfAborted();
+        const result = await abortable(new Promise((resolve, reject) => {
+            call = client.makeUnaryRequest(`/${schema.SpeechToText.typeName}/${method.name}`, serializer(method.input), deserializer(method.output), create(method.input, {
+                audio,
+                options: {
+                    language: options.language,
+                    mode: options.mode === "verbatim"
+                        ? schema.TranscriptionMode.VERBATIM
+                        : schema.TranscriptionMode.WRITTEN,
+                    contextTerms: [...(options.contextTerms ?? [])],
+                },
+            }), auth, (error, response) => (error ? reject(error) : resolve(response)));
+            call.on("metadata", (headers) => {
+                id = requestId(headers);
+            });
+            call.on("status", (status) => {
+                id ??= requestId(status.metadata);
+            });
+        }), deadline.signal);
+        if (!result.language?.tag || !result.language.source)
+            throw new RimeStreamError("The service did not confirm a resolved language", id);
+        if (Buffer.byteLength(result.text) > policy.transcriptBytes)
+            throw new RimeResourceLimitError("The transcript exceeds the SDK text limit", id);
+        return { text: result.text, language: result.language.tag, requestId: id };
+    }
+    catch (error) {
+        if (deadline.signal.aborted) {
+            const reason = deadline.signal.reason;
+            if (reason instanceof RimeTimeoutError)
+                throw new RimeTimeoutError(reason.message, id);
+            throw new RimeCancelledError("Transcription cancelled", id);
+        }
+        throw nativeError(error, id);
+    }
+    finally {
+        call?.cancel();
+        deadline.dispose();
+    }
+}
 export class TranscriptionCall extends BidiCall {
     constructor(client, auth, signal) {
         requireSchema();
@@ -22,7 +69,7 @@ export class TranscriptionCall extends BidiCall {
         const method = service.method.transcribeStreaming;
         super(client.makeBidiStreamRequest(`/${service.typeName}/${method.name}`, serializer(method.input), deserializer(method.output), auth), signal);
     }
-    start(language, mode, contextTerms) {
+    start(language, mode, contextTerms, outputContract = "revised_hypotheses") {
         return this.write(create(schema.StreamingTranscriptionRequestSchema, {
             payload: {
                 case: "config",
@@ -32,7 +79,9 @@ export class TranscriptionCall extends BidiCall {
                         ? schema.TranscriptionMode.VERBATIM
                         : schema.TranscriptionMode.WRITTEN,
                     contextTerms: [...contextTerms],
-                    outputContract: schema.StreamingOutputContract.REVISED_HYPOTHESES,
+                    outputContract: outputContract === "append_fragments"
+                        ? schema.StreamingOutputContract.APPEND_FRAGMENTS
+                        : schema.StreamingOutputContract.REVISED_HYPOTHESES,
                 },
             },
         }));

package/dist/stt/types.d.ts

@@ -3,7 +3,16 @@ import type { PCMFormat } from "../pcm.js";
 export type TranscriptionMode = "written" | "verbatim";
 /** One caller-ended utterance of headerless signed PCM16 little-endian audio. */
 export type AudioSource = AsyncIterable<Uint8Array>;
+/** Select replacement hypotheses (default) or permanent append fragments. */
+export type TranscriptionOutputContract = "revised_hypotheses" | "append_fragments";
+export interface TranscriptionDelta {
+    readonly kind: "delta";
+    /** Append exactly, preserving the server's newline separators. */
+    readonly text: string;
+}
 export interface TranscriptionOptions {
+    /** Defaults to revised_hypotheses. Each stream uses one fixed contract. */
+    outputContract?: TranscriptionOutputContract;
     /** Required BCP-47 tag, passed unchanged to the service (for example "en"). */
     language: string;
     /** Formatting intent; defaults to written and does not guarantee exact tokens. */
@@ -31,4 +40,12 @@ export interface TranscriptionFinal {
     /** Canonical BCP-47 tag selected by the service, for example "en". */
     readonly language: string;
 }
-export type TranscriptionUpdate = TranscriptionPartial | TranscriptionFinal;
+export type TranscriptionUpdate = TranscriptionPartial | TranscriptionDelta | TranscriptionFinal;
+/** Options for a complete WAV recording. Audio is sent unchanged. */
+export type TranscribeOptions = Omit<TranscriptionOptions, "inputFormat" | "outputContract">;
+/** A successful whole-recording transcription. Silence may produce empty text. */
+export interface Transcription {
+    readonly text: string;
+    readonly language: string;
+    readonly requestId: string | null;
+}

package/docs/realtime.md

@@ -16,17 +16,18 @@ 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.
+Use `await client.realtime.connect()` with `RIME_API_KEY` set. 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. |
+| `endpoint` | No | Defaults to `wss://prism.api.rime.ai/v1/realtime`. Overrides must be full URLs; 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. |
+| `turnDetection` | No | Omitted settings use the server's turn timing defaults. |
 | `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. |
@@ -36,7 +37,8 @@ Credentials come from `new Rime({ apiKey: "..." })` or `RIME_API_KEY`. Prism use
 voice, and timeout settings do not apply to Realtime.
 
 After connection, `session.info` contains `sessionId`, `model`, `voice`,
-`interruptOnSpeech`, `toolResultTimeoutS`, and `toolContinuationTimeoutS`.
+`interruptOnSpeech`, `turnDetection`, `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.
@@ -45,6 +47,39 @@ 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.
 
+## Optional turn timing
+
+Pass a `TurnDetection` object to override how readily Prism ends a spoken turn.
+Each field is optional; omitted fields use server defaults.
+
+| Field | Values | Current server default |
+| --- | --- | --- |
+| `eagerness` | `"low"`, `"medium"`, `"high"`, `"auto"` | `"auto"`, equivalent to `"medium"` |
+| `endOfTurnTimeoutMs` | Integer from 1,000 through 10,000 | 5,000 ms |
+
+`"low"` waits for more certainty that the user has finished. `"high"` answers
+sooner, with more risk of cutting in. The timeout is a maximum silence limit,
+not a fixed delay before each reply. If the server falls back to its local
+voice activity detector, it ends turns after 500 ms of silence instead.
+
+```typescript
+const session = await client.realtime.connect({
+  turnDetection: { eagerness: "low", endOfTurnTimeoutMs: 5000 },
+});
+try {
+  console.log(session.info.turnDetection);
+  // Send input and consume session.events here.
+} finally {
+  await session.close();
+}
+```
+
+`session.info.turnDetection` is a `TurnDetectionInfo` with the settings the
+server reported in its initialization acknowledgment. A missing field is
+`null`; the SDK does not substitute a requested value or assume a server
+default. An unrecognized server eagerness becomes `"unknown"`.
+`interruptOnSpeech` remains a separate connection option.
+
 ## Choose an operation
 
 Every method returns a promise. Arguments without `?` are required.

package/docs/stt.md

@@ -1,4 +1,43 @@
-# Streaming speech recognition
+# Speech recognition
+
+## Complete recordings
+
+For a complete recording, use the native unary `Transcribe` RPC through the SDK.
+Pass **complete WAV bytes, including the header**, up to **16 MiB (16,777,216
+bytes)**. PCM16 mono 16 kHz WAV is the portable format. The SDK sends the file
+unchanged; it does not decode, resample, or add a header. The service validates
+its encoding and the supplied language and recognition hints.
+
+The result is a `Transcription` containing final text, resolved language, and a
+request ID when available. Silence may return empty text. There are no partial
+updates or automatic retries. TTS client settings do not apply. An optional
+overall timeout includes connection and upload; the SDK also bounds connection
+time and the unary request (120 seconds). Timeout, cancellation, and service
+errors use the existing SDK error categories. A request ID is included when the
+transport has made it available.
+
+```typescript
+import { readFile } from "node:fs/promises";
+import { Rime } from "@rimelabs/sdk";
+
+const client = new Rime();
+try {
+  const result = await client.stt.transcribe(await readFile("utterance.wav"), {
+    language: "en",
+    mode: "written",
+    contextTerms: ["Super-G", "USOC"],
+    timeout: 120,
+  });
+  console.log(result.text, result.language, result.requestId);
+} finally {
+  await client.close();
+}
+```
+
+`TranscribeOptions` also accepts an `AbortSignal` as `signal`. Aborting it or
+closing the client cancels pending requests with `RimeCancelledError`.
+
+## Streaming 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
@@ -24,7 +63,8 @@ try {
   });
   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);
+    else if (update.kind === "final")
+      console.log("Final:", update.text, "Language:", update.language);
   }
   console.log("Request:", transcript.requestId);
 } finally {
@@ -37,6 +77,37 @@ without loading it all into memory. Use Node.js 22 or later; browsers are not su
 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.
 
+## Append-fragment streaming
+
+Choose `outputContract: "append_fragments"` on
+`client.stt.stream`. The default is `"revised_hypotheses"`; `transcribe()` does not
+accept an output contract. Both streaming modes use gRPC only.
+
+```javascript
+let text = "";
+const transcript = client.stt.stream(audioChunks(), {
+  language: "en", outputContract: "append_fragments",
+});
+for await (const update of transcript) {
+  if (update.kind === "delta") text += update.text;
+  else if (update.kind === "final") console.log(update.text);
+}
+```
+
+`TranscriptionDelta` is a permanent fragment, not a replacement partial. The
+server recognizes independent five-second audio windows; fragments after the
+first include newline separators. Do not strip, add separators, or drop deltas.
+The final text must match their concatenation. Empty speech can produce no
+updates before an empty final. A final is delivered only after `done` and an OK
+gRPC status, so a connection failure never promotes accumulated fragments to a
+successful result.
+
+Append mode suits longer recordings and consumers that cannot revise text. Send
+recordings as fast as backpressure permits. It does not enable unlimited-length
+streams: the service's 16 MiB audio and 120-second total-call limits still apply.
+Split larger recordings into separate streams. Live voice agents usually prefer
+revised hypotheses for earlier provisional text and corrections across windows.
+
 ## Options
 
 | Option | Meaning |
@@ -44,6 +115,7 @@ SDK and resources are opened only after the service accepts the utterance.
 | `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. |
+| `outputContract` | `"revised_hypotheses"` (default) or `"append_fragments"`. Streaming only. |
 | `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. |
 
@@ -59,11 +131,18 @@ 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`.
+`TranscriptionPartial`, `TranscriptionDelta`, and `TranscriptionFinal` are discriminated types exported from `@rimelabs/sdk`. In the default revised-hypotheses mode, 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.
 
+When upgrading, `TranscriptionUpdate` now includes `TranscriptionDelta`. Update
+exhaustive handlers to handle `kind: "delta"`, even if you keep the default
+revised-hypotheses contract. Only finals have `language`: check
+`update.kind === "final"` before reading it, rather than assuming every
+non-partial update is final. Append deltas exactly; replace text with partials
+or the confirmed final.
+
 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.
@@ -83,8 +162,12 @@ 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.
+The SDK bounds the transcript queue to 16 updates. In revised-hypotheses mode,
+each replacement update is limited to 1 MiB of UTF-8 text; sizes are not summed
+across revisions. In append-fragments mode, the concatenated text across all
+deltas is limited to 1 MiB. The final transcript is also limited to 1 MiB in both
+modes. gRPC responses are bounded to 1 MiB plus 64 KiB for the protobuf envelope.
+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

package/package.json

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