@flamai/finesse 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## 0.1.1 (unreleased)
+## 0.1.2
+
+- `output_format: "mulaw"` (raw G.711 µ-law) for telephony, with `sample_rate: 8000`, on
+  `speech` and realtime contexts. 8 kHz is now produced as asked; the README shows Twilio Media
+  Streams.
+
+## 0.1.1
 
 - Published on npm as `@flamai/finesse` (was private, installed from GitHub).
 - Token clients (`accessToken`) retry only `429` and connections that never opened. The

package/README.md

@@ -5,10 +5,12 @@
 </picture>
 
 <p>
+  <a href="https://www.npmjs.com/package/@flamai/finesse"><img alt="npm version" src="https://img.shields.io/npm/v/@flamai/finesse?style=flat&labelColor=14151A&color=2547F0"></a>
   <img alt="Node 18+" src="https://img.shields.io/badge/node-18%2B-14151A?style=flat&labelColor=14151A&color=2547F0">
   <img alt="Bun and Deno" src="https://img.shields.io/badge/also-Bun%20%C2%B7%20Deno-14151A?style=flat&labelColor=14151A&color=2547F0">
   <img alt="TypeScript types included" src="https://img.shields.io/badge/types-included-14151A?style=flat&labelColor=14151A&color=2547F0">
   <img alt="Status: beta" src="https://img.shields.io/badge/status-beta-14151A?style=flat&labelColor=14151A&color=63656A">
+  <a href="./LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-14151A?style=flat&labelColor=14151A&color=63656A"></a>
 </p>
 
 # Finesse TypeScript SDK
@@ -47,6 +49,11 @@ and stream it in realtime to voice agents, with a few lines of code.
 - [Request IDs](#request-ids)
 - [Advanced](#advanced)
 - [Runtimes](#runtimes)
+- [Requirements](#requirements)
+- [Versioning](#versioning)
+- [Getting help](#getting-help)
+- [Security](#security)
+- [Contributing](#contributing)
 
 ## Installation
 
@@ -56,8 +63,14 @@ Realtime in Node also needs the `ws` package:
 npm install @flamai/finesse ws
 # or
 pnpm add @flamai/finesse ws
+# or
+yarn add @flamai/finesse ws
+# or
+bun add @flamai/finesse
 ```
 
+`ws` is only needed for realtime in Node. Bun, Deno and browsers have a built-in `WebSocket`.
+
 ## Get an API key
 
 1. Sign in to the [Finesse dashboard](https://finesse.flamapp.ai/dashboard).
@@ -181,7 +194,7 @@ const audio = await client.speech.create({
   voice_id: voice.id,
   text: "The quick brown fox jumps over the lazy dog.",
   language: "en", // optional; defaults to the voice's language
-  output_format: "wav", // default; or raw PCM: "s16le", "s24le", "s32le", "f32le", "f64le"
+  output_format: "wav", // default; or raw PCM: "s16le", "s24le", "s32le", "f32le", "f64le", or "mulaw"
   num_step: 32, // optional; 1-32, default 32; fewer steps is faster
 });
 
@@ -331,11 +344,26 @@ outside `voice_ids` throws `PermissionDeniedError` with `code === "voice_not_all
 | `s16le`          | Raw PCM, 16-bit signed little-endian | `speech.stream`, realtime |
 | `s24le`, `s32le` | Raw PCM, 24- or 32-bit signed        |                           |
 | `f32le`, `f64le` | Raw PCM, 32- or 64-bit float         |                           |
+| `mulaw`          | Raw G.711 µ-law, for telephony       | needs `sample_rate: 8000` |
 | `opus`           | Opus                                 | realtime only             |
 
-All audio is mono. The engine's native rate is 24 kHz. You can ask for a higher `sample_rate`,
-but lower ones still come back at 24 kHz, so always read the actual rate from
-`audio.sampleRate`, `stream.sampleRate` or the `task_started` event.
+All audio is mono. The engine's native rate is 24 kHz. You can ask for a higher `sample_rate`, or
+for 8000 (telephony); other lower rates still come back at 24 kHz, so always read the actual rate
+from `audio.sampleRate`, `stream.sampleRate` or the `task_started` event.
+
+### Phone calls (Twilio)
+
+Twilio Media Streams play 8 kHz µ-law. Ask for exactly that and send each chunk as the media
+payload, base64-encoded; there is no WAV header to strip and nothing to resample:
+
+```ts
+const ctx = rt.context({ voice_id: voiceId, output_format: "mulaw", sample_rate: 8000 });
+
+for await (const audio of ctx.audio()) {
+  const payload = Buffer.from(audio).toString("base64");
+  twilioWs.send(JSON.stringify({ event: "media", streamSid, media: { payload } }));
+}
+```
 
 ## Handling errors
 
@@ -486,22 +514,12 @@ const quick = client.withOptions({ timeout: 10_000, maxRetries: 0 });
 await quick.voices.get(voiceId);
 ```
 
-### Environments
-
-The client talks to production by default. Point it elsewhere with `baseURL` or
-`FINESSE_BASE_URL`:
-
-```ts
-const client = new Finesse({ baseURL: "https://finesse-proxy.example.com" });
-```
-
 ### Configuration
 
 | Option                    | Environment variable | Default                               |
 | ------------------------- | -------------------- | ------------------------------------- |
 | `apiKey`                  | `FINESSE_API_KEY`    | required, unless `accessToken`        |
 | `accessToken`             |                      | none (a short-lived `fin_tok_` token) |
-| `baseURL`                 | `FINESSE_BASE_URL`   | `https://fi.production.flamapis.com`  |
 | `timeout`                 |                      | 120 000 ms                            |
 | `maxRetries`              |                      | 2                                     |
 | `defaultHeaders`          |                      | none                                  |
@@ -510,6 +528,8 @@ const client = new Finesse({ baseURL: "https://finesse-proxy.example.com" });
 | `logLevel`                | `FINESSE_LOG`        | `"off"`                               |
 | `logger`                  |                      | `console`                             |
 
+An option passed to `new Finesse({...})` always wins over its environment variable.
+
 ### Custom fetch
 
 Pass your own `fetch` for proxies, logging or tests:
@@ -542,11 +562,28 @@ Browsers can't keep an API key secret, so a client holding a key refuses to run
 deprecated URL parameter, because browsers can't set WebSocket headers (as does Deno before
 2.5), and logs a warning once.
 
+## TypeScript types
+
+Every request and response type is exported, so you can type your own code against the API:
+
+```ts
+import type { Voice } from "@flamai/finesse";
+
+function label(voice: Voice) {
+  return `${voice.name} (${voice.id})`;
+}
+```
+
 ## Examples
 
 Runnable scripts are in [`examples/`](./examples): [`speak.ts`](./examples/speak.ts) and
 [`realtime.ts`](./examples/realtime.ts).
 
+## Requirements
+
+- Node 18 or later, Bun, Deno, or a modern browser (see [Runtimes](#runtimes)).
+- TypeScript 4.7 or later, if you use TypeScript.
+
 ## Versioning
 
 The SDK follows [semantic versioning](https://semver.org). Before 1.0, minor versions may
@@ -556,6 +593,18 @@ include breaking changes; they are listed in the [changelog](./CHANGELOG.md).
 import { VERSION } from "@flamai/finesse";
 ```
 
+## Getting help
+
+- [Documentation](https://docs.finesse.flamapp.ai) for guides and the API reference.
+- [GitHub issues](https://github.com/homingos/finesse-node/issues) for bugs and feature requests
+  in this SDK. Include the `requestId` from the error (see [Request IDs](#request-ids)) when
+  a request failed.
+
+## Security
+
+Please don't report security problems in a public issue. See [SECURITY.md](./SECURITY.md) for
+how to report one privately.
+
 ## Contributing
 
 ```sh

package/dist/index.cjs

@@ -225,7 +225,7 @@ function numberField(body2, key) {
 }
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.2";
 
 // src/core.ts
 var DEFAULT_BASE_URL = "https://fi.production.flamapis.com";