@streamoji/aitwin 0.6.1 → 0.6.3

package/README.md

@@ -96,8 +96,9 @@ Provide **`id`** (cloud twin), **`avatarId`/`faceId`** (R2 custom face), or **`a
 | `faceId` | Alias for `avatarId` (same CDN path) |
 | `assets` | `{ twinBase, binBase, encrypted }` — skip getAiTwin (lab / custom CDN) |
 | `authToken` | Bearer for TTS + encrypted assets; omitted → dev `getAuthToken` |
-| `ttsEngineId` | TTS engine when using `assets` (default Cartesia) |
-| `voiceId` | Override TTS voice |
+| `ttsEngineId` | TTS engine (default Cartesia). Optional if `voiceId` is packed as `engine:voice` |
+| `voiceId` | Voice id, or packed `ttsEngineId:voiceId` (e.g. `visemetts:eve`) |
+| `language` | Default TTS language for `speakText()` and `connect()` (`en`, `es-MX`, `auto`, …) |
 | `speakingRate` | Default `0.85` |
 | `idleHandoffHoldMs` | Milliseconds to hold still sil after speech before resuming the idle video loop (default `200`) |
 | `showErrorOverlay` | Canvas error overlay (default `true`) |
@@ -147,11 +148,25 @@ After speech ends, the twin returns to a still closed-mouth frame before the idl
 
 Applies to both `speakText()` and voice `connect()` playback.
 
+#### Language
+
+`language` is a uniform code for visemetts and Cartesia. Pass it on `<AiTwin>`, `speakText()`, or `connect()`. Per-call options override the prop. Omitted → the API default.
+
+```tsx
+await twinRef.current?.speakText("Hola, ¿cómo estás?", {
+  ttsEngineId: "visemetts",
+  voiceId: "eve",
+  language: "es-MX",
+});
+```
+
+`auto` is visemetts-only. Cartesia also accepts extra codes (`nl`, `pl`, `th`, …). See `TTS_LANGUAGE_CATALOG` / `ttsLanguagesForEngine()`.
+
 ### Ref handle
 
 | Method | Description |
 |--------|-------------|
-| `speakText(text, options?)` | SSE TTS + lipsync; optional per-call `tts` / `voiceId` |
+| `speakText(text, options?)` | SSE TTS + lipsync; optional per-call `ttsEngineId` / `voiceId` / `language` |
 | `connect(options)` | Mic + WebSocket voice session (`/ws/voice`) |
 | `disconnect()` | End voice session |
 | `isConnected()` | Whether voice WebSocket is active |
@@ -195,6 +210,7 @@ function VoiceDemo() {
       authToken: authJwt,
       voiceId: optionalCartesiaUuid,
       speakingRate: 0.85,
+      language: "es-MX",
     });
   };
 
@@ -220,7 +236,9 @@ WebSocket URL: `wss://<api-host>/ws/voice?<query>`. The SDK builds it from `conn
 |-------------|----------|--------|
 | `authToken` | Yes | Same JWT as SSE `Authorization: Bearer` (`client_…` from `getAuthToken`) |
 | `tenant` | Yes | Always `aiTwin` |
-| `voiceId` | No | Cartesia UUID override (from getAiTwin or `connect({ voiceId })`) |
+| `voiceId` | No | Cartesia UUID, visemetts name (`eve`), or packed `engine:voice` |
+| `ttsEngineId` | No | `visemetts` or Cartesia id; also parsed from packed `voiceId` |
+| `language` | No | Uniform TTS language (`en`, `es-MX`, `auto`, …) for visemetts and Cartesia |
 | `personaId` | No | getAiTwin `knowledgeContextId` when present |
 | `speaking_rate` | No | `0.5`–`1.5`, default `0.85` |
 | `tts_stream` | No | Default `true` (server TTS + `avatar_audio_chunk`) |