@streamoji/aitwin 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -6,6 +6,15 @@ export declare const AI_TWIN_THUMBNAIL_FILENAME = "thumbnail.webp";
 
 export declare const AiTwin: ForwardRefExoticComponent<AiTwinProps & RefAttributes<AiTwinHandle>>;
 
+export declare type AiTwinCaptionsOptions = {
+    /** CSS font-family, e.g. "Inter, sans-serif" or "Georgia, serif". */
+    fontFamily?: string;
+    /** CSS font-size, e.g. "1rem" or "18px". Default: clamp for readability. */
+    fontSize?: string;
+    /** Text color. Default: rgba(255,255,255,0.85). */
+    color?: string;
+};
+
 export declare type AiTwinHandle = {
     speakText: (text: string, options?: AvatarTtsSpeakOptions) => Promise<void>;
     stop: () => void;
@@ -37,6 +46,11 @@ export declare type AiTwinHandle = {
      * Null until a voice session (or TTS playback) has primed audio.
      */
     getVoiceStream: () => MediaStream | null;
+    /** Mute/unmute bot audio output (TTS + voice). */
+    setMuted: (muted: boolean) => void;
+    isMuted: () => boolean;
+    /** Persona / knowledge context id from getAiTwin (for /avatarReply). */
+    getPersonaId: () => string | null;
 };
 
 export declare class AiTwinNotFoundError extends Error {
@@ -110,6 +124,8 @@ export declare type AiTwinProps = {
      * atlas handling. Omit to use the device limit.
      */
     pixiMaxTextureSize?: number;
+    /** Plain subtitles during TTS/voice playback. */
+    captions?: boolean | AiTwinCaptionsOptions;
 };
 
 export declare type AiTwinRecord = {
@@ -135,6 +151,81 @@ export declare type AiTwinRenderVisemeOptions = {
 /** Basename for the original portrait stored on CDN (e.g. source.png). */
 export declare function aiTwinSourceFilename(extension?: string): string;
 
+/**
+ * React embed with optional Talk / Text / mute chrome (`showControls`)
+ * and bottom-right overlay (`float`). Same surface as the HTML UMD widget.
+ */
+export declare const AiTwinWidget: ForwardRefExoticComponent<AiTwinWidgetProps & RefAttributes<AiTwinWidgetHandle>>;
+
+/** Imperative API shared by React ref and HTML widget handle. */
+export declare type AiTwinWidgetHandle = {
+    speakText: (text: string, options?: AvatarTtsSpeakOptions) => Promise<void>;
+    connect: (options?: VoiceConnectOptions) => Promise<void>;
+    disconnect: () => Promise<void>;
+    stop: () => void;
+    isReady: () => boolean;
+    isConnected: () => boolean;
+    getTwin: () => AiTwinHandle | null;
+};
+
+/** HTML script-tag handle (React ref plus update/destroy). */
+export declare type AiTwinWidgetHtmlHandle = AiTwinWidgetHandle & {
+    destroy: () => void;
+    /** Merge options and re-render. */
+    update: (options: Partial<AiTwinWidgetProps>) => void;
+};
+
+/** @deprecated Use AiTwinWidgetProps */
+export declare type AiTwinWidgetInitOptions = AiTwinWidgetProps;
+
+/** Shared options for HTML `AiTwinWidget.init` and React `<AiTwinWidget />`. */
+export declare type AiTwinWidgetProps = {
+    /** Twin id for getAiTwin (e.g. `zoe`). */
+    id?: string;
+    /** 64-char hex R2 custom-faces id. */
+    avatarId?: string;
+    /** Alias for avatarId. */
+    faceId?: string;
+    /** Bearer token for TTS and encrypted assets; omit → SDK dev token. */
+    authToken?: string;
+    /** Avatar API base. Default: https://ai.aitwin.me */
+    apiBase?: string;
+    /** TTS voice id override. */
+    voiceId?: string;
+    /** API speakingRate (default 0.85). */
+    speakingRate?: number;
+    /**
+     * Show built-in Talk / Text / mute controls under the face.
+     * Default: false (face-only; host builds its own UI via the handle).
+     */
+    showControls?: boolean;
+    /**
+     * Pin the widget to the bottom-right of the viewport (fixed overlay).
+     * Default: false (inline in the mount target).
+     */
+    float?: boolean;
+    /**
+     * Persona / knowledge context id for /avatarReply (Text mode).
+     * When omitted, uses getAiTwin `knowledgeContextId` if available.
+     */
+    personaId?: string;
+    onReady?: () => void;
+    onStatusChange?: (status: AvatarTtsLipsyncStatus) => void;
+    onError?: (message: string) => void;
+    onUserTranscript?: (text: string, final: boolean) => void;
+    onBotOutput?: (text: string) => void;
+};
+
+export declare type AvatarReply = {
+    displayText: string;
+    spokenText: string;
+};
+
+export declare type AvatarReplyMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+
 export declare type AvatarTtsLipsyncController = {
     setDeveloperToken: (token: string) => void;
     setTtsEngineId: (engineId: TtsEngineId) => void;
@@ -210,6 +301,22 @@ export declare function faceAssetUrls(faceId: string, cdnBase?: string): TwinAss
 
 export declare function fetchAiTwin(id: string, baseUrl?: string): Promise<AiTwinRecord>;
 
+/**
+ * POST /avatarReply — LLM reply as displayText + spokenText (SSE).
+ * Same contract as aitwin-fe studio / Azure-test avatar_reply.
+ */
+export declare function fetchAvatarReply(options: FetchAvatarReplyOptions): Promise<AvatarReply>;
+
+export declare type FetchAvatarReplyOptions = {
+    message: string;
+    authToken: string;
+    apiBase?: string;
+    personaId?: string;
+    history?: AvatarReplyMessage[];
+    /** Called as soon as spokenText arrives on the SSE stream. */
+    onSpokenText?: (spokenText: string) => void;
+};
+
 /** Bearer token for /avatar_ttsWithPoses and /api/session-value. */
 export declare function fetchDevAuthToken(): Promise<string>;
 

package/package.json

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