@spatialwalk/avatarkit 1.0.0-beta.70 → 1.0.0-beta.72

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-beta.72] - 2026-01-17
+
+### 📚 Documentation
+- **README Optimization** - Enhanced README with authentication section and improved API documentation
+
+## [1.0.0-beta.71] - 2026-01-17
+
+### 🔧 Improvements
+- **Internal API** - Marked all audio and animation internal classes with `@internal` to prevent public API exposure
+- **Type Safety** - Hidden `AnimationPlayer`, `StreamingAudioPlayer`, `AnimationWebSocketClient`, and related utilities from public API
+- **Internal Documentation** - Fixed missing English translations in `AnimationWebSocketClient.ts`
+
 ## [1.0.0-beta.70] - 2026-01-17
 
 ### 🔧 Improvements

package/README.md

@@ -18,13 +18,34 @@ Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supportin
 npm install @spatialwalk/avatarkit
 ```
 
-## 🔧 Vite 配置（推荐）
+## 🚀 Demo Repository
 
-如果你使用 Vite 作为构建工具，强烈推荐使用我们的 Vite 插件来自动处理 WASM 文件配置。插件会自动处理所有必要的配置，让你无需手动设置。
+<div align="center">
 
-### 使用插件
+### 📌 **Quick Start: Check Out Our Demo Repository**
 
-在 `vite.config.ts` 中添加插件：
+We provide complete example code and best practices to help you quickly integrate the SDK.
+
+**The demo repository includes:**
+- ✅ Complete integration examples
+- ✅ Usage examples for both SDK mode and Host mode  
+- ✅ Audio processing examples (PCM16, WAV, MP3, etc.)
+- ✅ Vite configuration examples
+- ✅ Best practices for common scenarios
+
+**[👉 View Demo Repository](https://github.com/spatialwalk/avatarkit-demo)** | *If not yet created, please contact the team*
+
+</div>
+
+---
+
+## 🔧 Vite Configuration (Recommended)
+
+If you are using Vite as your build tool, we strongly recommend using our Vite plugin to automatically handle WASM file configuration. The plugin automatically handles all necessary configurations, so you don't need to set them up manually.
+
+### Using the Plugin
+
+Add the plugin to `vite.config.ts`:
 
 ```typescript
 import { defineConfig } from 'vite'
@@ -32,27 +53,27 @@ import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
 
 export default defineConfig({
   plugins: [
-    avatarkitVitePlugin(), // 添加这一行即可
+    avatarkitVitePlugin(), // Just add this line
   ],
 })
 ```
 
-### 插件功能
+### Plugin Features
 
-插件会自动处理：
+The plugin automatically handles:
 
-- ✅ **开发服务器**：自动设置 WASM 文件的正确 MIME 类型 (`application/wasm`)
-- ✅ **构建时**：自动复制 WASM 文件到 `dist/assets/` 目录
-  - 智能检测：从 JS glue 文件中提取引用的 WASM 文件名（包括 hash）
-  - 自动匹配：确保复制的 WASM 文件与 JS glue 文件中的引用匹配
-  - 支持 hash：正确处理带 hash 的 WASM 文件（如 `avatar_core_wasm-{hash}.wasm`）
-- ✅ **WASM JS Glue**：自动复制 WASM JS glue 文件到 `dist/assets/` 目录
-- ✅ **Cloudflare Pages**：自动生成 `_headers` 文件，确保 WASM 文件使用正确的 MIME 类型
-- ✅ **Vite 配置**：自动配置 `optimizeDeps`、`assetsInclude`、`assetsInlineLimit` 等选项
+- ✅ **Development Server**: Automatically sets the correct MIME type (`application/wasm`) for WASM files
+- ✅ **Build Time**: Automatically copies WASM files to `dist/assets/` directory
+  - Smart Detection: Extracts referenced WASM file names (including hash) from JS glue files
+  - Auto Matching: Ensures copied WASM files match references in JS glue files
+  - Hash Support: Correctly handles hashed WASM files (e.g., `avatar_core_wasm-{hash}.wasm`)
+- ✅ **WASM JS Glue**: Automatically copies WASM JS glue files to `dist/assets/` directory
+- ✅ **Cloudflare Pages**: Automatically generates `_headers` file to ensure WASM files use the correct MIME type
+- ✅ **Vite Configuration**: Automatically configures `optimizeDeps`, `assetsInclude`, `assetsInlineLimit`, and other options
 
-### 手动配置（不使用插件）
+### Manual Configuration (Without Plugin)
 
-如果你不使用 Vite 插件，需要手动配置以下内容：
+If you don't use the Vite plugin, you need to manually configure the following:
 
 ```typescript
 // vite.config.ts
@@ -74,7 +95,7 @@ export default defineConfig({
       },
     },
   },
-  // 开发服务器需要手动配置中间件设置 WASM MIME 类型
+  // Development server needs to manually configure middleware to set WASM MIME type
   configureServer(server) {
     server.middlewares.use((req, res, next) => {
       if (req.url?.endsWith('.wasm')) {
@@ -86,6 +107,53 @@ export default defineConfig({
 })
 ```
 
+## 🔐 Authentication
+
+All environments require an **App ID** and **Session Token** for authentication.
+
+### App ID
+
+The App ID is used to identify your application. You can obtain your App ID by:
+
+1. **For Testing**: Use the default test App ID provided in demo repositories (paired with test Session Token, only works with publicly available test avatars like Rohan, Dr.Kellan, Priya, Josh, etc.)
+2. **For Production**: Visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and avatars. You will receive your own App ID after creating an App.
+
+### Session Token
+
+The Session Token is required for WebSocket authentication and must be obtained from your SDK provider.
+
+**⚠️ Important Notes:**
+- The Session Token must be valid and not expired
+- In production applications, you **must** manually inject a valid Session Token obtained from your SDK provider
+- The default Session Token provided in demo repositories is **only for demonstration purposes** and can only be used with test avatars
+- If you want to create your own avatars and test them, please visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and generate Session Tokens
+
+**How to Set Session Token:**
+
+```typescript
+// Initialize SDK with App ID
+await AvatarSDK.initialize('your-app-id', configuration)
+
+// Set Session Token (can be called before or after initialization)
+// If called before initialization, the token will be automatically set when you initialize the SDK
+AvatarSDK.setSessionToken('your-session-token')
+
+// Get current Session Token
+const sessionToken = AvatarSDK.sessionToken
+```
+
+**Token Management:**
+- The Session Token can be set at any time using `AvatarSDK.setSessionToken(token)`
+- If you set the token before initializing the SDK, it will be automatically applied during initialization
+- If you set the token after initialization, it will be applied immediately
+- Handle token refresh logic in your application as needed (e.g., when token expires)
+
+**For Production Integration:**
+- Obtain a valid Session Token from your SDK provider
+- Store the token securely (never expose it in client-side code if possible)
+- Implement token refresh logic to handle token expiration
+- Use `AvatarSDK.setSessionToken(token)` to inject the token programmatically
+
 ## 🎯 Quick Start
 
 ### ⚠️ Important: Audio Context Initialization
@@ -126,8 +194,10 @@ const configuration: Configuration = {
 
 await AvatarSDK.initialize('your-app-id', configuration)
 
-// Set sessionToken (if needed, call separately)
-// AvatarSDK.setSessionToken('your-session-token')
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section above for more details
+AvatarSDK.setSessionToken('your-session-token')
 
 // 2. Load avatar
 const avatarManager = AvatarManager.shared
@@ -408,7 +478,9 @@ const appId = AvatarSDK.appId
 // Get configuration
 const config = AvatarSDK.configuration
 
-// Set sessionToken (if needed, call separately)
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section for more details
 AvatarSDK.setSessionToken('your-session-token')
 
 // Set userId (optional, for telemetry)
@@ -437,7 +509,7 @@ const manager = AvatarManager.shared
 
 // Load avatar
 const avatar = await manager.load(
-  characterId: string, 
+  id: string, 
   onProgress?: (progress: LoadProgressInfo) => void
 )
 
@@ -505,7 +577,7 @@ const newAvatar = await avatarManager.load('new-character-id')
 currentAvatarView = new AvatarView(newAvatar, container)
 
 // SDK mode: start connection (will throw error if not in SDK mode)
-  await currentAvatarView.controller.start()
+await currentAvatarView.controller.start()
 ```
 
 ### AvatarController
@@ -581,24 +653,30 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
+// Pause playback (from playing state)
+avatarView.controller.pause()
+
+// Resume playback (from paused state)
+await avatarView.controller.resume()
+
 // Interrupt current playback (stops and clears data)
-avatarView.avatarController.interrupt()
+avatarView.controller.interrupt()
 
 // Clear all data and resources
-avatarView.avatarController.clear()
+avatarView.controller.clear()
 
 // Get current conversation ID (for Host mode)
-const conversationId = avatarView.avatarController.getCurrentConversationId()
+const conversationId = avatarView.controller.getCurrentConversationId()
 // Returns: Current conversationId for the active audio session, or null if no active session
 
 // Volume control (affects only avatar audio player, not system volume)
-avatarView.avatarController.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
-const currentVolume = avatarView.avatarController.getVolume()  // Get current volume (0.0 to 1.0)
+avatarView.controller.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
+const currentVolume = avatarView.controller.getVolume()  // Get current volume (0.0 to 1.0)
 
 // Set event callbacks
-avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // SDK mode only
-avatarView.avatarController.onConversationState = (state: ConversationState) => {}
-avatarView.avatarController.onError = (error: Error) => {}
+avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
+avatarView.controller.onConversationState = (state: ConversationState) => {}
+avatarView.controller.onError = (error: Error) => {}
 ```
 
 #### Avatar Transform Methods
@@ -674,7 +752,7 @@ enum LogLevel {
     - Supported values: 8000, 16000, 22050, 24000, 32000, 44100, 48000
     - The configured sample rate will be used for both audio recording and playback
 - `characterApiBaseUrl`: Internal debug config, can be ignored
-- `sessionToken`: Set separately via `AvatarSDK.setSessionToken()`, not in Configuration
+- `sessionToken`: **Required for authentication**. Set separately via `AvatarSDK.setSessionToken()`, not in Configuration. See [Authentication](#-authentication) section for details
 
 ```typescript
 enum Environment {
@@ -734,7 +812,7 @@ enum ConversationState {
 The SDK supports two rendering backends:
 
 - **WebGPU** - High-performance rendering for modern browsers
-- **WebGL** - Better compatibility traditional rendering
+- **WebGL** - Better compatibility for traditional rendering
 
 The rendering system automatically selects the best backend, no manual configuration needed.
 
@@ -748,7 +826,7 @@ The SDK uses custom error types, providing more detailed error information:
 import { AvatarError } from '@spatialwalk/avatarkit'
 
 try {
-  await avatarView.avatarController.start()
+  await avatarView.controller.start()
 } catch (error) {
   if (error instanceof AvatarError) {
     console.error('SDK Error:', error.message, error.code)
@@ -761,7 +839,7 @@ try {
 ### Error Callbacks
 
 ```typescript
-avatarView.avatarController.onError = (error: Error) => {
+avatarView.controller.onError = (error: Error) => {
   console.error('AvatarController error:', error)
   // Handle error, such as reconnection, user notification, etc.
 }
@@ -777,14 +855,13 @@ avatarView.avatarController.onError = (error: Error) => {
 // Initialize
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
-await avatarView.avatarController.start()
+await avatarView.controller.start()
 
 // Use
-avatarView.avatarController.send(audioData, false)
+avatarView.controller.send(audioData, false)
 
-// Cleanup
-avatarView.avatarController.close()
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including WebSocket connections
+avatarView.dispose()
 ```
 
 #### Host Mode Lifecycle
@@ -795,19 +872,21 @@ const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
 // Use
-const conversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
-avatarView.avatarController.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
+const conversationId = avatarView.controller.yieldAudioData(audioChunk, false)
+avatarView.controller.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
 
-// Cleanup
-avatarView.avatarController.clear() // Clear all data and resources
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including playback data
+avatarView.dispose()
 ```
 
 **⚠️ Important Notes:** 
-- When disposing AvatarView instances, must call `dispose()` to properly clean up resources
-- Not properly cleaning up may cause resource leaks and rendering errors
-- In SDK mode, call `close()` before `dispose()` to properly close WebSocket connections
-- In Host mode, call `clear()` before `dispose()` to clear all playback data
+- `dispose()` automatically cleans up all resources, including:
+  - WebSocket connections (SDK mode)
+  - Playback data and animation resources (both modes)
+  - Render system and canvas elements
+  - All event listeners and callbacks
+- Not properly calling `dispose()` may cause resource leaks and rendering errors
+- If you need to manually close WebSocket connections or clear playback data before disposing, you can call `avatarView.controller.close()` (SDK mode) or `avatarView.controller.clear()` (both modes) first, but it's not required as `dispose()` handles this automatically
 
 ### Memory Optimization
 

package/dist/{StreamingAudioPlayer-Bi2685bX.js → StreamingAudioPlayer-fV-zTOrl.js}

@@ -1,9 +1,9 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CvW_c7G-.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-BginsqFH.js";
 class StreamingAudioPlayer {
-  // 标记是否正在恢复 AudioContext，避免并发恢复请求
+  // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
     // AudioContext is managed internally
     __publicField(this, "audioContext", null);
@@ -28,17 +28,17 @@ class StreamingAudioPlayer {
     __publicField(this, "autoStartEnabled", true);
     // Control whether to auto-start when buffer is ready
     __publicField(this, "autoContinue", false);
-    // 标记是否应该自动继续播放（当 end=false 且无数据时自动暂停后使用）
+    // Mark if should auto-continue playback (used after auto-pause when end=false and no data)
     // Audio buffer queue
     __publicField(this, "audioChunks", []);
     __publicField(this, "scheduledChunks", 0);
     // Number of chunks already scheduled
     __publicField(this, "activeSources", /* @__PURE__ */ new Set());
     __publicField(this, "lastScheduledChunkEndTime", 0);
-    // 最后一个已调度 chunk 的结束时间（相对时间）
+    // End time of last scheduled chunk (relative time)
     __publicField(this, "lastGetCurrentTimeLog", 0);
-    // 上次记录 getCurrentTime 日志的时间戳（用于节流）
-    // 跟踪每个已调度的 chunk 的开始时间（绝对时间）和持续时间，用于准确计算当前播放时间
+    // Timestamp of last getCurrentTime log (for throttling)
+    // Track start time (absolute time) and duration of each scheduled chunk for accurate current playback time calculation
     __publicField(this, "scheduledChunkInfo", []);
     // Volume control
     __publicField(this, "gainNode", null);
@@ -96,13 +96,14 @@ class StreamingAudioPlayer {
     }
   }
   /**
-   * 确保 AudioContext 正在运行（如果被暂停则自动恢复）
-   * 只在正在播放且未暂停时自动恢复，避免干扰正常的暂停/恢复逻辑
+   * Ensure AudioContext is running (auto-resume if suspended)
+   * Only auto-resume when playing and not paused, avoid interfering with normal pause/resume logic
    * 
-   * 优化：
-   * - 快速路径：如果已经是 running 状态，直接返回
-   * - 避免并发恢复：使用 isResuming 标志防止重复恢复请求
-   * - 处理 closed 状态：如果 AudioContext 已关闭，无法恢复
+   * Optimizations:
+   * - Fast path: if already in running state, return directly
+   * - Avoid concurrent resume: use isResuming flag to prevent duplicate resume requests
+   * - Handle closed state: if AudioContext is closed, cannot resume
+   * @internal
    */
   async ensureAudioContextRunning() {
     if (!this.audioContext) {
@@ -372,7 +373,8 @@ class StreamingAudioPlayer {
   }
   /**
    * Get current playback time (seconds)
-   * 返回实际播放的音频总时长
+   * Returns total actual playback duration
+   * @internal
    */
   getCurrentTime() {
     if (!this.audioContext || !this.isPlaying) {
@@ -403,7 +405,8 @@ class StreamingAudioPlayer {
   }
   /**
    * Get total duration of buffered audio (seconds)
-   * 计算所有已缓冲 chunk 的总时长
+   * Calculate total duration of all buffered chunks
+   * @internal
    */
   getBufferedDuration() {
     if (!this.audioContext) {
@@ -598,9 +601,10 @@ class StreamingAudioPlayer {
     this.log("Flushed (soft)", { remainingScheduled: this.scheduledChunks });
   }
   /**
-   * 设置音量 (0.0 - 1.0)
-   * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-   * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+   * Set volume (0.0 - 1.0)
+   * Note: This only controls avatar audio player volume, does not affect system volume
+   * @param volume Volume value, range 0.0 to 1.0 (0.0 is mute, 1.0 is max volume)
+   * @internal
    */
   setVolume(volume) {
     if (volume < 0 || volume > 1) {
@@ -613,8 +617,9 @@ class StreamingAudioPlayer {
     }
   }
   /**
-   * 获取当前音量
-   * @returns 当前音量值 (0.0 - 1.0)
+   * Get current volume
+   * @returns Current volume value (0.0 - 1.0)
+   * @internal
    */
   getVolume() {
     return this.volume;

package/dist/animation/AnimationWebSocketClient.d.ts

@@ -1,61 +1,6 @@
-import { EventEmitter } from './utils/eventEmitter';
-export interface AnimationWebSocketClientOptions {
-    wsUrl: string;
-    reconnectAttempts?: number;
-    jwtToken?: string;
-    appId?: string;
-    clientId?: string;
-}
-export declare class AnimationWebSocketClient extends EventEmitter {
-    private wsUrl;
-    private reconnectAttempts;
-    private jwtToken?;
-    private appId?;
-    private clientId?;
-    private ws;
-    private currentCharacterId;
-    private currentRetryCount;
-    private isConnecting;
-    private isManuallyDisconnected;
-    private reconnectTimer;
-    private sessionConfigured;
-    constructor(options: AnimationWebSocketClientOptions);
-    /**
-     * 连接WebSocket
-     */
-    connect(characterId: string): Promise<void>;
-    /**
-     * 断开连接
-     */
-    disconnect(): void;
-    /**
-     * 发送音频数据
-     * @param conversationId - 会话ID（在 protobuf 协议中映射为 reqId 字段）
-     */
-    sendAudioData(conversationId: string, audioData: ArrayBuffer, end: boolean): boolean;
-    /**
-     * 生成会话ID
-     * 使用统一的会话ID生成规则：YYYYMMDDHHmmss_nanoid
-     */
-    generateConversationId(): string;
-    /**
-     * 获取连接状态
-     */
-    isConnected(): boolean;
-    /**
-     * 获取当前角色ID
-     */
-    getCurrentCharacterId(): string;
-    private buildWebSocketUrl;
-    private connectWebSocket;
-    /**
-     * 清理 URL 用于日志记录（隐藏敏感信息）
-     */
-    private sanitizeUrlForLog;
-    /**
-     * v2 协议：配置会话（发送采样率等参数）
-     */
-    private configureSession;
-    private handleMessage;
-    private scheduleReconnect;
-}
+/**
+ * AnimationWebSocketClient: Animation-specific WebSocket client
+ * Uses driveningress/v2 protocol, only handles audio input and animation output
+ * @internal
+ */
+export {};

package/dist/animation/utils/eventEmitter.d.ts

@@ -1,12 +1,5 @@
 /**
  * Simple Event Emitter
+ * @internal
  */
-type EventHandler = (...args: any[]) => void;
-export declare class EventEmitter {
-    private events;
-    on(event: string, handler: EventHandler): void;
-    off(event: string, handler: EventHandler): void;
-    emit(event: string, ...args: any[]): void;
-    removeAllListeners(event?: string): void;
-}
 export {};

package/dist/animation/utils/flameConverter.d.ts

@@ -1,25 +1,5 @@
-import { Flame } from '../../generated/driveningress/v1/driveningress';
-export interface FlameParams {
-    shape_params?: number[];
-    expr_params?: number[];
-    rotation?: number[];
-    translation?: number[];
-    neck_pose?: number[];
-    jaw_pose?: number[];
-    eyes_pose?: number[];
-    eyelid?: number[];
-    has_eyelid?: boolean;
-}
 /**
- * Convert proto Flame to WASM FlameParams format
+ * Convert proto Flame to WASM FlameParams
+ * @internal
  */
-export declare function convertProtoFlameToWasmParams(protoFlame: Flame): FlameParams;
-/**
- * Convert WASM FlameParams to proto Flame format
- * Used for transition animation from idle to speaking
- */
-export declare function convertWasmParamsToProtoFlame(wasmParams: FlameParams): Flame;
-/**
- * Create a neutral proto Flame (zero pose)
- */
-export declare function createNeutralFlameProto(): Flame;
+export {};

package/dist/audio/AnimationPlayer.d.ts

@@ -1,75 +1,6 @@
-import { StreamingAudioPlayer } from './StreamingAudioPlayer';
-export declare class AnimationPlayer {
-    private audio;
-    private streamingPlayer;
-    private _isPlaying;
-    private fps;
-    private onEndedCallback?;
-    private static audioUnlocked;
-    private useStreaming;
-    /**
-     * 解锁音频上下文（Safari 自动播放策略）
-     * 必须在用户交互事件（如 click）中调用
-     */
-    static unlockAudioContext(): Promise<void>;
-    /**
-     * Initialize with HTMLAudioElement (traditional way)
-     */
-    initialize(audioUrl: string, onEnded?: () => void): Promise<void>;
-    /**
-     * Initialize with StreamingAudioPlayer (streaming way)
-     * @deprecated 使用 prepareStreamingPlayer() 代替
-     */
-    initializeStreaming(streamingPlayer: StreamingAudioPlayer, onEnded?: () => void): Promise<void>;
-    /**
-     * 检查流式播放器是否已准备好
-     */
-    isStreamingReady(): boolean;
-    /**
-     * 获取流式播放器实例
-     */
-    getStreamingPlayer(): StreamingAudioPlayer | null;
-    /**
-     * 创建并初始化流式播放器
-     * 在服务连接建立时调用
-     */
-    createAndInitializeStreamingPlayer(): Promise<void>;
-    /**
-     * 准备流式播放器（如果未创建则创建并初始化）
-     * 停止之前的播放并更新结束回调
-     */
-    prepareStreamingPlayer(onEnded?: () => void): Promise<void>;
-    private setupEventListeners;
-    play(): Promise<void>;
-    stop(): void;
-    isPlaying(): boolean;
-    getCurrentFrameIndex(): number;
-    /**
-     * Get current playback time
-     */
-    getCurrentTime(): number;
-    /**
-     * 添加音频块（仅用于流式播放）
-     */
-    addAudioChunk(audio: Uint8Array, isLast?: boolean): void;
-    /**
-     * 暂停播放
-     */
-    pause(): void;
-    /**
-     * 继续播放
-     */
-    resume(): Promise<void>;
-    /**
-     * 设置音量 (0.0 - 1.0)
-     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
-     */
-    setVolume(volume: number): void;
-    /**
-     * 获取当前音量
-     * @returns 当前音量值 (0.0 - 1.0)
-     */
-    getVolume(): number;
-    dispose(): void;
-}
+/**
+ * Audio-animation synchronized player
+ * Supports HTMLAudioElement (traditional) and StreamingAudioPlayer (streaming)
+ * @internal
+ */
+export {};

package/dist/audio/StreamingAudioPlayer.d.ts

@@ -2,154 +2,6 @@
  * Streaming Audio Player
  * Implements real-time audio playback using Web Audio API
  * Supports dynamic PCM chunk addition without Workers
+ * @internal
  */
-export interface StreamingAudioPlayerOptions {
-    sampleRate?: number;
-    channelCount?: number;
-    debug?: boolean;
-}
-export declare class StreamingAudioPlayer {
-    private audioContext;
-    private sampleRate;
-    private channelCount;
-    private debug;
-    private sessionId;
-    private sessionStartTime;
-    private pausedTimeOffset;
-    private pausedAt;
-    private pausedAudioContextTime;
-    private scheduledTime;
-    private isPlaying;
-    private isPaused;
-    private autoStartEnabled;
-    private autoContinue;
-    private audioChunks;
-    private scheduledChunks;
-    private activeSources;
-    private lastScheduledChunkEndTime;
-    private lastGetCurrentTimeLog;
-    private scheduledChunkInfo;
-    private gainNode;
-    private volume;
-    private onEndedCallback?;
-    private stateChangeHandler?;
-    private isResuming;
-    constructor(options?: StreamingAudioPlayerOptions);
-    /**
-     * Initialize audio context (create and ensure it's ready)
-     */
-    initialize(): Promise<void>;
-    /**
-     * 确保 AudioContext 正在运行（如果被暂停则自动恢复）
-     * 只在正在播放且未暂停时自动恢复，避免干扰正常的暂停/恢复逻辑
-     *
-     * 优化：
-     * - 快速路径：如果已经是 running 状态，直接返回
-     * - 避免并发恢复：使用 isResuming 标志防止重复恢复请求
-     * - 处理 closed 状态：如果 AudioContext 已关闭，无法恢复
-     */
-    private ensureAudioContextRunning;
-    /**
-     * Add audio chunk (16-bit PCM)
-     */
-    addChunk(pcmData: Uint8Array, isLast?: boolean): void;
-    /**
-     * Start new session (stop current and start fresh)
-     */
-    startNewSession(audioChunks: Array<{
-        data: Uint8Array;
-        isLast: boolean;
-    }>): Promise<void>;
-    /**
-     * Start playback
-     */
-    private startPlayback;
-    /**
-     * Schedule all pending chunks
-     */
-    private scheduleAllChunks;
-    /**
-     * Schedule next audio chunk
-     */
-    private scheduleNextChunk;
-    /**
-     * Convert PCM data to AudioBuffer
-     * Input: 16-bit PCM (int16), Output: AudioBuffer (float32 [-1, 1])
-     */
-    private pcmToAudioBuffer;
-    /**
-     * Get current playback time (seconds)
-     * 返回实际播放的音频总时长
-     */
-    getCurrentTime(): number;
-    /**
-     * Get total duration of buffered audio (seconds)
-     * 计算所有已缓冲 chunk 的总时长
-     */
-    getBufferedDuration(): number;
-    /**
-     * Get current AudioContext time
-     * @returns Current AudioContext time in seconds, or 0 if AudioContext is not initialized
-     */
-    getAudioContextTime(): number;
-    /**
-     * Pause playback
-     */
-    pause(): void;
-    /**
-     * Resume playback
-     */
-    resume(): Promise<void>;
-    /**
-     * Stop playback
-     */
-    stop(): void;
-    /**
-     * Enable or disable auto-start (for delayed start scenarios)
-     */
-    setAutoStart(enabled: boolean): void;
-    /**
-     * Start playback manually (for delayed start scenarios)
-     * This allows starting playback after transition animation completes
-     */
-    play(): void;
-    /**
-     * Mark playback as ended
-     */
-    markEnded(): void;
-    /**
-     * Set ended callback
-     */
-    onEnded(callback: () => void): void;
-    /**
-     * Check if playing
-     */
-    isPlayingNow(): boolean;
-    /**
-     * Dispose and cleanup
-     */
-    dispose(): void;
-    /**
-     * Flush buffered audio
-     * - hard: stops all playing sources and clears all chunks
-     * - soft (default): clears UNSCHEDULED chunks only
-     */
-    flush(options?: {
-        hard?: boolean;
-    }): void;
-    /**
-     * 设置音量 (0.0 - 1.0)
-     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
-     */
-    setVolume(volume: number): void;
-    /**
-     * 获取当前音量
-     * @returns 当前音量值 (0.0 - 1.0)
-     */
-    getVolume(): number;
-    /**
-     * Debug logging
-     */
-    private log;
-}
+export {};

package/dist/{index-CvW_c7G-.js → index-BginsqFH.js}

@@ -7780,8 +7780,9 @@ const _AnimationPlayer = class _AnimationPlayer {
     __publicField(this, "useStreaming", false);
   }
   /**
-   * 解锁音频上下文（Safari 自动播放策略）
-   * 必须在用户交互事件（如 click）中调用
+   * Unlock audio context (Safari autoplay policy)
+   * Must be called in user interaction event (e.g., click)
+   * @internal
    */
   static async unlockAudioContext() {
     if (_AnimationPlayer.audioUnlocked) {
@@ -7802,6 +7803,9 @@ const _AnimationPlayer = class _AnimationPlayer {
   }
   /**
    * Initialize with HTMLAudioElement (traditional way)
+   * @param audioUrl Audio file URL
+   * @param onEnded Optional callback when playback ends
+   * @internal
    */
   async initialize(audioUrl, onEnded) {
     this.onEndedCallback = onEnded;
@@ -7820,7 +7824,8 @@ const _AnimationPlayer = class _AnimationPlayer {
   }
   /**
    * Initialize with StreamingAudioPlayer (streaming way)
-   * @deprecated 使用 prepareStreamingPlayer() 代替
+   * @deprecated Use prepareStreamingPlayer() instead
+   * @internal
    */
   async initializeStreaming(streamingPlayer, onEnded) {
     this.streamingPlayer = streamingPlayer;
@@ -7833,26 +7838,29 @@ const _AnimationPlayer = class _AnimationPlayer {
     });
   }
   /**
-   * 检查流式播放器是否已准备好
+   * Check if streaming player is ready
+   * @internal
    */
   isStreamingReady() {
     return this.useStreaming && this.streamingPlayer !== null;
   }
   /**
-   * 获取流式播放器实例
+   * Get streaming player instance
+   * @internal
    */
   getStreamingPlayer() {
     return this.streamingPlayer;
   }
   /**
-   * 创建并初始化流式播放器
-   * 在服务连接建立时调用
+   * Create and initialize streaming player
+   * Called when service connection is established
+   * @internal
    */
   async createAndInitializeStreamingPlayer() {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-Bi2685bX.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-fV-zTOrl.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -7874,8 +7882,9 @@ const _AnimationPlayer = class _AnimationPlayer {
     this.useStreaming = true;
   }
   /**
-   * 准备流式播放器（如果未创建则创建并初始化）
-   * 停止之前的播放并更新结束回调
+   * Prepare streaming player (create and initialize if not created)
+   * Stop previous playback and update end callback
+   * @internal
    */
   async prepareStreamingPlayer(onEnded) {
     if (!this.streamingPlayer) {
@@ -7904,6 +7913,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
     });
   }
+  /**
+   * Start playback
+   * @internal
+   */
   async play() {
     if (this.useStreaming) {
       this._isPlaying = true;
@@ -7914,6 +7927,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       await this.audio.play();
     }
   }
+  /**
+   * Stop playback
+   * @internal
+   */
   stop() {
     var _a;
     this._isPlaying = false;
@@ -7926,6 +7943,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       }
     }
   }
+  /**
+   * Check if currently playing
+   * @internal
+   */
   isPlaying() {
     var _a;
     if (this.useStreaming) {
@@ -7933,12 +7954,17 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
     return this._isPlaying;
   }
+  /**
+   * Get current frame index
+   * @internal
+   */
   getCurrentFrameIndex() {
     const currentTime = this.getCurrentTime();
     return Math.floor(currentTime * this.fps);
   }
   /**
    * Get current playback time
+   * @internal
    */
   getCurrentTime() {
     var _a, _b;
@@ -7948,7 +7974,8 @@ const _AnimationPlayer = class _AnimationPlayer {
     return ((_b = this.audio) == null ? void 0 : _b.currentTime) ?? 0;
   }
   /**
-   * 添加音频块（仅用于流式播放）
+   * Add audio chunk (only for streaming playback)
+   * @internal
    */
   addAudioChunk(audio, isLast = false) {
     if (this.useStreaming && this.streamingPlayer) {
@@ -7958,7 +7985,8 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
   }
   /**
-   * 暂停播放
+   * Pause playback
+   * @internal
    */
   pause() {
     var _a;
@@ -7971,7 +7999,8 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
   }
   /**
-   * 继续播放
+   * Resume playback
+   * @internal
    */
   async resume() {
     var _a;
@@ -7984,9 +8013,10 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
   }
   /**
-   * 设置音量 (0.0 - 1.0)
-   * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-   * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+   * Set volume (0.0 - 1.0)
+   * Note: This only controls avatar audio player volume, does not affect system volume
+   * @param volume Volume value, range 0.0 to 1.0 (0.0 is mute, 1.0 is max volume)
+   * @internal
    */
   setVolume(volume) {
     if (this.useStreaming && this.streamingPlayer) {
@@ -7998,8 +8028,9 @@ const _AnimationPlayer = class _AnimationPlayer {
     }
   }
   /**
-   * 获取当前音量
-   * @returns 当前音量值 (0.0 - 1.0)
+   * Get current volume
+   * @returns Current volume value (0.0 - 1.0)
+   * @internal
    */
   getVolume() {
     var _a;
@@ -8009,6 +8040,10 @@ const _AnimationPlayer = class _AnimationPlayer {
       return ((_a = this.audio) == null ? void 0 : _a.volume) ?? 1;
     }
   }
+  /**
+   * Dispose and cleanup
+   * @internal
+   */
   dispose() {
     this.stop();
     if (this.audio) {
@@ -9496,7 +9531,7 @@ class AvatarSDK {
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.70");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.72");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
@@ -10487,7 +10522,7 @@ class EventEmitter {
   }
 }
 class AnimationWebSocketClient extends EventEmitter {
-  // v2 协议：标记会话是否已配置
+  // v2 protocol: mark if session is configured
   constructor(options) {
     super();
     __publicField(this, "wsUrl");
@@ -10509,7 +10544,8 @@ class AnimationWebSocketClient extends EventEmitter {
     this.clientId = options.clientId;
   }
   /**
-   * 连接WebSocket
+   * Connect WebSocket
+   * @internal
    */
   async connect(characterId) {
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
@@ -10537,7 +10573,8 @@ class AnimationWebSocketClient extends EventEmitter {
     }
   }
   /**
-   * 断开连接
+   * Disconnect
+   * @internal
    */
   disconnect() {
     if (this.ws) {
@@ -10557,8 +10594,9 @@ class AnimationWebSocketClient extends EventEmitter {
     logger.log("[AnimationWebSocketClient] Disconnected");
   }
   /**
-   * 发送音频数据
-   * @param conversationId - 会话ID（在 protobuf 协议中映射为 reqId 字段）
+   * Send audio data
+   * @param conversationId - Conversation ID (mapped to reqId field in protobuf protocol)
+   * @internal
    */
   sendAudioData(conversationId, audioData, end) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -10596,25 +10634,28 @@ class AnimationWebSocketClient extends EventEmitter {
     }
   }
   /**
-   * 生成会话ID
-   * 使用统一的会话ID生成规则：YYYYMMDDHHmmss_nanoid
+   * Generate conversation ID
+   * Uses unified conversation ID generation rule: YYYYMMDDHHmmss_nanoid
+   * @internal
    */
   generateConversationId() {
     return idManager.generateNewConversationId();
   }
   /**
-   * 获取连接状态
+   * Get connection state
+   * @internal
    */
   isConnected() {
     return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
   }
   /**
-   * 获取当前角色ID
+   * Get current character ID
+   * @internal
    */
   getCurrentCharacterId() {
     return this.currentCharacterId;
   }
-  // ========== 私有方法 ==========
+  // ========== Private Methods ==========
   buildWebSocketUrl(characterId) {
     const url = new URL(this.wsUrl);
     url.searchParams.set("id", characterId);
@@ -10742,7 +10783,8 @@ class AnimationWebSocketClient extends EventEmitter {
     });
   }
   /**
-   * 清理 URL 用于日志记录（隐藏敏感信息）
+   * Sanitize URL for logging (hide sensitive information)
+   * @internal
    */
   sanitizeUrlForLog(url) {
     try {
@@ -10761,7 +10803,8 @@ class AnimationWebSocketClient extends EventEmitter {
     }
   }
   /**
-   * v2 协议：配置会话（发送采样率等参数）
+   * v2 protocol: configure session (send sample rate and other parameters)
+   * @internal
    */
   configureSession() {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -10775,7 +10818,7 @@ class AnimationWebSocketClient extends EventEmitter {
         clientConfigureSession: {
           sampleRate: audioFormatConfig.sampleRate,
           bitrate: 0,
-          // 根据实际需求设置
+          // Set according to actual requirements
           audioFormat: AudioFormat.AUDIO_FORMAT_PCM_S16LE,
           transportCompression: TransportCompression.TRANSPORT_COMPRESSION_NONE
         }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-CvW_c7G-.js";
+import { b, c, m, f, d, j, g, C, i, D, E, k, h, L, R, n } from "./index-BginsqFH.js";
 export {
   b as Avatar,
   c as AvatarController,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.70",
+  "version": "1.0.0-beta.72",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",