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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

package/README.md

@@ -1,74 +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.
-
-## TTS quick start
-
-Save playable speech with the
-[WAV example](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/tts/save.ts).
-After the [example setup](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md#nodejs), run from the repository root:
-
-```sh
-npm --prefix examples/typescript run tts:save
+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.
+
+These examples use JavaScript `.mjs` files so you can run them without a TypeScript build.
+The additional [wavefile package](https://github.com/rochars/wavefile) reads and writes WAV files
+for the examples. It is not required by the SDK.
+
+## TTS: save speech
+
+Save this as `tts.mjs`. It writes a playable `speech.wav` file with no audio-device dependencies.
+
+```javascript
+import { writeFileSync } from "node:fs";
+import wavefile from "wavefile";
+import { Rime } from "@rimelabs/sdk";
+
+const client = new Rime({ timeout: 60 });
+try {
+  const chunks = [];
+  for await (const chunk of client.tts.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();
+}
 ```
 
-Open `examples/typescript/speech.wav` in your audio player. To hear streamed text
-as it arrives, run `npm --prefix examples/typescript run tts:play`, open the printed
-local URL, and press **Start**. **Stop** cancels generation and playback.
-
-Replace the example's async text source with your LLM's text stream. The SDK
-handles sentence boundaries. Coda is the default; select Mist v3 with
-`new Rime({ model: "mistv3" })`.
-The [TTS guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/tts.md)
-covers voices, formats, and cancellation.
+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.
 
-## Prism quick start
+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.
 
-Start a voice conversation in your browser. The Node.js server uses the SDK;
-the browser captures your microphone and plays replies. Use headphones, and
-speak during a reply to interrupt it. The API key stays on the local server.
+## Prism: send recorded speech
 
-Set `PRISM_URL` to your deployment's full WebSocket URL ending in `/v1/realtime`.
-Set `PRISM_VOICE` unless that deployment has a default. Obtain these values from
-your deployment operator; the TTS endpoint does not serve Prism.
-
-After the [example setup](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md#nodejs), run from the repository root:
+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
-npm --prefix examples/typescript run prism:voice
+export PRISM_URL="wss://your-prism-host/v1/realtime"
+export PRISM_VOICE="your-deployment-voice"
 ```
 
-Open the printed local URL and press **Start**. Without a microphone, send the
-included speech recording and save `reply.wav`:
-
-```sh
-npm --prefix examples/typescript run prism:recorded
+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 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,
+    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 === "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}: ${payload.reason}`);
+        }
+        return;
+      }
+    }
+    throw new Error("Session closed before the reply ended");
+  })();
+  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 Promise.allSettled([sending, reading]);
+}
 ```
 
-Run `prism:voice-tools` for the same conversation with a demo order lookup.
-The [Realtime guide](https://github.com/rimelabs/rime-sdk/blob/main/typescript/docs/realtime.md)
-covers audio, tools, playback reports, errors, and optional typed input.
+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.
 
-## License
+## Help and licenses
+
+See [Rime documentation](https://docs.rime.ai/) for API keys, TTS models, and deployment information.
+The examples above run with the installed package. No source checkout is required.
 
-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,16 +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 [voice conversation](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/realtime/voice.ts)
-for microphone input, playback, and caller interruption. The
-[recorded-speech example](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/realtime/recorded.ts)
-saves a spoken reply without audio hardware. See the
-[example setup](https://github.com/rimelabs/rime-sdk/blob/main/examples/README.md)
-for commands, device requirements, and the voice tool example.
+Start with the [recorded-speech quick start](../README.md#prism-send-recorded-speech)
+to save a spoken reply without audio hardware.
 
-Typed turns remain useful for connection checks and mixed text/voice applications.
-The live examples keep the session open after normal cancellation and report
-playback from the output clock. Saving a file is not playback.
+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
 
@@ -112,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
@@ -221,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,12 +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).
-
-For a playable file, use [save speech](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/tts/save.ts).
-For immediate playback and cancellation, use [stream and play](https://github.com/rimelabs/rime-sdk/blob/main/examples/typescript/tts/play.ts).
-Both accept the same SDK text stream; device dependencies stay in the examples.
+Your application owns playback. Start with the complete WAV example in the
+[package quick start](../README.md#tts-save-speech).
 
 ## Stream incoming text
 
@@ -21,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.8",
+  "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"
@@ -49,5 +44,6 @@
     "prettier": "3.9.8",
     "typescript": "^5.9.0",
     "yaml": "^2.9.1"
-  }
+  },
+  "homepage": "https://docs.rime.ai/"
 }