@omote/three 0.2.0 → 0.3.2

package/dist/index.d.cts

@@ -1,6 +1,10 @@
 import * as _omote_core from '@omote/core';
-import { FaceCompositorConfig, EmotionWeights, ConversationalState, A2EOrchestratorConfig } from '@omote/core';
+import { FaceCompositorConfig, CharacterControllerConfig, FrameSource, TTSBackend, TTSSpeakerConfig, SpeechListenerConfig, TranscriptResult, VoiceOrchestratorConfig, ConversationalState, LoadingProgress, EmotionWeights, CharacterProfile } from '@omote/core';
+export { FrameSource, TTSSpeakerConfig as TTSConfig } from '@omote/core';
+import { SpeakOptions, StreamTextSink } from '@omote/avatar';
+import * as THREE from 'three';
 import { Object3D, Camera, SkinnedMesh } from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 
 /**
  * SceneDiscovery — Traverse a Three.js scene graph to discover bones and
@@ -67,35 +71,22 @@ interface SceneDiscoveryResult {
  */
 declare function discoverScene(scene: SceneObject): SceneDiscoveryResult;
 
-/** Generic frame source — any object that emits 'frame' events with blendshapes. */
-interface FrameSource {
-    on(event: 'frame', callback: (frame: {
-        blendshapes: Float32Array;
-    }) => void): void;
-    off?(event: 'frame', callback: (...args: any[]) => void): void;
-}
 interface OmoteAvatarOptions {
     /** Three.js Object3D (loaded GLB scene, Group, etc.) to traverse for meshes and bones. */
     target: Object3D;
     /** FaceCompositor configuration (profile, emotion, life layer). */
     compositor?: FaceCompositorConfig;
     /** Gaze tracking configuration. */
-    gaze?: {
-        enabled?: boolean;
-        yawInfluence?: number;
-        pitchInfluence?: number;
-        smoothing?: number;
-    };
+    gaze?: CharacterControllerConfig['gaze'];
 }
 declare class OmoteAvatar {
     private readonly controller;
     private readonly discovery;
+    private readonly core;
     private frameSourceCallback;
     private connectedSource;
     private currentBlendshapes;
     private _emotion;
-    private _isSpeaking;
-    private _state;
     private _audioEnergy;
     constructor(options: OmoteAvatarOptions);
     /**
@@ -119,6 +110,32 @@ declare class OmoteAvatar {
     connectFrameSource(source: FrameSource): void;
     /** Disconnect the currently connected frame source. */
     disconnectFrameSource(): void;
+    /** Warm up AudioContext for iOS/Safari autoplay policy. Call from user gesture. */
+    warmup(): Promise<void>;
+    connectSpeaker(tts: TTSBackend, config?: TTSSpeakerConfig): Promise<void>;
+    speak(text: string, options?: SpeakOptions): Promise<void>;
+    streamText(options?: SpeakOptions): Promise<StreamTextSink>;
+    stopSpeaking(): void;
+    disconnectSpeaker(): Promise<void>;
+    /** @deprecated Use connectSpeaker(). Will be removed in v1.0. */
+    connectTTS(tts: TTSBackend, config?: TTSSpeakerConfig): Promise<void>;
+    /** @deprecated Use disconnectSpeaker(). Will be removed in v1.0. */
+    disconnectTTS(): Promise<void>;
+    connectListener(config?: SpeechListenerConfig): Promise<void>;
+    startListening(): Promise<void>;
+    stopListening(): void;
+    onTranscript(callback: (result: TranscriptResult) => void): () => void;
+    disconnectListener(): Promise<void>;
+    connectVoice(config: VoiceOrchestratorConfig): Promise<void>;
+    disconnectVoice(): Promise<void>;
+    onTranscriptEvent(callback: (result: TranscriptResult) => void): () => void;
+    onVoiceStateChange(callback: (state: ConversationalState) => void): () => void;
+    onLoadingProgress(callback: (progress: LoadingProgress) => void): () => void;
+    onError(callback: (error: Error) => void): () => void;
+    onAudioLevel(callback: (level: {
+        rms: number;
+        peak: number;
+    }) => void): () => void;
     /** Set raw blendshapes directly (alternative to connectFrameSource). */
     setFrame(blendshapes: Float32Array): void;
     /** Set the current emotion (string preset name or EmotionWeights object). */
@@ -129,6 +146,8 @@ declare class OmoteAvatar {
     setState(state: ConversationalState): void;
     /** Set audio energy level (0-1, drives emphasis/gesture intensity). */
     setAudioEnergy(energy: number): void;
+    /** Update character expression profile at runtime. */
+    setProfile(profile: CharacterProfile): void;
     /** Access the underlying FaceCompositor for advanced configuration. */
     get compositor(): _omote_core.FaceCompositor;
     /** Access discovered scene parts (meshes, bones). */
@@ -137,10 +156,20 @@ declare class OmoteAvatar {
     get hasMorphTargets(): boolean;
     /** Number of successfully mapped ARKit blendshapes. */
     get mappedBlendshapeCount(): number;
+    /** Whether the avatar is currently speaking via TTS. */
+    get isSpeaking(): boolean;
+    /** Whether the avatar is currently listening for speech. */
+    get isListening(): boolean;
+    /** Current conversational state. */
+    get conversationalState(): ConversationalState;
+    /** Access the internal TTSSpeaker (null if not connected). */
+    get speaker(): _omote_core.TTSSpeaker | null;
+    /** Access the internal SpeechListener (null if not connected). */
+    get listener(): _omote_core.SpeechListener | null;
     /** Reset all state (smoothing, life layer, emotions). */
     reset(): void;
-    /** Disconnect frame sources and dispose the controller. */
-    dispose(): void;
+    /** Disconnect all voice resources, frame sources, and dispose the controller. */
+    dispose(): Promise<void>;
 }
 
 /**
@@ -162,6 +191,48 @@ declare class OmoteAvatar {
  */
 declare function writeBlendshapes(blendshapes: Float32Array, morphEntries: MorphIndexEntry[]): void;
 
+/**
+ * createAvatar — Async factory for a complete Three.js avatar scene.
+ *
+ * Sets up renderer, scene, camera, lighting, GLTF loading, OmoteAvatar,
+ * render loop, and resize handling. Returns a handle with all sub-objects.
+ *
+ * @example
+ * ```typescript
+ * import { createAvatar } from '@omote/three';
+ *
+ * const { avatar, dispose } = await createAvatar({
+ *   src: '/avatar.glb',
+ *   container: '#avatar-container',
+ * });
+ * avatar.connectFrameSource(pipeline);
+ * ```
+ *
+ * @category Three
+ */
+
+interface CreateAvatarConfig {
+    /** URL to GLB/GLTF avatar model */
+    src: string;
+    /** Container element or CSS selector */
+    container: HTMLElement | string;
+    /** Camera FOV (default: 35) */
+    fov?: number;
+    /** Enable orbit controls (default: true) */
+    controls?: boolean;
+}
+interface AvatarHandle {
+    avatar: OmoteAvatar;
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    renderer: THREE.WebGLRenderer;
+    controls: OrbitControls | null;
+    /** Animation clips embedded in the GLTF/GLB file. Pass to avatar.connectAnimations(). */
+    animations: THREE.AnimationClip[];
+    dispose(): void;
+}
+declare function createAvatar(config: CreateAvatarConfig): Promise<AvatarHandle>;
+
 interface BlendshapeControllerOptions {
     /** Blendshape names in order (default: LAM_BLENDSHAPES, 52 ARKit) */
     names?: readonly string[];
@@ -186,25 +257,4 @@ declare class BlendshapeController {
     dispose(): void;
 }
 
-interface OmoteA2EOptions extends A2EOrchestratorConfig {
-    target: Object3D;
-    controllerOptions?: BlendshapeControllerOptions;
-}
-/**
- * @deprecated Use {@link OmoteAvatar} instead. OmoteA2E will be removed in v0.8.0.
- */
-declare class OmoteA2E {
-    private orchestrator;
-    private controller;
-    constructor(options: OmoteA2EOptions);
-    load(): Promise<void>;
-    start(): Promise<void>;
-    stop(): void;
-    update(): void;
-    dispose(): Promise<void>;
-    get isReady(): boolean;
-    get isStreaming(): boolean;
-    get backend(): string | null;
-}
-
-export { BlendshapeController, type BlendshapeControllerOptions, type DiscoveredBone, type DiscoveredMesh, type FrameSource, type MorphIndexEntry, OmoteA2E, type OmoteA2EOptions, OmoteAvatar, type OmoteAvatarOptions, type SceneDiscoveryResult, type SceneObject, discoverScene, writeBlendshapes };
+export { type AvatarHandle, BlendshapeController, type BlendshapeControllerOptions, type CreateAvatarConfig, type DiscoveredBone, type DiscoveredMesh, type MorphIndexEntry, OmoteAvatar, type OmoteAvatarOptions, type SceneDiscoveryResult, type SceneObject, createAvatar, discoverScene, writeBlendshapes };

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 import * as _omote_core from '@omote/core';
-import { FaceCompositorConfig, EmotionWeights, ConversationalState, A2EOrchestratorConfig } from '@omote/core';
+import { FaceCompositorConfig, CharacterControllerConfig, FrameSource, TTSBackend, TTSSpeakerConfig, SpeechListenerConfig, TranscriptResult, VoiceOrchestratorConfig, ConversationalState, LoadingProgress, EmotionWeights, CharacterProfile } from '@omote/core';
+export { FrameSource, TTSSpeakerConfig as TTSConfig } from '@omote/core';
+import { SpeakOptions, StreamTextSink } from '@omote/avatar';
+import * as THREE from 'three';
 import { Object3D, Camera, SkinnedMesh } from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 
 /**
  * SceneDiscovery — Traverse a Three.js scene graph to discover bones and
@@ -67,35 +71,22 @@ interface SceneDiscoveryResult {
  */
 declare function discoverScene(scene: SceneObject): SceneDiscoveryResult;
 
-/** Generic frame source — any object that emits 'frame' events with blendshapes. */
-interface FrameSource {
-    on(event: 'frame', callback: (frame: {
-        blendshapes: Float32Array;
-    }) => void): void;
-    off?(event: 'frame', callback: (...args: any[]) => void): void;
-}
 interface OmoteAvatarOptions {
     /** Three.js Object3D (loaded GLB scene, Group, etc.) to traverse for meshes and bones. */
     target: Object3D;
     /** FaceCompositor configuration (profile, emotion, life layer). */
     compositor?: FaceCompositorConfig;
     /** Gaze tracking configuration. */
-    gaze?: {
-        enabled?: boolean;
-        yawInfluence?: number;
-        pitchInfluence?: number;
-        smoothing?: number;
-    };
+    gaze?: CharacterControllerConfig['gaze'];
 }
 declare class OmoteAvatar {
     private readonly controller;
     private readonly discovery;
+    private readonly core;
     private frameSourceCallback;
     private connectedSource;
     private currentBlendshapes;
     private _emotion;
-    private _isSpeaking;
-    private _state;
     private _audioEnergy;
     constructor(options: OmoteAvatarOptions);
     /**
@@ -119,6 +110,32 @@ declare class OmoteAvatar {
     connectFrameSource(source: FrameSource): void;
     /** Disconnect the currently connected frame source. */
     disconnectFrameSource(): void;
+    /** Warm up AudioContext for iOS/Safari autoplay policy. Call from user gesture. */
+    warmup(): Promise<void>;
+    connectSpeaker(tts: TTSBackend, config?: TTSSpeakerConfig): Promise<void>;
+    speak(text: string, options?: SpeakOptions): Promise<void>;
+    streamText(options?: SpeakOptions): Promise<StreamTextSink>;
+    stopSpeaking(): void;
+    disconnectSpeaker(): Promise<void>;
+    /** @deprecated Use connectSpeaker(). Will be removed in v1.0. */
+    connectTTS(tts: TTSBackend, config?: TTSSpeakerConfig): Promise<void>;
+    /** @deprecated Use disconnectSpeaker(). Will be removed in v1.0. */
+    disconnectTTS(): Promise<void>;
+    connectListener(config?: SpeechListenerConfig): Promise<void>;
+    startListening(): Promise<void>;
+    stopListening(): void;
+    onTranscript(callback: (result: TranscriptResult) => void): () => void;
+    disconnectListener(): Promise<void>;
+    connectVoice(config: VoiceOrchestratorConfig): Promise<void>;
+    disconnectVoice(): Promise<void>;
+    onTranscriptEvent(callback: (result: TranscriptResult) => void): () => void;
+    onVoiceStateChange(callback: (state: ConversationalState) => void): () => void;
+    onLoadingProgress(callback: (progress: LoadingProgress) => void): () => void;
+    onError(callback: (error: Error) => void): () => void;
+    onAudioLevel(callback: (level: {
+        rms: number;
+        peak: number;
+    }) => void): () => void;
     /** Set raw blendshapes directly (alternative to connectFrameSource). */
     setFrame(blendshapes: Float32Array): void;
     /** Set the current emotion (string preset name or EmotionWeights object). */
@@ -129,6 +146,8 @@ declare class OmoteAvatar {
     setState(state: ConversationalState): void;
     /** Set audio energy level (0-1, drives emphasis/gesture intensity). */
     setAudioEnergy(energy: number): void;
+    /** Update character expression profile at runtime. */
+    setProfile(profile: CharacterProfile): void;
     /** Access the underlying FaceCompositor for advanced configuration. */
     get compositor(): _omote_core.FaceCompositor;
     /** Access discovered scene parts (meshes, bones). */
@@ -137,10 +156,20 @@ declare class OmoteAvatar {
     get hasMorphTargets(): boolean;
     /** Number of successfully mapped ARKit blendshapes. */
     get mappedBlendshapeCount(): number;
+    /** Whether the avatar is currently speaking via TTS. */
+    get isSpeaking(): boolean;
+    /** Whether the avatar is currently listening for speech. */
+    get isListening(): boolean;
+    /** Current conversational state. */
+    get conversationalState(): ConversationalState;
+    /** Access the internal TTSSpeaker (null if not connected). */
+    get speaker(): _omote_core.TTSSpeaker | null;
+    /** Access the internal SpeechListener (null if not connected). */
+    get listener(): _omote_core.SpeechListener | null;
     /** Reset all state (smoothing, life layer, emotions). */
     reset(): void;
-    /** Disconnect frame sources and dispose the controller. */
-    dispose(): void;
+    /** Disconnect all voice resources, frame sources, and dispose the controller. */
+    dispose(): Promise<void>;
 }
 
 /**
@@ -162,6 +191,48 @@ declare class OmoteAvatar {
  */
 declare function writeBlendshapes(blendshapes: Float32Array, morphEntries: MorphIndexEntry[]): void;
 
+/**
+ * createAvatar — Async factory for a complete Three.js avatar scene.
+ *
+ * Sets up renderer, scene, camera, lighting, GLTF loading, OmoteAvatar,
+ * render loop, and resize handling. Returns a handle with all sub-objects.
+ *
+ * @example
+ * ```typescript
+ * import { createAvatar } from '@omote/three';
+ *
+ * const { avatar, dispose } = await createAvatar({
+ *   src: '/avatar.glb',
+ *   container: '#avatar-container',
+ * });
+ * avatar.connectFrameSource(pipeline);
+ * ```
+ *
+ * @category Three
+ */
+
+interface CreateAvatarConfig {
+    /** URL to GLB/GLTF avatar model */
+    src: string;
+    /** Container element or CSS selector */
+    container: HTMLElement | string;
+    /** Camera FOV (default: 35) */
+    fov?: number;
+    /** Enable orbit controls (default: true) */
+    controls?: boolean;
+}
+interface AvatarHandle {
+    avatar: OmoteAvatar;
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    renderer: THREE.WebGLRenderer;
+    controls: OrbitControls | null;
+    /** Animation clips embedded in the GLTF/GLB file. Pass to avatar.connectAnimations(). */
+    animations: THREE.AnimationClip[];
+    dispose(): void;
+}
+declare function createAvatar(config: CreateAvatarConfig): Promise<AvatarHandle>;
+
 interface BlendshapeControllerOptions {
     /** Blendshape names in order (default: LAM_BLENDSHAPES, 52 ARKit) */
     names?: readonly string[];
@@ -186,25 +257,4 @@ declare class BlendshapeController {
     dispose(): void;
 }
 
-interface OmoteA2EOptions extends A2EOrchestratorConfig {
-    target: Object3D;
-    controllerOptions?: BlendshapeControllerOptions;
-}
-/**
- * @deprecated Use {@link OmoteAvatar} instead. OmoteA2E will be removed in v0.8.0.
- */
-declare class OmoteA2E {
-    private orchestrator;
-    private controller;
-    constructor(options: OmoteA2EOptions);
-    load(): Promise<void>;
-    start(): Promise<void>;
-    stop(): void;
-    update(): void;
-    dispose(): Promise<void>;
-    get isReady(): boolean;
-    get isStreaming(): boolean;
-    get backend(): string | null;
-}
-
-export { BlendshapeController, type BlendshapeControllerOptions, type DiscoveredBone, type DiscoveredMesh, type FrameSource, type MorphIndexEntry, OmoteA2E, type OmoteA2EOptions, OmoteAvatar, type OmoteAvatarOptions, type SceneDiscoveryResult, type SceneObject, discoverScene, writeBlendshapes };
+export { type AvatarHandle, BlendshapeController, type BlendshapeControllerOptions, type CreateAvatarConfig, type DiscoveredBone, type DiscoveredMesh, type MorphIndexEntry, OmoteAvatar, type OmoteAvatarOptions, type SceneDiscoveryResult, type SceneObject, createAvatar, discoverScene, writeBlendshapes };