@spatialwalk/avatarkit 1.0.0-beta.67 → 1.0.0-beta.69

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.69] - 2026-01-17
+
+### 🔧 Improvements
+- **API Documentation** - All public API comments are now in English with JSDoc support for better IDE IntelliSense
+- **Type Safety** - Removed internal types from public API exports, using `KeyframeData` instead of `Flame`
+- **Build Configuration** - JSDoc comments are now preserved in generated `.d.ts` files
+
+### 📚 Documentation
+- Enhanced audio data format documentation with WAV and MP3 processing examples
+
+## [1.0.0-beta.68] - 2026-01-17
+
+### 🐛 Bugfixes
+- **Vite Plugin WASM File Detection** - Fixed Vite plugin not finding WASM files with hash in consuming projects
+  - Plugin now reads JS glue file to extract referenced WASM filename (including hash)
+  - Ensures correct WASM file is copied to match JS glue file references
+  - Prevents 404 errors when WASM files have content-based hashes
+  - Fixes issue where `avatar_core_wasm.wasm` was not found after adding hash support
+
 ## [1.0.0-beta.67] - 2026-01-17
 
 ### 🐛 Bugfixes
@@ -123,7 +145,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ✨ New Features
 - **Eye Tracking Control** - Added `eyeTrackingEnabled` parameter to `PostProcessingConfig`, allowing external control of eye tracking enable/disable state in real-time
-- **Point Count API** - Added `getPointCount()` method to `AvatarController` to get the point cloud count of the current character
+- **Point Count API** - Added `getPointCount()` method to `AvatarController` to get the point cloud count of the current avatar
 
 ## [1.0.0-beta.54] - 2025-01-05
 
@@ -153,7 +175,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.50] - 2025-01-05
 
 ### 🔧 Performance Improvements
-- **Removed CORS Preflight for Meta API** - Removed authentication headers (`X-App-Id` and `Authorization`) and unnecessary `Content-Type` header from character metadata API requests. This eliminates CORS preflight requests for simple GET requests, improving loading performance.
+- **Removed CORS Preflight for Meta API** - Removed authentication headers (`X-App-Id` and `Authorization`) and unnecessary `Content-Type` header from avatar metadata API requests. This eliminates CORS preflight requests for simple GET requests, improving loading performance.
 
 ## [1.0.0-beta.49] - 2025-01-05
 
@@ -163,7 +185,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.48] - 2025-01-05
 
 ### ✨ New Features
-- **PWA Cache Management** - Added automatic PWA cache management for character and template resources to improve loading performance
+- **PWA Cache Management** - Added automatic PWA cache management for avatar and template resources to improve loading performance
 
 ### 🔧 Performance Improvements
 - **Cache Hit Rate Metrics** - Resource downloads now report cache status for analytics
@@ -171,7 +193,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.47] - 2025-12-29
 
 ### 🐛 Bugfix
-- **Avatar Meta Update** - Fixed issue where cached Avatar instances would return stale character metadata even when the latest metadata was fetched. Now the character metadata is always updated to the latest version when loading an avatar, even if the version number hasn't changed.
+- **Avatar Meta Update** - Fixed issue where cached Avatar instances would return stale avatar metadata even when the latest metadata was fetched. Now the avatar metadata is always updated to the latest version when loading an avatar, even if the version number hasn't changed.
 
 ## [1.0.0-beta.46] - 2025-12-29
 
@@ -273,12 +295,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.31] - 2025-12-16
 
 ### 🐛 Bugfix
-- **Environment CORS Issue** - Fixed CORS issues when requesting configuration and character data APIs. SDK now provides default configuration fallback when config requests fail, ensuring smooth operation across different environments.
+- **Environment CORS Issue** - Fixed CORS issues when requesting configuration and avatar data APIs. SDK now provides default configuration fallback when config requests fail, ensuring smooth operation across different environments.
 
 ## [1.0.0-beta.30] - 2025-12-15
 
 ### 🐛 Bugfix
-- **Template Resources Duplicate Download** - Fixed issue where template resources were being re-downloaded for each new character load. Template resources are now only loaded once during SDK initialization and reused for all characters.
+- **Template Resources Duplicate Download** - Fixed issue where template resources were being re-downloaded for each new avatar load. Template resources are now only loaded once during SDK initialization and reused for all avatars.
 
 ## [1.0.0-beta.29] - 2025-12-15
 
@@ -451,14 +473,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ✨ New Features
 - **Multi-AvatarView Support** - SDK now supports multiple `AvatarView` instances simultaneously
-  - Each `AvatarView` instance can manage its own character independently
-  - Multiple characters can be displayed and controlled at the same time
+  - Each `AvatarView` instance can manage its own avatar independently
+  - Multiple avatars can be displayed and controlled at the same time
   - Each instance maintains its own rendering context, playback state, and network connection
   - Removed the previous limitation of "only one AvatarView instance at a time"
 
 ### 📚 Documentation
-- Updated README.md to reflect multi-character support capabilities
-- Added multi-character usage examples
+- Updated README.md to reflect multi-avatar support capabilities
+- Added multi-avatar usage examples
 - Removed outdated limitation notes about single AvatarView instance
 
 ---
@@ -469,7 +491,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added authentication support for API requests
   - `appId` is now automatically included in HTTP headers (`X-App-Id`) and WebSocket URL query parameters
   - `sessionToken` is now automatically included in HTTP headers (`Authorization: Bearer {token}`) and WebSocket URL query parameters
-  - All network requests (character loading, resource downloads, WebSocket connections) now include authentication credentials
+  - All network requests (avatar loading, resource downloads, WebSocket connections) now include authentication credentials
 
 ### 🔧 Improvements
 - Fixed canvas resize handling for different aspect ratios

package/README.md

@@ -6,7 +6,7 @@ Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supportin
 
 - **3D Gaussian Splatting Rendering** - Based on the latest point cloud rendering technology, providing high-quality 3D virtual avatars
 - **Audio-Driven Real-Time Animation Rendering** - Users provide audio data, SDK handles receiving animation data and rendering
-- **Multi-Character Support** - Support multiple avatar instances simultaneously, each with independent state and rendering
+- **Multi-Avatar Support** - Support multiple avatar instances simultaneously, each with independent state and rendering
 - **WebGPU/WebGL Dual Rendering Backend** - Automatically selects the best rendering backend for compatibility
 - **WASM High-Performance Computing** - Uses C++ compiled WebAssembly modules for geometric calculations
 - **TypeScript Support** - Complete type definitions and IntelliSense
@@ -43,7 +43,11 @@ export default defineConfig({
 
 - ✅ **开发服务器**：自动设置 WASM 文件的正确 MIME 类型 (`application/wasm`)
 - ✅ **构建时**：自动复制 WASM 文件到 `dist/assets/` 目录
-- ✅ **Cloudflare Pages**：自动生成 `_headers` 文件
+  - 智能检测：从 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` 等选项
 
 ### 手动配置（不使用插件）
@@ -125,7 +129,7 @@ await AvatarSDK.initialize('your-app-id', configuration)
 // Set sessionToken (if needed, call separately)
 // AvatarSDK.setSessionToken('your-session-token')
 
-// 2. Load character
+// 2. Load avatar
 const avatarManager = AvatarManager.shared
 const avatar = await avatarManager.load('character-id', (progress) => {
   console.log(`Loading progress: ${progress.progress}%`)
@@ -149,7 +153,11 @@ button.addEventListener('click', async () => {
   await avatarView.controller.start()
   
   // 6. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
-  const audioData = new ArrayBuffer(1024) // Example: PCM16 audio data at configured sample rate
+  // audioData: ArrayBuffer or Uint8Array containing PCM16 audio samples
+  // - PCM files: Can be directly read as ArrayBuffer
+  // - WAV files: Extract PCM data from WAV format (may require resampling)
+  // - MP3 files: Decode first (e.g., using AudioContext.decodeAudioData()), then convert to PCM16
+  const audioData = new ArrayBuffer(1024) // Placeholder: Replace with actual PCM16 audio data
   avatarView.controller.send(audioData, false) // Send audio data
   avatarView.controller.send(audioData, true) // end=true marks the end of current conversation round
 })
@@ -159,7 +167,7 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
-// 1-3. Same as SDK mode (initialize SDK, load character)
+// 1-3. Same as SDK mode (initialize SDK, load avatar)
 
 // 3. Create view with Host mode
 const container = document.getElementById('avatar-container')
@@ -197,7 +205,7 @@ The SDK uses a three-layer architecture for clear separation of concerns:
 ### Core Components
 
 - **AvatarSDK** - SDK initialization and management
-- **AvatarManager** - Character resource loading and management
+- **AvatarManager** - Avatar resource loading and management
 - **AvatarView** - 3D rendering view (rendering layer)
 - **AvatarController** - Audio/animation playback controller (playback layer)
 
@@ -284,11 +292,87 @@ RenderSystem → WebGPU/WebGL → Canvas rendering
 - **Byte Order**: Little-endian
 
 **Audio Data Format:**
-- Each sample is 2 bytes (16-bit)
+- Each sample is 2 bytes (16-bit signed integer, little-endian)
 - Audio data should be provided as `ArrayBuffer` or `Uint8Array`
 - For example, with 16kHz sample rate: 1 second of audio = 16000 samples × 2 bytes = 32000 bytes
 - For 48kHz sample rate: 1 second of audio = 48000 samples × 2 bytes = 96000 bytes
 
+**Audio Data Source:**
+The `audioData` parameter represents raw PCM16 audio samples in the configured sample rate and mono format. Common audio sources include:
+- **PCM files**: Raw PCM16 files can be directly read as `ArrayBuffer` or `Uint8Array` and sent to the SDK (ensure sample rate matches configuration)
+- **WAV files**: WAV files contain PCM16 audio data in their data chunk. After extracting the PCM data from the WAV file format, it can be sent to the SDK (may require resampling if sample rate differs)
+- **MP3 files**: MP3 files need to be decoded first (e.g., using `AudioContext.decodeAudioData()` or a decoder library), then converted from the decoded format to PCM16 before sending to the SDK
+- **Microphone input**: Real-time microphone audio needs to be captured and converted to PCM16 format at the configured sample rate before sending
+- **Other audio sources**: Any audio source must be converted to mono PCM16 format at the configured sample rate before sending
+
+**Example: Processing WAV and MP3 Files:**
+```typescript
+// WAV file processing
+async function processWAVFile(wavFile: File): Promise<ArrayBuffer> {
+  const arrayBuffer = await wavFile.arrayBuffer()
+  const view = new DataView(arrayBuffer)
+  
+  // WAV format: Skip header (usually 44 bytes for standard WAV)
+  // Check RIFF header
+  if (view.getUint32(0, true) !== 0x46464952) { // "RIFF"
+    throw new Error('Invalid WAV file')
+  }
+  
+  // Find "data" chunk (offset may vary)
+  let dataOffset = 44 // Standard WAV header size
+  // For non-standard WAV files, you may need to search for "data" chunk
+  // This is a simplified example - production code should parse chunks properly
+  
+  const pcmData = arrayBuffer.slice(dataOffset)
+  return pcmData
+}
+
+// MP3 file processing
+async function processMP3File(mp3File: File, targetSampleRate: number): Promise<ArrayBuffer> {
+  const arrayBuffer = await mp3File.arrayBuffer()
+  const audioContext = new AudioContext({ sampleRate: targetSampleRate })
+  
+  // Decode MP3 to AudioBuffer
+  const audioBuffer = await audioContext.decodeAudioData(arrayBuffer.slice(0))
+  
+  // Convert AudioBuffer to PCM16 ArrayBuffer
+  const length = audioBuffer.length
+  const channels = audioBuffer.numberOfChannels
+  const pcm16Buffer = new ArrayBuffer(length * 2)
+  const pcm16View = new DataView(pcm16Buffer)
+  
+  // Mix down to mono if stereo
+  const sourceData = channels === 1 
+    ? audioBuffer.getChannelData(0)
+    : new Float32Array(length)
+  
+  if (channels > 1) {
+    const leftChannel = audioBuffer.getChannelData(0)
+    const rightChannel = audioBuffer.getChannelData(1)
+    for (let i = 0; i < length; i++) {
+      sourceData[i] = (leftChannel[i] + rightChannel[i]) / 2 // Mix to mono
+    }
+  }
+  
+  // Convert float32 (-1.0 to 1.0) to int16 (-32768 to 32767)
+  for (let i = 0; i < length; i++) {
+    const sample = Math.max(-1, Math.min(1, sourceData[i])) // Clamp
+    const int16Sample = sample < 0 ? sample * 0x8000 : sample * 0x7FFF
+    pcm16View.setInt16(i * 2, int16Sample, true) // little-endian
+  }
+  
+  audioContext.close()
+  return pcm16Buffer
+}
+
+// Usage example:
+// const wavPcmData = await processWAVFile(wavFile)
+// avatarView.controller.send(wavPcmData, false)
+//
+// const mp3PcmData = await processMP3File(mp3File, 16000) // 16kHz
+// avatarView.controller.send(mp3PcmData, false)
+```
+
 **Resampling:**
 - If your audio source is at a different sample rate, you must resample it to match the configured sample rate before sending to the SDK
 - For high-quality resampling, we recommend using Web Audio API's `OfflineAudioContext` with anti-aliasing filtering
@@ -345,20 +429,20 @@ AvatarSDK.cleanup()
 
 ### AvatarManager
 
-Character resource manager, responsible for downloading, caching, and loading character data. Use the singleton instance via `AvatarManager.shared`.
+Avatar resource manager, responsible for downloading, caching, and loading avatar data. Use the singleton instance via `AvatarManager.shared`.
 
 ```typescript
 // Get singleton instance
 const manager = AvatarManager.shared
 
-// Load character
+// Load avatar
 const avatar = await manager.load(
   characterId: string, 
   onProgress?: (progress: LoadProgressInfo) => void
 )
 
 // Clear cache
-manager.clearCache()
+manager.clearAll()
 ```
 
 ### AvatarView
@@ -402,19 +486,19 @@ avatarView.transform = { x, y, scale }
 // - y: Vertical offset in normalized coordinates (-1 to 1, where -1 = bottom edge, 0 = center, 1 = top edge)
 // - scale: Scale factor (1.0 = original size, 2.0 = double size, 0.5 = half size)
 
-// Cleanup resources (must be called before switching characters)
+// Cleanup resources (must be called before switching avatars)
 avatarView.dispose()
 ```
 
-**Character Switching Example:**
+**Avatar Switching Example:**
 
 ```typescript
-// To switch characters, simply dispose the old view and create a new one
+// To switch avatars, simply dispose the old view and create a new one
 if (currentAvatarView) {
   currentAvatarView.dispose()
 }
 
-// Load new character
+// Load new avatar
 const newAvatar = await avatarManager.load('new-character-id')
 
 // Create new AvatarView
@@ -444,7 +528,7 @@ button.addEventListener('click', async () => {
   // Start WebSocket service
   await avatarView.controller.start()
   
-  // Send audio data (must be 16kHz mono PCM16 format)
+  // Send audio data (must be mono PCM16 format matching configured sample rate)
   const conversationId = avatarView.controller.send(audioData: ArrayBuffer, end: boolean)
   // Returns: conversationId - Conversation ID for this conversation session
   // end: false (default) - Continue sending audio data for current conversation
@@ -466,9 +550,9 @@ button.addEventListener('click', async () => {
   // Initialize audio context - MUST be in user gesture context
   await avatarView.controller.initializeAudioContext()
   
-  // Stream audio chunks (must be 16kHz mono PCM16 format)
+  // Stream audio chunks (must be mono PCM16 format matching configured sample rate)
   const conversationId = avatarView.controller.yieldAudioData(
-    data: Uint8Array,               // Audio chunk data
+    data: Uint8Array,               // Audio chunk data (PCM16 format)
     isLast: boolean = false         // Whether this is the last chunk
   )
   // Returns: conversationId - Conversation ID for this audio session
@@ -728,7 +812,7 @@ avatarView.dispose() // Automatically cleans up all resources
 ### Memory Optimization
 
 - SDK automatically manages WASM memory allocation
-- Supports dynamic loading/unloading of character and animation resources
+- Supports dynamic loading/unloading of avatar and animation resources
 - Provides memory usage monitoring interface
 
 ## 🌐 Browser Compatibility

package/dist/{StreamingAudioPlayer-CD9jBs6B.js → StreamingAudioPlayer-DiIRp5nx.js}

@@ -1,32 +1,52 @@
 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-GRm00rtd.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-BT9yxWW8.js";
 class StreamingAudioPlayer {
+  // 标记是否正在恢复 AudioContext，避免并发恢复请求
   constructor(options) {
+    // AudioContext is managed internally
     __publicField(this, "audioContext", null);
     __publicField(this, "sampleRate");
     __publicField(this, "channelCount");
     __publicField(this, "debug");
+    // Session-level state
     __publicField(this, "sessionId");
     __publicField(this, "sessionStartTime", 0);
+    // AudioContext time when session started
     __publicField(this, "pausedTimeOffset", 0);
+    // Accumulated paused time
     __publicField(this, "pausedAt", 0);
+    // Time when paused
     __publicField(this, "pausedAudioContextTime", 0);
+    // audioContext.currentTime when paused (for resume calculation)
     __publicField(this, "scheduledTime", 0);
+    // Next chunk schedule time in AudioContext time
+    // Playback state
     __publicField(this, "isPlaying", false);
     __publicField(this, "isPaused", false);
     __publicField(this, "autoStartEnabled", true);
+    // Control whether to auto-start when buffer is ready
     __publicField(this, "autoContinue", false);
+    // 标记是否应该自动继续播放（当 end=false 且无数据时自动暂停后使用）
+    // 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 的结束时间（相对时间）
     __publicField(this, "lastGetCurrentTimeLog", 0);
+    // 上次记录 getCurrentTime 日志的时间戳（用于节流）
+    // 跟踪每个已调度的 chunk 的开始时间（绝对时间）和持续时间，用于准确计算当前播放时间
     __publicField(this, "scheduledChunkInfo", []);
+    // Volume control
     __publicField(this, "gainNode", null);
     __publicField(this, "volume", 1);
+    // Default volume 1.0 (0.0 - 1.0)
+    // Event callbacks
     __publicField(this, "onEndedCallback");
+    // AudioContext state management
     __publicField(this, "stateChangeHandler");
     __publicField(this, "isResuming", false);
     this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
@@ -34,6 +54,9 @@ class StreamingAudioPlayer {
     this.channelCount = (options == null ? void 0 : options.channelCount) ?? 1;
     this.debug = (options == null ? void 0 : options.debug) ?? false;
   }
+  /**
+   * Initialize audio context (create and ensure it's ready)
+   */
   async initialize() {
     if (this.audioContext) {
       return;
@@ -72,6 +95,15 @@ class StreamingAudioPlayer {
       throw error instanceof Error ? error : new Error(message);
     }
   }
+  /**
+   * 确保 AudioContext 正在运行（如果被暂停则自动恢复）
+   * 只在正在播放且未暂停时自动恢复，避免干扰正常的暂停/恢复逻辑
+   * 
+   * 优化：
+   * - 快速路径：如果已经是 running 状态，直接返回
+   * - 避免并发恢复：使用 isResuming 标志防止重复恢复请求
+   * - 处理 closed 状态：如果 AudioContext 已关闭，无法恢复
+   */
   async ensureAudioContextRunning() {
     if (!this.audioContext) {
       return;
@@ -120,6 +152,9 @@ class StreamingAudioPlayer {
       }
     }
   }
+  /**
+   * Add audio chunk (16-bit PCM)
+   */
   addChunk(pcmData, isLast = false) {
     if (!this.audioContext) {
       logger.error("AudioContext not initialized");
@@ -157,6 +192,9 @@ class StreamingAudioPlayer {
       this.log("[StreamingAudioPlayer] Not playing and no chunks, waiting for more chunks");
     }
   }
+  /**
+   * Start new session (stop current and start fresh)
+   */
   async startNewSession(audioChunks) {
     this.stop();
     this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
@@ -173,6 +211,9 @@ class StreamingAudioPlayer {
       this.addChunk(chunk.data, chunk.isLast);
     }
   }
+  /**
+   * Start playback
+   */
   async startPlayback() {
     if (!this.audioContext) {
       this.log("[StreamingAudioPlayer] Cannot start playback: AudioContext not initialized");
@@ -198,11 +239,17 @@ class StreamingAudioPlayer {
     });
     this.scheduleAllChunks();
   }
+  /**
+   * Schedule all pending chunks
+   */
   scheduleAllChunks() {
     while (this.scheduledChunks < this.audioChunks.length) {
       this.scheduleNextChunk();
     }
   }
+  /**
+   * Schedule next audio chunk
+   */
   scheduleNextChunk() {
     if (!this.audioContext) {
       this.log("[StreamingAudioPlayer] Cannot schedule chunk: AudioContext not initialized");
@@ -284,6 +331,10 @@ class StreamingAudioPlayer {
       });
     }
   }
+  /**
+   * Convert PCM data to AudioBuffer
+   * Input: 16-bit PCM (int16), Output: AudioBuffer (float32 [-1, 1])
+   */
   pcmToAudioBuffer(pcmData) {
     if (!this.audioContext) {
       return null;
@@ -319,6 +370,10 @@ class StreamingAudioPlayer {
     }
     return audioBuffer;
   }
+  /**
+   * Get current playback time (seconds)
+   * 返回实际播放的音频总时长
+   */
   getCurrentTime() {
     if (!this.audioContext || !this.isPlaying) {
       return 0;
@@ -346,6 +401,10 @@ class StreamingAudioPlayer {
     }
     return Math.max(0, totalPlayedDuration);
   }
+  /**
+   * Get total duration of buffered audio (seconds)
+   * 计算所有已缓冲 chunk 的总时长
+   */
   getBufferedDuration() {
     if (!this.audioContext) {
       return 0;
@@ -357,10 +416,17 @@ class StreamingAudioPlayer {
     }
     return totalDuration;
   }
+  /**
+   * Get current AudioContext time
+   * @returns Current AudioContext time in seconds, or 0 if AudioContext is not initialized
+   */
   getAudioContextTime() {
     var _a;
     return ((_a = this.audioContext) == null ? void 0 : _a.currentTime) ?? 0;
   }
+  /**
+   * Pause playback
+   */
   pause() {
     if (!this.isPlaying || this.isPaused || !this.audioContext) {
       return;
@@ -380,6 +446,9 @@ class StreamingAudioPlayer {
       audioContextState: this.audioContext.state
     });
   }
+  /**
+   * Resume playback
+   */
   async resume() {
     if (!this.isPaused || !this.audioContext || !this.isPlaying) {
       return;
@@ -407,6 +476,9 @@ class StreamingAudioPlayer {
       audioContextState: this.audioContext.state
     });
   }
+  /**
+   * Stop playback
+   */
   stop() {
     if (!this.audioContext) {
       return;
@@ -438,10 +510,17 @@ class StreamingAudioPlayer {
     this.autoContinue = false;
     this.log("[StreamingAudioPlayer] Playback stopped, state reset");
   }
+  /**
+   * Enable or disable auto-start (for delayed start scenarios)
+   */
   setAutoStart(enabled) {
     this.autoStartEnabled = enabled;
     this.log(`Auto-start ${enabled ? "enabled" : "disabled"}`);
   }
+  /**
+   * Start playback manually (for delayed start scenarios)
+   * This allows starting playback after transition animation completes
+   */
   play() {
     if (this.isPlaying) {
       return;
@@ -451,18 +530,30 @@ class StreamingAudioPlayer {
       logger.errorWithError("[StreamingAudioPlayer] Failed to start playback from play():", err);
     });
   }
+  /**
+   * Mark playback as ended
+   */
   markEnded() {
     var _a;
     this.log("Playback ended");
     this.isPlaying = false;
     (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
   }
+  /**
+   * Set ended callback
+   */
   onEnded(callback) {
     this.onEndedCallback = callback;
   }
+  /**
+   * Check if playing
+   */
   isPlayingNow() {
     return this.isPlaying && !this.isPaused;
   }
+  /**
+   * Dispose and cleanup
+   */
   dispose() {
     this.stop();
     if (this.audioContext && this.stateChangeHandler) {
@@ -484,6 +575,11 @@ class StreamingAudioPlayer {
     this.onEndedCallback = void 0;
     this.log("StreamingAudioPlayer disposed");
   }
+  /**
+   * Flush buffered audio
+   * - hard: stops all playing sources and clears all chunks
+   * - soft (default): clears UNSCHEDULED chunks only
+   */
   flush(options) {
     const hard = (options == null ? void 0 : options.hard) === true;
     if (hard) {
@@ -501,6 +597,11 @@ class StreamingAudioPlayer {
     }
     this.log("Flushed (soft)", { remainingScheduled: this.scheduledChunks });
   }
+  /**
+   * 设置音量 (0.0 - 1.0)
+   * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
+   * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+   */
   setVolume(volume) {
     if (volume < 0 || volume > 1) {
       logger.warn(`[StreamingAudioPlayer] Volume out of range: ${volume}, clamping to [0, 1]`);
@@ -511,9 +612,16 @@ class StreamingAudioPlayer {
       this.gainNode.gain.value = volume;
     }
   }
+  /**
+   * 获取当前音量
+   * @returns 当前音量值 (0.0 - 1.0)
+   */
   getVolume() {
     return this.volume;
   }
+  /**
+   * Debug logging
+   */
   log(message, data) {
     if (this.debug) {
       logger.log(`[StreamingAudioPlayer] ${message}`, data || "");

package/dist/animation/AnimationWebSocketClient.d.ts

@@ -20,15 +20,41 @@ export declare class AnimationWebSocketClient extends EventEmitter {
     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;

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

@@ -1,3 +1,6 @@
+/**
+ * Simple Event Emitter
+ */
 type EventHandler = (...args: any[]) => void;
 export declare class EventEmitter {
     private events;