@streamoji/aitwin 0.6.2 → 0.6.4

package/dist/index.d.ts

@@ -49,7 +49,9 @@ export declare type AiTwinHandle = {
     /** Mute/unmute bot audio output (TTS + voice). */
     setMuted: (muted: boolean) => void;
     isMuted: () => boolean;
-    /** Persona / knowledge context id from getAiTwin (for /avatarReply). */
+    /** Brain id from getAiTwin (for /avatarReply and /ws/voice). */
+    getBrainId: () => string | null;
+    /** @deprecated Use `getBrainId`. */
     getPersonaId: () => string | null;
 };
 
@@ -89,6 +91,11 @@ export declare type AiTwinProps = {
      * `ttsEngineId:voiceId` (e.g. `visemetts:eve`).
      */
     voiceId?: string;
+    /**
+     * Default TTS language for `speakText()` and voice `connect()`.
+     * Uniform code for visemetts and Cartesia (`en`, `es-MX`, `auto`, …).
+     */
+    language?: TtsLanguage;
     /** API speakingRate (default: 0.85). */
     speakingRate?: number;
     className?: string;
@@ -148,7 +155,9 @@ export declare type AiTwinRecord = {
     voiceId?: string;
     /** Bearer JWT for TTS / voice WebSocket (same as `getAuthToken`). */
     authToken?: string;
-    /** When set, passed as `personaId` on voice WebSocket connect. */
+    /** Redis brain id. Passed as `brainId` on `/ws/voice` and `/avatarReply`. */
+    brainId?: string;
+    /** @deprecated Use `brainId`. */
     knowledgeContextId?: string;
     gender?: string;
     createdAt?: string;
@@ -205,6 +214,11 @@ export declare type AiTwinWidgetProps = {
     apiBase?: string;
     /** TTS voice id override. */
     voiceId?: string;
+    /**
+     * Default TTS language for `speakText()` and voice `connect()`.
+     * Uniform code for visemetts and Cartesia (`en`, `es-MX`, `auto`, …).
+     */
+    language?: TtsLanguage;
     /** API speakingRate (default 0.85). */
     speakingRate?: number;
     /**
@@ -218,9 +232,11 @@ export declare type AiTwinWidgetProps = {
      */
     float?: boolean;
     /**
-     * Persona / knowledge context id for /avatarReply (Text mode).
-     * When omitted, uses getAiTwin `knowledgeContextId` if available.
+     * Brain id for /avatarReply (Text mode).
+     * When omitted, uses getAiTwin `brainId` if available.
      */
+    brainId?: string;
+    /** @deprecated Use `brainId`. */
     personaId?: string;
     /**
      * Optional poster shown (blurred) on `<AiTwin>` while sil/atlas/idle assets load.
@@ -281,6 +297,11 @@ export declare type AvatarTtsSpeakOptions = {
     speakingRate?: number;
     /** Overrides controller default for this request. */
     ttsEngineId?: TtsEngineId;
+    /**
+     * Uniform TTS language code (`en`, `es-MX`, `auto`, …).
+     * Sent as `language` on `/avatar_ttsWithPoses`.
+     */
+    language?: TtsLanguage;
 };
 
 /** Pair transitions for playback, including sil→first and last→sil bookends. */
@@ -307,6 +328,8 @@ export declare function createRealtimeVoiceLipsyncController(onStatus: (status:
 
 export declare const DEFAULT_TTS_ENGINE_ID: TtsEngineId;
 
+export declare const DEFAULT_TTS_LANGUAGE: TtsLanguage;
+
 export declare const EMOTION_TO_EYEBROW: Record<ExpressionEmotion, number>;
 
 export declare function emotionToEyebrow(emotion: ExpressionEmotion): number;
@@ -329,6 +352,8 @@ export declare type FetchAvatarReplyOptions = {
     message: string;
     authToken: string;
     apiBase?: string;
+    brainId?: string;
+    /** @deprecated Use `brainId`. */
     personaId?: string;
     history?: AvatarReplyMessage[];
     /** Called as soon as spokenText arrives on the SSE stream. */
@@ -398,6 +423,10 @@ export declare function getAiTwinSourceUrl(faceId: string, cdnBase?: string, ext
 /** Public CDN thumbnail for custom-faces/{faceId}/ (same id as pipeline avatarId). */
 export declare function getAiTwinThumbnailUrl(faceId: string, cdnBase?: string): string;
 
+export declare function isTtsLanguageCode(raw: string): raw is TtsLanguage;
+
+export declare function isTtsLanguageSupported(engineId: TtsEngineId, language: string): boolean;
+
 export declare function listSkippedVisemeEntries(queue: VisemeQueueItem[]): SkippedVisemeEntry[];
 
 /** Visemes removed by compaction (for debug). */
@@ -410,6 +439,9 @@ export declare function normalizeOculusViseme(symbol: string | null | undefined)
 
 export declare function normalizeStreamEmotion(raw: string | undefined | null, fallback?: ExpressionEmotion): ExpressionEmotion;
 
+/** Trimmed language code, or undefined when empty. */
+export declare function normalizeTtsLanguage(raw?: string | null): TtsLanguage | undefined;
+
 /** Oculus viseme ids for Talking Lady stills and pair transitions (15 standard). */
 export declare const OCULUS_VISEME_IDS: readonly ["aa", "CH", "DD", "E", "FF", "I", "O", "PP", "RR", "SS", "TH", "U", "kk", "nn", "sil"];
 
@@ -482,6 +514,9 @@ export declare type RealtimeVoiceOptions = VoiceConnectOptions & {
 /** Resolve optional `avatarId` / `faceId` props (same R2 custom-faces hex id). */
 export declare function resolveDirectFaceId(avatarId?: string, faceId?: string): string | undefined;
 
+/** Canonical `brainId`, then legacy `knowledgeContextId`, then extra fallbacks. */
+export declare function resolveTwinBrainId(source?: TwinBrainFields | string | null, ...fallbacks: Array<string | null | undefined>): string | undefined;
+
 /** Pick the active viseme at playback offset (latest vtime wins on overlap). */
 export declare function resolveVisemeAtTime(queue: VisemeQueueItem[], elapsedMs: number): string;
 
@@ -538,8 +573,265 @@ export declare const TTS_ENGINE_INWORLD = "eng_d4e8f3a2";
 /** streamoji-ai-avatar viseme TTS (`POST /avatar_ttsWithPoses`). */
 export declare const TTS_ENGINE_VISEMETTS = "visemetts";
 
+/**
+ * Uniform TTS language codes for visemetts and Cartesia (`eng_c9b1e6d4`).
+ * Passed as `language` on `/avatar_ttsWithPoses` and `/ws/voice`.
+ */
+export declare const TTS_LANGUAGE_CATALOG: readonly [{
+    readonly code: "en";
+    readonly label: "English";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "es";
+    readonly label: "Spanish";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "es-MX";
+    readonly label: "Spanish (Mexico)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "es-ES";
+    readonly label: "Spanish (Spain)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "pt";
+    readonly label: "Portuguese";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "pt-BR";
+    readonly label: "Portuguese (Brazil)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "pt-PT";
+    readonly label: "Portuguese (Portugal)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "fr";
+    readonly label: "French";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "de";
+    readonly label: "German";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "it";
+    readonly label: "Italian";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "zh";
+    readonly label: "Chinese";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ja";
+    readonly label: "Japanese";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "hi";
+    readonly label: "Hindi";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ko";
+    readonly label: "Korean";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ru";
+    readonly label: "Russian";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "tr";
+    readonly label: "Turkish";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "id";
+    readonly label: "Indonesian";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ar";
+    readonly label: "Arabic";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ar-EG";
+    readonly label: "Arabic (Egypt)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "ar-AE";
+    readonly label: "Arabic (UAE)";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "vi";
+    readonly label: "Vietnamese";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "bn";
+    readonly label: "Bengali";
+    readonly visemetts: true;
+    readonly cartesia: true;
+}, {
+    readonly code: "auto";
+    readonly label: "Auto-detect";
+    readonly visemetts: true;
+    readonly cartesia: false;
+}, {
+    readonly code: "nl";
+    readonly label: "Dutch";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "pl";
+    readonly label: "Polish";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "sv";
+    readonly label: "Swedish";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "tl";
+    readonly label: "Tagalog";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "bg";
+    readonly label: "Bulgarian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "ro";
+    readonly label: "Romanian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "cs";
+    readonly label: "Czech";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "el";
+    readonly label: "Greek";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "fi";
+    readonly label: "Finnish";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "hr";
+    readonly label: "Croatian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "ms";
+    readonly label: "Malay";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "sk";
+    readonly label: "Slovak";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "da";
+    readonly label: "Danish";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "ta";
+    readonly label: "Tamil";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "uk";
+    readonly label: "Ukrainian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "hu";
+    readonly label: "Hungarian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "no";
+    readonly label: "Norwegian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "th";
+    readonly label: "Thai";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "he";
+    readonly label: "Hebrew";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "ka";
+    readonly label: "Georgian";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "te";
+    readonly label: "Telugu";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "gu";
+    readonly label: "Gujarati";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "kn";
+    readonly label: "Kannada";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "ml";
+    readonly label: "Malayalam";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "mr";
+    readonly label: "Marathi";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}, {
+    readonly code: "pa";
+    readonly label: "Punjabi";
+    readonly visemetts: false;
+    readonly cartesia: true;
+}];
+
+export declare const TTS_LANGUAGE_CODES: readonly TtsLanguage[];
+
 export declare type TtsEngineId = typeof TTS_ENGINE_GOOGLE | typeof TTS_ENGINE_INWORLD | typeof TTS_ENGINE_CARTESIA | typeof TTS_ENGINE_VISEMETTS;
 
+export declare type TtsLanguage = (typeof TTS_LANGUAGE_CATALOG)[number]["code"];
+
+export declare function ttsLanguagesForEngine(engineId: TtsEngineId): TtsLanguage[];
+
 /** Runtime face bundle URLs (R2 custom-faces or local /twins/…). */
 export declare type TwinAssetUrls = {
     /** Plain assets: sil.png, idle.mp4, atlas.json */
@@ -549,6 +841,12 @@ export declare type TwinAssetUrls = {
     encrypted: boolean;
 };
 
+declare type TwinBrainFields = {
+    brainId?: string | null;
+    /** @deprecated Use `brainId`. Older getAiTwin responses still send this. */
+    knowledgeContextId?: string | null;
+};
+
 export declare const VISEME_IDS: readonly ["aa", "E", "I", "O", "U", "PP", "FF", "DD", "SS", "TH", "CH", "RR", "kk", "nn"];
 
 /** Minimum gap (ms) between consecutive vtimes to keep a skippable viseme. */
@@ -582,7 +880,14 @@ export declare type VoiceConnectOptions = {
     ttsEngineId?: TtsEngineId;
     /** Cartesia voice UUID, or visemetts name (e.g. `eve`). */
     voiceId?: string;
-    /** Persona / knowledge context id (from getAiTwin `knowledgeContextId`). */
+    /**
+     * Uniform TTS language code (`en`, `es-MX`, `auto`, …).
+     * Sent as `language` on `/ws/voice` and redirected `/avatar_ttsWithPoses` calls.
+     */
+    language?: TtsLanguage;
+    /** Redis brain id (from getAiTwin `brainId`). Sent as `brainId` on `/ws/voice`. */
+    brainId?: string;
+    /** @deprecated Use `brainId`. */
     personaId?: string;
     speakingRate?: number;
     /** Default true — server streams TTS + avatar messages. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamoji/aitwin",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Embeddable React AI twin face with TTS lipsync",
   "type": "module",
   "main": "./dist/aitwin.cjs",