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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **realtime:** expose Prism's speech hint ([#73](https://github.com/rimelabs/rime-sdk/issues/73)) ([cb7187d](https://github.com/rimelabs/rime-sdk/commit/cb7187d687c2210332fee704d43ac9ba45c760ea))
+
 ## [0.1.0-alpha.15](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.14...typescript-v0.1.0-alpha.15) (2026-10-13)
 
 

package/README.md

@@ -224,12 +224,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,6 +17,8 @@ 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;

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, TranscriptionFinal, TranscriptionUpdate, } from "./stt/types.js";

package/dist/realtime/protocol.js

@@ -192,6 +192,12 @@ function decodeValue(value, sessionId) {
         case "prism.typed_input.ready":
             payload = { kind: "input.ready" };
             break;
+        case "prism.input_audio_buffer.speech_hint":
+            payload = {
+                kind: "speech.hint",
+                audioStartMs: integer(event.audio_start_ms, "audio_start_ms"),
+            };
+            break;
         case "input_audio_buffer.speech_started":
             payload = {
                 kind: "speech.started",

package/dist/realtime/types.d.ts

@@ -81,6 +81,13 @@ export declare class RimeRealtimeError extends RimeError {
 export interface InputReady {
     readonly kind: "input.ready";
 }
+/** The user may have started speaking over a playing reply. Prism sends it
+ * before `speech.started` when it may interrupt the reply; it can be a false
+ * alarm, so lower playback on it rather than stopping. */
+export interface SpeechHint {
+    readonly kind: "speech.hint";
+    readonly audioStartMs: number;
+}
 export interface SpeechStarted {
     readonly kind: "speech.started";
     readonly itemId: string;
@@ -164,7 +171,7 @@ export interface FaultEvent {
     readonly kind: "error";
     readonly error: RealtimeFault;
 }
-export type InputEvent = InputReady | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed;
+export type InputEvent = InputReady | SpeechHint | SpeechStarted | SpeechStopped | InputCommitted | TranscriptDelta | TranscriptFinal | TranscriptFailed;
 export type ResponseEvent = ResponseStarted | ResponseAbandoned | MessageStarted | TextDelta | TextDone | AudioDelta | AudioDone | ToolCall | ResponseEnded;
 export interface SessionEvent {
     readonly sessionId: 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,40 +11,72 @@ 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 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,
             mode,
@@ -56,8 +89,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 +104,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/transport.d.ts

@@ -1,11 +1,13 @@
 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>;

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();

package/dist/stt/types.d.ts

@@ -32,3 +32,11 @@ export interface TranscriptionFinal {
     readonly language: string;
 }
 export type TranscriptionUpdate = TranscriptionPartial | TranscriptionFinal;
+/** Options for a complete WAV recording. Audio is sent unchanged. */
+export type TranscribeOptions = Omit<TranscriptionOptions, "inputFormat">;
+/** 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

@@ -130,6 +130,7 @@ are exported from `@rimelabs/sdk`.
 | Kind | Payload fields |
 | --- | --- |
 | `input.ready` | No data fields. Turn methods handle the readiness wait. |
+| `speech.hint` | `audioStartMs`; the user may have started speaking over a playing reply. It can be a false alarm: lower playback, do not stop it. |
 | `speech.started`, `speech.stopped` | `itemId` and `audioStartMs` or `audioEndMs` |
 | `input.committed` | `itemId` |
 | `transcript.delta`, `transcript.final` | `itemId` and `delta` or `text` |

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

package/package.json

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