@rimelabs/sdk 0.1.0-alpha.7 → 0.1.0-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.0-alpha.9](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.8...typescript-v0.1.0-alpha.9) (2026-10-08)
+
+
+### Bug Fixes
+
+* make package quickstarts usable without repository access ([#24](https://github.com/rimelabs/rime-sdk/issues/24)) ([3a30b83](https://github.com/rimelabs/rime-sdk/commit/3a30b83ecaad1740c84d1e8c005520522cf56d26))
+
+## [0.1.0-alpha.8](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.7...typescript-v0.1.0-alpha.8) (2026-10-08)
+
+
+### Features
+
+* add voice examples and automate example dependency updates ([#22](https://github.com/rimelabs/rime-sdk/issues/22)) ([dea7044](https://github.com/rimelabs/rime-sdk/commit/dea7044831058ebee9ae536e8d822a4d7fabbd3d))
+
 ## [0.1.0-alpha.7](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.6...typescript-v0.1.0-alpha.7) (2026-10-07)
 
 

package/README.md

@@ -1,93 +1,175 @@
 # Rime SDK for Node.js
 
-Stream speech from a string or async text source. The SDK handles sentence
-boundaries, authentication, and audio conversion; your application owns playback.
-Use Prism for conversations with audio input, typed turns, and tools.
+Generate speech with TTS, or send speech to Prism and receive a spoken reply.
+Both APIs use the `Rime` client. Your application handles audio capture and playback.
 
 ## Install
 
-Requires Node.js 22 or later. This alpha package uses ESM and includes TypeScript
-types. Browser use is not supported.
+Requires Node.js 22 or later. This alpha package uses ESM and includes TypeScript types.
+Run it on a server. Browser use is not supported.
 
 ```sh
-npm install @rimelabs/sdk
+mkdir rime-quickstart
+cd rime-quickstart
+npm init -y
+npm install @rimelabs/sdk wavefile
 export RIME_API_KEY="your-api-key"
 ```
 
-An explicit `new Rime({ apiKey: "..." })` overrides the environment. The SDK
-does not load `.env` files.
+Get a TTS API key from the [Rime dashboard](https://app.rime.ai/).
+An explicit `new Rime({ apiKey: "..." })` overrides `RIME_API_KEY`. The SDK does not load `.env` files.
+The commands below use a macOS or Linux shell.
 
-## TTS quick start
+These examples use JavaScript `.mjs` files so you can run them without a TypeScript build.
+The additional [wavefile package](https://github.com/rochars/wavefile) reads and writes WAV files
+for the examples. It is not required by the SDK.
 
-Save this as `speech.mjs` and run `node speech.mjs`:
+## TTS: save speech
+
+Save this as `tts.mjs`. It writes a playable `speech.wav` file with no audio-device dependencies.
 
 ```javascript
-import { writeFile } from "node:fs/promises";
+import { writeFileSync } from "node:fs";
+import wavefile from "wavefile";
 import { Rime } from "@rimelabs/sdk";
 
-const client = new Rime();
+const client = new Rime({ timeout: 60 });
 try {
-  const audio = client.tts.stream("Hello. This is Rime.");
-  await writeFile("speech.pcm", audio);
-  console.log(audio.requestId);
+  const chunks = [];
+  for await (const chunk of client.tts.stream(
+    "Your appointment is confirmed for tomorrow.",
+  )) {
+    chunks.push(Buffer.from(chunk));
+  }
+  const pcm = Buffer.concat(chunks);
+  const samples = Array.from({ length: pcm.length / 2 }, (_, i) =>
+    pcm.readInt16LE(i * 2),
+  );
+  const wav = new wavefile.WaveFile();
+  wav.fromScratch(1, 24000, "16", samples);
+  writeFileSync("speech.wav", wav.toBuffer());
+  console.log("Saved speech.wav");
 } finally {
   await client.close();
 }
 ```
 
-Output is raw mono 24 kHz signed little-endian PCM16, with no WAV header.
-The default model is Coda. Select Mist v3 with `new Rime({ model: "mistv3" })`.
+Run `node tts.mjs`, then open `speech.wav` in your audio player.
+This short example collects the audio in memory before writing the file.
+For long responses, write audio chunks as they arrive.
+
+Coda is the default model. Use `new Rime({ model: "mistv3" })` for Mist v3, or pass
+`{ voice: "your-voice" }` as the second argument to `client.tts.stream(...)` to select a voice.
+The default output is mono 24 kHz PCM16. The example adds its WAV header.
+To supply text from an LLM, pass an async iterable of strings instead of a string.
+The SDK handles sentence boundaries.
 
-For streamed text, voices, audio formats, and cancellation, read the
-[TTS guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/tts.md).
-Runnable scripts are in the [examples](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md).
+## Prism: send recorded speech
 
-## Prism quick start
+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.
+
+```sh
+export PRISM_URL="wss://your-prism-host/v1/realtime"
+export PRISM_VOICE="your-deployment-voice"
+```
 
-Set `PRISM_URL` to your deployment's full `wss://host/v1/realtime` endpoint.
-Supply `PRISM_VOICE` unless the deployment has a default 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`.
 
 ```javascript
+import { readFileSync, writeFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import wavefile from "wavefile";
 import { Rime, RimeRealtimeError } from "@rimelabs/sdk";
 
+const input = new wavefile.WaveFile(readFileSync("question.wav"));
+if (
+  input.container !== "RIFF" ||
+  input.fmt.audioFormat !== 1 ||
+  input.fmt.numChannels !== 1 ||
+  input.fmt.sampleRate !== 16000 ||
+  input.bitDepth !== "16"
+) {
+  throw new Error("question.wav must be 16 kHz mono PCM16");
+}
+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 deadline = setTimeout(() => void client.close(), 60_000);
+const stop = new AbortController();
+const deadline = setTimeout(() => {
+  stop.abort();
+  void client.close();
+}, 60_000);
+let sending;
 let reading;
 try {
   const session = await client.realtime.connect({
-    endpoint: process.env.PRISM_URL,
+    endpoint,
     voice: process.env.PRISM_VOICE,
+    instructions: "Give short, clear answers.",
   });
+  sending = (async () => {
+    for (let offset = 0; ; offset += 1280) {
+      const frame = Buffer.alloc(1280);
+      if (offset < data.length)
+        data.copy(frame, 0, offset, Math.min(offset + 1280, data.length));
+      await session.sendAudio({ data: frame });
+      await sleep(40, undefined, { signal: stop.signal });
+    }
+  })();
+  const chunks = [];
   reading = (async () => {
     for await (const { payload } of session.events) {
-      if (payload.kind === "text.delta") process.stdout.write(payload.delta);
+      if (payload.kind === "audio.delta")
+        chunks.push(Buffer.from(payload.audio.data));
       if (payload.kind === "error") throw new RimeRealtimeError(payload.error);
       if (payload.kind === "response.ended") {
-        if (payload.status !== "completed")
-          throw new Error(`Response ${payload.status}`);
+        if (payload.status !== "completed") {
+          throw new Error(`Response ${payload.status}: ${payload.reason}`);
+        }
         return;
       }
     }
-    throw new Error("Session closed before the response ended");
+    throw new Error("Session closed before the reply ended");
   })();
-  await Promise.all([reading, session.sendText("Hello!")]);
+  await Promise.race([sending, reading]);
+  const pcm = Buffer.concat(chunks);
+  const samples = Array.from({ length: pcm.length / 2 }, (_, i) =>
+    pcm.readInt16LE(i * 2),
+  );
+  const wav = new wavefile.WaveFile();
+  wav.fromScratch(1, 24000, "16", samples);
+  writeFileSync("reply.wav", wav.toBuffer());
+  console.log("Saved reply.wav");
 } finally {
+  stop.abort();
   clearTimeout(deadline);
   await client.close();
-  await reading?.catch(() => {});
+  await Promise.allSettled([sending, reading]);
 }
 ```
 
-This example prints text and discards audio. The
-[Realtime guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/realtime.md)
-covers audio input, tools, playback reports, and cancellation. Runnable
-[Prism examples](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md#nodejs)
-save audio and handle tools. TTS settings do not apply to Prism sessions.
+Run `node prism.mjs`, then open `reply.wav`. This example has a 60-second deadline
+and collects the reply in memory. It saves audio without playing it, so it sends no playback receipt.
+For live conversations, your application must capture microphone audio, play replies,
+stop playback on interruption, and report the actual played position to Prism.
+Keep the API key on your server when you add a browser interface.
+TTS settings do not configure Prism sessions.
+
+## Help and licenses
 
-## License
+See [Rime documentation](https://docs.rime.ai/) for API keys, TTS models, and deployment information.
+The examples above run with the installed package. No source checkout is required.
 
-SDK code uses the [MIT license](https://github.com/rimelabs/rime-sdk/blob/main/typescript/LICENSE).
-The Prism protocol module uses the [Apache 2.0 license](https://github.com/rimelabs/rime-sdk/blob/main/typescript/LICENSE-PRISM).
-BlingFire retains its [upstream license](https://github.com/rimelabs/rime-sdk/blob/main/typescript/vendor/LICENSE.blingfire).
-Its WASM runtime ships with the package; the SDK downloads no code or models at
-runtime. See [vendor provenance](https://github.com/rimelabs/rime-sdk/blob/main/typescript/vendor/README.md).
+SDK code uses the MIT license. The Prism protocol module uses Apache 2.0.
+BlingFire retains its MIT license. License texts and notices are included in the package.
+Its WASM runtime ships with the package. The SDK downloads no code or models at runtime.

package/docs/realtime.md

@@ -4,10 +4,12 @@ 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 [package quick start](../README.md#prism-quick-start), or run the
-[typed-turn example](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/realtime/typed-turn.mjs).
-The [example setup](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md#nodejs)
-lists the commands and environment variables. This API requires Node.js 22 or later.
+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
 
@@ -106,10 +108,9 @@ 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.
 
-The [tool example](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/realtime/tools.mjs)
-keeps the event consumer running while result submissions and continuation wait.
-It uses local order data. Slow tools need asynchronous work or a worker thread
-so they do not block the Node.js event loop.
+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
@@ -174,8 +175,8 @@ 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 examples
-have no player and omit these reports.
+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
 
@@ -185,8 +186,8 @@ 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. Both examples
-use a 60-second deadline.
+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
@@ -215,6 +216,5 @@ 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.
 
-The [pinned contract](https://github.com/rimelabs/rime-sdk/blob/main/conformance/prism/README.md)
-is the local test target. The deployed gateway handshake and endpoint behavior
-still need validation for the deployment you use.
+Local peer tests cover the SDK protocol handling. Validate the gateway handshake
+and endpoint behavior for the deployment you use.

package/docs/tts.md

@@ -1,8 +1,8 @@
 # TTS for Node.js
 
 You supply text; the SDK handles sentence boundaries and streams audio back.
-Your application owns playback. Start with the [package quick start](../README.md),
-or run the [streaming example](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/tts/stream.mjs).
+Your application owns playback. Start with the complete WAV example in the
+[package quick start](../README.md#tts-save-speech).
 
 ## Stream incoming text
 
@@ -17,7 +17,7 @@ async function* text() {
 
 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. `writeFile` consumes the stream for you.
+iterator read starts work. The quick start collects chunks before writing a WAV file.
 
 ## Configuration
 

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "Rime streaming TTS and Prism realtime SDK for Node.js",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rimelabs/rime-sdk.git",
-    "directory": "typescript"
-  },
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -34,7 +29,7 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test tests/*.test.mjs",
     "prepack": "npm run build",
-    "lint": "prettier --check src tests ../examples/typescript/tts ../examples/typescript/realtime"
+    "lint": "prettier --check src tests ../examples/typescript/tts ../examples/typescript/realtime ../examples/typescript/common ../examples/typescript/browser ../examples/typescript/tests"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
@@ -49,5 +44,6 @@
     "prettier": "3.9.8",
     "typescript": "^5.9.0",
     "yaml": "^2.9.1"
-  }
+  },
+  "homepage": "https://docs.rime.ai/"
 }