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

package/CHANGELOG.md

@@ -1,16 +1,28 @@
 # Changelog
 
-## 0.1.0-alpha.1
+## [0.1.0-alpha.3](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.2...typescript-v0.1.0-alpha.3) (2026-09-28)
+
+
+### Bug Fixes
+
+* match ITU mu-law quantization for negative PCM ([#10](https://github.com/rimelabs/rime-sdk/issues/10)) ([e03dcb3](https://github.com/rimelabs/rime-sdk/commit/e03dcb3424cab5a9b7d6bc9b1c37b3b72540e3a6))
 
-Initial local alpha for Node.js 22+ and ESM. Adds Coda synthesis, discovery,
-API-key authentication, sentence buffering, PCM and mu-law profiles, typed errors,
-deadlines, and cancellation. The Themis wire contract is assumed and needs
-deployment validation.
+## [0.1.0-alpha.2](https://github.com/rimelabs/rime-sdk/compare/typescript-v0.1.0-alpha.1...typescript-v0.1.0-alpha.2) (2026-09-28)
+
+- Add `model: "mistv3"` for Mist v3 speech, voice discovery, and language discovery.
+  The model selects its standard endpoint and default voice. Custom endpoints
+  retain the model's default voice. Coda remains the default model.
+- Reorganize the usage guide around examples and option tables. Clarify audio
+  output, timeout defaults, error handling, and cancellation.
+
+## 0.1.0-alpha.1
 
-Review fixes preserve zero-width spaces and BOM characters during sentence
-mapping, distinguish token-exchange rate limits and service failures from
-rejected credentials, and cancel failed HTTP response bodies.
+Initial public alpha for Node.js 22 and later, with ESM and TypeScript types:
 
-Further review fixes stop pending reads after cancellation, preserve errors from
-responses without audio metadata, handle responses with only trailers, and
-collect discovery request IDs from headers and trailers.
+- Stream Coda speech from a string or an async text source with API-key authentication.
+- Discover voices and languages, and select a custom deployment endpoint.
+- Receive raw 24 kHz PCM or 8 kHz mu-law audio with sentence buffering.
+- Set operation deadlines, cancel streams, and handle typed errors with request IDs.
+- Preserve original text during sentence detection, including zero-width spaces
+  and byte order marks.
+- Report server errors even when no audio metadata arrives or input writes fail.

package/README.md

@@ -1,23 +1,28 @@
 # Rime SDK for Node.js
 
-Requires Node.js 22 or later. The package uses ESM and includes TypeScript types.
-Browser use is not supported. This is an alpha release.
-Install it from npm using the `next` tag:
+Stream speech from a string or async text source with Rime.
+
+## Install
+
+Requires Node.js 22 or later. This alpha package uses ESM and includes TypeScript
+types. Browser use is not supported.
 
 ```sh
 npm install @rimelabs/sdk@next
+export RIME_API_KEY="your-api-key"
 ```
 
+## Quick start
+
+Save this as `speech.mjs` and run `node speech.mjs`:
+
 ```javascript
 import { writeFile } from "node:fs/promises";
-import { Rime, AudioFormat } from "@rimelabs/sdk";
+import { Rime } from "@rimelabs/sdk";
 
-const client = new Rime({ apiKey: "your-api-key" });
+const client = new Rime();
 try {
-  const audio = client.tts.stream("Hello. This is Rime.", {
-    voice: "clementine",
-    audioFormat: AudioFormat.PCM_24000,
-  });
+  const audio = client.tts.stream("Hello. This is Rime.");
   await writeFile("speech.pcm", audio);
   console.log(audio.requestId);
 } finally {
@@ -25,69 +30,137 @@ try {
 }
 ```
 
-Omit `apiKey` to read `RIME_API_KEY`. The default model is `coda`.
-The SDK selects its standard endpoint. Only `coda` is currently supported.
-For a custom deployment of that model, set `endpoint`:
+Output is raw mono 24 kHz signed 16-bit little-endian PCM. Configure your player
+for this format; there is no WAV header.
+
+## Stream incoming text
+
+Add this async text source before the client declaration in the quick start:
 
 ```javascript
-const client = new Rime({ model: "coda", endpoint: "coda.api.customer-name.rime.ai" });
+async function* text() {
+  yield "Hello. ";
+  yield "This text arrives in separate chunks.";
+}
 ```
 
-Use a hostname with an optional port, such as `host:8443`. Omit the scheme and path.
-Connections always use TLS; the default port is `443`.
-The endpoint applies to speech, voices, and languages for this client.
+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.
 
-The default voice is `clementine`; the default language is `en`.
-`tts.stream()` also accepts `AsyncIterable<string>`. Do not await the factory.
-The first iterator read starts work. A `for await` loop exit cancels the stream.
-Use `await audio.cancel()` in a `finally` block if you read the iterator manually.
+## Configuration
 
-`await client.voices.list({ language: "en" })` returns voice names.
-`await client.languages.list()` returns language codes.
-Both accept an options object with `timeout` in seconds.
+Select Mist v3 with `new Rime({ model: "mistv3" })`. Mist v1 and v2 are not supported.
 
-`new Rime({ timeout: 30 })` sets an overall timeout. An operation can replace
-it with `{ timeout: 10 }` or disable it with `{ timeout: null }`.
-An omitted or `undefined` option inherits the client setting. Internal connection
-and progress limits still apply. An overall timeout continues during caller pauses.
+| Model | Standard endpoint | Default voice |
+| --- | --- | --- |
+| `coda` | `coda.api.rime.ai:443` | `clementine` |
+| `mistv3` | `mist.api.rime.ai:443` | `astra` |
 
-`audio.format` is a read-only `AudioFormat` with `encoding`, `sampleRate`, and
-`channels`. `PCM_24000` is raw signed 16-bit little-endian mono PCM at 24 kHz.
-`MULAW_8000` is raw mono G.711 mu-law at 8 kHz. Neither includes a file header.
-The iterator yields `Uint8Array` chunks with complete sample frames.
-Chunk sizes are not fixed.
+### Client options
 
-`await audio.cancel()` cancels one operation. `await client.close()` cancels all
-client work. Both are idempotent. Both objects support `Symbol.asyncDispose`.
-Normal iterator completion means that the final service status was successful.
-Partial audio can precede a typed error. Synthesis is never replayed.
+| `new Rime({ ... })` option | Default | Meaning |
+| --- | --- | --- |
+| `apiKey` | `RIME_API_KEY` | API key; an explicit value overrides the environment |
+| `model` | `"coda"` | Model for speech and discovery |
+| `endpoint` | Model's standard endpoint | Custom hostname and optional port for speech and discovery |
+| `timeout` | No overall deadline | Positive seconds; `null` disables the overall deadline |
 
-Catch `RimeError` or one of `RimeAuthenticationError`, `RimePermissionError`,
-`RimeInputError`, `RimeResourceLimitError`, `RimeUnavailableError`,
-`RimeTimeoutError`, `RimeAudioFormatError`, `RimeCancelledError`, or
-`RimeStreamError`. Errors expose a message and optional `requestId`.
-Cancellation cannot stop application code that waits on an unrelated promise.
-The SDK stops its RPC and limits how long it waits for source cleanup.
+Authentication uses bearer tokens over TLS. The SDK does not load `.env` files.
 
-The SDK sends the API key as a bearer token over TLS.
+Custom deployments use `new Rime({ model: "coda", endpoint: "host:8443" })`.
+Omit the scheme and path. TLS is required; the default port is `443`.
+Model defaults still apply.
 
-## Development for contributors
+### Synthesis options
 
-These instructions require access to the source repository.
-Run the commands from its `typescript/` directory:
+Pass these options to `client.tts.stream(text, { ... })`:
 
-```sh
-npm ci
-npm run check
-npm run lint
-npm test
-npm pack
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `voice` | Model's default voice | Voice name from `client.voices.list()` |
+| `language` | `"en"` | Language code |
+| `audioFormat` | `AudioFormat.PCM_24000` | Output profile, imported from `@rimelabs/sdk` |
+| `timeout` | Client setting | Seconds; pass `null` to disable the overall deadline |
+
+### Audio formats
+
+Both profiles return raw audio without a file header.
+
+| `AudioFormat` profile | Encoding | Sample rate | Channels |
+| --- | --- | --- | --- |
+| `PCM_24000` | Signed 16-bit little-endian PCM | 24 kHz | Mono |
+| `MULAW_8000` | G.711 mu-law | 8 kHz | Mono |
+
+Chunks are `Uint8Array` values with complete sample frames; sizes vary. Inspect the
+read-only `audio.format.encoding`, `audio.format.sampleRate`, and `audio.format.channels`.
+
+### Timeouts
+
+An overall deadline includes pauses between reads. Disabling it leaves internal
+connection and progress limits active. Discovery allows at most 10 seconds;
+a shorter supplied timeout takes precedence. Omit an operation's `timeout` or
+pass `undefined` to inherit the client setting.
+
+## Discover voices and languages
+
+List voices and languages inside the quick start's `try` block:
+
+```javascript
+const voices = await client.voices.list({ language: "en" });
+const languages = await client.languages.list();
+console.log(voices, languages);
+```
+
+Both return string arrays and accept `timeout`. Omit `language` to disable filtering.
+
+## Errors and cancellation
+
+Report SDK errors and request IDs while closing the client on failure:
+
+```javascript
+import { writeFile } from "node:fs/promises";
+import { Rime, RimeError } from "@rimelabs/sdk";
+
+let client;
+try {
+  client = new Rime();
+  await writeFile("speech.pcm", client.tts.stream("Hello. This is Rime."));
+} catch (error) {
+  if (error instanceof RimeError) {
+    console.error(`Speech failed: ${error.message}; requestId=${error.requestId}`);
+  }
+  throw error;
+} finally {
+  await client?.close();
+}
 ```
 
-The package includes a pinned Microsoft BlingFire WASM binary and its license.
-It does not download code at runtime. See [vendor provenance](vendor/README.md).
+Each SDK error inherits from `RimeError`:
+
+| Error | Meaning |
+| --- | --- |
+| `RimeAuthenticationError` | Missing or rejected credentials |
+| `RimePermissionError` | Access denied |
+| `RimeInputError` | Invalid input or client use |
+| `RimeResourceLimitError` | Service resource limit reached |
+| `RimeUnavailableError` | Service unavailable |
+| `RimeTimeoutError` | Overall or internal deadline reached |
+| `RimeAudioFormatError` | Unsupported or unexpected audio format |
+| `RimeCancelledError` | Operation cancelled |
+| `RimeStreamError` | Other stream or transport failure |
+
+Partial audio can arrive before an error. Output is complete only after successful
+iteration. Synthesis is not retried automatically.
+
+Keep cleanup when stopping early. A `for await` loop exit cancels the stream.
+For manual reads, call `await audio.cancel()` in `finally`. `await client.close()`
+stops all client work. Both calls are safe to repeat; both objects support
+`Symbol.asyncDispose`. Cancellation stops the RPC and limits cleanup time, but
+cannot force your text source to finish an unrelated promise.
 
 ## License
 
-The SDK is licensed under the [MIT License](LICENSE).
-BlingFire retains its [upstream license](vendor/LICENSE.blingfire).
+The SDK uses the [MIT License](LICENSE). BlingFire retains its
+[upstream license](vendor/LICENSE.blingfire). The package includes its WASM runtime
+and downloads no code or models at runtime. See [vendor provenance](vendor/README.md).

package/dist/audio.js

@@ -20,7 +20,8 @@ const total = raw.reduce((a, b) => a + b, 0);
 const coefficients = raw.map((x) => x / total);
 function mulaw(sample) {
     sample = Math.max(-32768, Math.min(32767, sample));
-    const sign = sample < 0 ? 128 : 0, magnitude = Math.min(Math.abs(sample), 32635) + 132;
+    // G.711 uses one's complement for negative PCM before quantization.
+    const sign = sample < 0 ? 128 : 0, magnitude = Math.min(sample < 0 ? ~sample : sample, 32635) + 132;
     const exponent = Math.max(0, Math.floor(Math.log2(magnitude)) - 7);
     return ~(sign | (exponent << 4) | ((magnitude >> (exponent + 3)) & 15)) & 255;
 }

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { AudioFormat } from "./audio.js";
 import { AudioStream, type TextSource } from "./stream.js";
 export interface RimeOptions {
     apiKey?: string | null;
+    /** Select "coda" (default) or "mistv3" for speech and discovery. */
     model?: string;
     endpoint?: string | null;
     timeout?: number | null;

package/dist/client.js

@@ -58,7 +58,7 @@ export class Rime {
         else if (!text || typeof text[Symbol.asyncIterator] !== "function")
             throw new RimeInputError("text must be a string or an async iterable of strings");
         const voice = options.voice === undefined || options.voice === null
-            ? "clementine"
+            ? this.deployment.defaultVoice
             : nonempty(options.voice, "voice");
         const language = nonempty(options.language ?? "en", "language");
         const format = options.audioFormat ?? AudioFormat.PCM_24000;

package/dist/policy.d.ts

@@ -1,6 +1,7 @@
 export declare const policy: {
     target: string;
     audience: string;
+    defaultVoice: string;
     exchangeUrl: string;
     sentenceBytes: number;
     sourceChars: number;

package/dist/policy.js

@@ -1,7 +1,9 @@
 import { RimeInputError } from "./errors.js";
+const codaHostname = "coda.api.rime.ai";
 export const policy = {
-    target: "coda.api.rime.ai:443",
-    audience: "coda.api.rime.ai",
+    target: `${codaHostname}:443`,
+    audience: codaHostname,
+    defaultVoice: "clementine",
     exchangeUrl: "https://themis.api.rime.ai/v1/token",
     sentenceBytes: 65536,
     sourceChars: 1024,
@@ -16,11 +18,18 @@ export const policy = {
     cleanupTimeout: 2,
 };
 export function resolve(model, endpoint) {
-    // Add model defaults here only when its transport contract is supported.
-    if (model !== "coda")
-        throw new RimeInputError("This SDK supports model='coda'");
+    const deployment = { ...policy };
+    if (model === "mistv3") {
+        const hostname = "mist.api.rime.ai";
+        deployment.target = `${hostname}:443`;
+        deployment.audience = hostname;
+        deployment.defaultVoice = "astra";
+    }
+    else if (model !== "coda") {
+        throw new RimeInputError("model must be 'coda' or 'mistv3'");
+    }
     if (endpoint === undefined || endpoint === null)
-        return { ...policy };
+        return deployment;
     const error = "endpoint must be a hostname with an optional port (1-65535), without a scheme or path";
     if (typeof endpoint !== "string" || /\s/.test(endpoint))
         throw new RimeInputError(error);
@@ -35,7 +44,7 @@ export function resolve(model, endpoint) {
             (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)))
         throw new RimeInputError(error);
     return {
-        ...policy,
+        ...deployment,
         target: `${host.toLowerCase()}:${port === undefined ? 443 : Number(port)}`,
         audience: host.toLowerCase(),
     };

package/dist/transport.js

@@ -72,7 +72,7 @@ function nativeError(error, id) {
         const metadata = "metadata" in error ? error.metadata : null;
         return rpcError(error.code, id ?? (metadata instanceof grpc.Metadata ? requestId(metadata) : null));
     }
-    return new errors.RimeStreamError("Coda transport failed", id, {
+    return new errors.RimeStreamError("Rime transport failed", id, {
         cause: error,
     });
 }

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@rimelabs/sdk",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Rime streaming text-to-speech 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"