@streamoji/aitwin 0.6.1 → 0.6.3

package/dist/index.d.ts

@@ -82,10 +82,18 @@ export declare type AiTwinProps = {
     authToken?: string;
     /** Avatar API base (TTS, session-value, voice). Default: package `DEFAULT_API_BASE`. */
     apiBase?: string;
-    /** TTS engine when using `assets` or `avatarId`/`faceId` (default: Cartesia). */
+    /** TTS engine when using `assets` or `avatarId`/`faceId` (default: Cartesia). Optional if `voiceId` is packed as `engine:voice`. */
     ttsEngineId?: TtsEngineId;
-    /** TTS voice id override (engine-specific). */
+    /**
+     * TTS voice id. May be a bare id (`eve`, Cartesia UUID) or packed
+     * `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;
@@ -202,6 +210,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;
     /**
@@ -278,6 +291,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. */
@@ -304,6 +322,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;
@@ -395,6 +415,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). */
@@ -407,9 +431,21 @@ 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"];
 
+/**
+ * `voiceId` may be a bare id (`eve`) or packed `engine:voice` (`visemetts:eve`).
+ * Cartesia UUIDs have no colon, so they stay a plain voice id.
+ */
+export declare function parsePackedVoiceId(raw?: string): {
+    ttsEngineId?: TtsEngineId;
+    voiceId?: string;
+};
+
 export declare const PLAYBACK_SAMPLE_RATE = 16000;
 
 declare type RawVisemeTransition = {
@@ -510,6 +546,12 @@ export declare const SPEAKING_RATE_MAX = 1.5;
 
 export declare const SPEAKING_RATE_MIN = 0.5;
 
+/** Merge explicit `ttsEngineId` with a possibly packed `voiceId`. Packed engine wins only if engine is omitted. */
+export declare function splitVoiceIdSpec(ttsEngineId?: TtsEngineId, voiceId?: string): {
+    ttsEngineId?: TtsEngineId;
+    voiceId?: string;
+};
+
 export declare const TTS_ENGINE_CARTESIA = "eng_c9b1e6d4";
 
 /** Opaque TTS engine ids — must match backend TTS_ENGINE_MAP in main.py. */
@@ -520,8 +562,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 */
@@ -564,6 +863,11 @@ export declare type VoiceConnectOptions = {
     ttsEngineId?: TtsEngineId;
     /** Cartesia voice UUID, or visemetts name (e.g. `eve`). */
     voiceId?: string;
+    /**
+     * Uniform TTS language code (`en`, `es-MX`, `auto`, …).
+     * Sent as `language` on `/ws/voice` and redirected `/avatar_ttsWithPoses` calls.
+     */
+    language?: TtsLanguage;
     /** Persona / knowledge context id (from getAiTwin `knowledgeContextId`). */
     personaId?: string;
     speakingRate?: number;

package/package.json

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