@spatialwalk/avatarkit 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -1,25 +1,25 @@
 # SPAvatarKit SDK
 
-基于 3D Gaussian Splatting 的实时虚拟人物头像渲染 SDK，支持音频驱动的动画渲染和高质量 3D 渲染。
+Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supporting audio-driven animation rendering and high-quality 3D rendering.
 
-## 🚀 特性
+## 🚀 Features
 
-- **3D Gaussian Splatting 渲染** - 基于最新的点云渲染技术，提供高质量的 3D 虚拟人物
-- **音频驱动的实时动画渲染** - 用户提供音频数据，SDK 负责接收动画数据并渲染
-- **WebGPU/WebGL 双渲染后端** - 自动选择最佳渲染后端，确保兼容性
-- **WASM 高性能计算** - 使用 C++ 编译的 WebAssembly 模块进行几何计算
-- **TypeScript 支持** - 完整的类型定义和智能提示
-- **模块化架构** - 清晰的组件分离，易于集成和扩展
+- **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
+- **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
+- **Modular Architecture** - Clear component separation, easy to integrate and extend
 
-## 📦 安装
+## 📦 Installation
 
 ```bash
 npm install @spatialwalk/avatarkit
 ```
 
-## 🎯 快速开始
+## 🎯 Quick Start
 
-### 基础使用
+### Basic Usage
 
 ```typescript
 import { 
@@ -30,173 +30,356 @@ import {
   Environment 
 } from '@spatialwalk/avatarkit'
 
-// 1. 初始化 SDK
+// 1. Initialize SDK
 const configuration: Configuration = {
   environment: Environment.test,
 }
 
 await AvatarKit.initialize('your-app-id', configuration)
 
-// 设置 sessionToken（如果需要，单独调用）
+// Set sessionToken (if needed, call separately)
 // AvatarKit.setSessionToken('your-session-token')
 
-// 2. 加载角色
+// 2. Load character
 const avatarManager = new AvatarManager()
 const avatar = await avatarManager.load('character-id', (progress) => {
   console.log(`Loading progress: ${progress.progress}%`)
 })
 
-// 3. 创建视图（自动创建 Canvas 和 AvatarController）
+// 3. Create view (automatically creates Canvas and AvatarController)
+// Network mode (default)
 const container = document.getElementById('avatar-container')
-const avatarView = new AvatarView(avatar, container)
+const avatarView = new AvatarView(avatar, {
+  container: container,
+  playbackMode: 'network' // Optional, 'network' is default
+})
 
-// 4. 启动实时通信
+// 4. Start real-time communication (network mode only)
 await avatarView.avatarController.start()
 
-// 5. 发送音频数据
-// 如果音频是 Uint8Array，可以使用 slice().buffer 转换为 ArrayBuffer
-const audioUint8 = new Uint8Array(1024) // 示例：音频数据
-const audioData = audioUint8.slice().buffer // 简化的转换方式，适用于 ArrayBuffer 和 SharedArrayBuffer
-avatarView.avatarController.send(audioData, false) // 发送音频数据，积累到一定量后会自动开始播放
-avatarView.avatarController.send(audioData, true) // end=true 表示立即返回动画数据，不再积累
+// 5. Send audio data (network mode)
+// ⚠️ Important: Audio must be 16kHz mono PCM16 format
+// If audio is Uint8Array, you can use slice().buffer to convert to ArrayBuffer
+const audioUint8 = new Uint8Array(1024) // Example: 16kHz PCM16 audio data (512 samples = 1024 bytes)
+const audioData = audioUint8.slice().buffer // Simplified conversion, works for ArrayBuffer and SharedArrayBuffer
+avatarView.avatarController.send(audioData, false) // Send audio data, will automatically start playing after accumulating enough data
+avatarView.avatarController.send(audioData, true) // end=true means immediately return animation data, no longer accumulating
+```
+
+### External Data Mode Example
+
+```typescript
+import { AvatarPlaybackMode } from '@spatialwalk/avatarkit'
+
+// 1-3. Same as network mode (initialize SDK, load character)
+
+// 3. Create view with external data mode
+const container = document.getElementById('avatar-container')
+const avatarView = new AvatarView(avatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.external
+})
+
+// 4. Start playback with initial data (obtained from your service)
+// Note: Audio and animation data should be obtained from your backend service
+const initialAudioChunks = [{ data: audioData1, isLast: false }, { data: audioData2, isLast: false }]
+const initialKeyframes = animationData1 // Animation keyframes from your service
+
+await avatarView.avatarController.play(initialAudioChunks, initialKeyframes)
+
+// 5. Stream additional data as needed
+avatarView.avatarController.sendAudioChunk(audioData3, false)
+avatarView.avatarController.sendKeyframes(animationData2)
 ```
 
-### 完整示例
+### Complete Examples
 
-查看 GitHub 仓库中的示例代码了解完整的使用流程。
+Check the example code in the GitHub repository for complete usage flows for both modes.
 
-**示例项目：** [Avatarkit-web-demo](https://github.com/spatialwalk/Avatarkit-web-demo)
+**Example Project:** [Avatarkit-web-demo](https://github.com/spatialwalk/Avatarkit-web-demo)
 
-该仓库包含 Vanilla JS、Vue 3 和 React 的完整示例，展示了如何在不同框架中集成和使用 SPAvatarKit SDK。
+This repository contains complete examples for Vanilla JS, Vue 3, and React, demonstrating:
+- Network mode: Real-time audio input with automatic animation data reception
+- External data mode: Custom data sources with manual audio/animation data management
 
-## 🏗️ 架构概览
+## 🏗️ Architecture Overview
 
-### 核心组件
+### Three-Layer Architecture
 
-- **AvatarKit** - SDK 初始化和管理
-- **AvatarManager** - 角色资源加载和管理
-- **AvatarView** - 3D 渲染视图（内部包含 AvatarController）
-- **AvatarController** - 实时通信和数据处理
-- **AvatarCoreAdapter** - WASM 模块适配器
+The SDK uses a three-layer architecture for clear separation of concerns:
+
+1. **Rendering Layer (AvatarView)** - Responsible for 3D rendering only
+2. **Playback Layer (AvatarController)** - Manages audio/animation synchronization and playback
+3. **Network Layer (NetworkLayer)** - Handles WebSocket communication (only in network mode)
+
+### Core Components
+
+- **AvatarKit** - SDK initialization and management
+- **AvatarManager** - Character resource loading and management
+- **AvatarView** - 3D rendering view (rendering layer)
+- **AvatarController** - Audio/animation playback controller (playback layer)
+- **NetworkLayer** - WebSocket communication (network layer, automatically composed in network mode)
+- **AvatarCoreAdapter** - WASM module adapter
+
+### Playback Modes
+
+The SDK supports two playback modes, configured when creating `AvatarView`:
+
+#### 1. Network Mode (Default)
+- SDK handles WebSocket communication automatically
+- Send audio data via `AvatarController.send()`
+- SDK receives animation data from backend and synchronizes playback
+- Best for: Real-time audio input scenarios
+
+#### 2. External Data Mode
+- External components manage their own network/data fetching
+- External components provide both audio and animation data
+- SDK only handles synchronized playback
+- Best for: Custom data sources, pre-recorded content, or custom network implementations
+
+### Data Flow
+
+#### Network Mode Flow
+
+```
+User audio input (16kHz mono PCM16) 
+    ↓
+AvatarController.send() 
+    ↓
+NetworkLayer → WebSocket → Backend processing
+    ↓
+Backend returns animation data (FLAME keyframes) 
+    ↓
+NetworkLayer → AvatarController → AnimationPlayer
+    ↓
+FLAME parameters → AvatarCore.computeFrameFlatFromParams() → Splat data
+    ↓
+AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
+    ↓
+RenderSystem → WebGPU/WebGL → Canvas rendering
+```
 
-### 数据流
+#### External Data Mode Flow
 
 ```
-用户音频输入（16kHz mono PCM） → AvatarController → WebSocket → 后台处理
-                                              ↓
-后台返回动画数据（FLAME 关键帧） → AvatarController → AnimationPlayer
-                                              ↓
-FLAME 参数 → AvatarCore.computeFrameFlatFromParams() → Splat 数据
-                                              ↓
-Splat 数据 → RenderSystem → WebGPU/WebGL → Canvas 渲染
+External data source (audio + animation)
+    ↓
+AvatarController.play(initialAudio, initialKeyframes) // Start playback
+    ↓
+AvatarController.sendAudioChunk() // Stream additional audio
+AvatarController.sendKeyframes() // Stream additional animation
+    ↓
+AvatarController → AnimationPlayer (synchronized playback)
+    ↓
+FLAME parameters → AvatarCore.computeFrameFlatFromParams() → Splat data
+    ↓
+AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
+    ↓
+RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 
-**注意：** 用户需要自己提供音频数据（16kHz mono PCM），SDK 负责接收动画数据并渲染。
+**Note:** 
+- In network mode, users provide audio data, SDK handles network communication and animation data reception
+- In external data mode, users provide both audio and animation data, SDK handles synchronized playback only
+
+### Audio Format Requirements
+
+**⚠️ Important:** The SDK requires audio data to be in **16kHz mono PCM16** format:
+
+- **Sample Rate**: 16kHz (16000 Hz) - This is a backend requirement
+- **Channels**: Mono (single channel)
+- **Format**: PCM16 (16-bit signed integer, little-endian)
+- **Byte Order**: Little-endian
+
+**Audio Data Format:**
+- Each sample is 2 bytes (16-bit)
+- Audio data should be provided as `ArrayBuffer` or `Uint8Array`
+- For example: 1 second of audio = 16000 samples × 2 bytes = 32000 bytes
+
+**Resampling:**
+- If your audio source is at a different sample rate (e.g., 24kHz, 48kHz), you must resample it to 16kHz before sending to the SDK
+- For high-quality resampling, we recommend using Web Audio API's `OfflineAudioContext` with anti-aliasing filtering
+- See example projects for resampling implementation
 
-## 📚 API 参考
+## 📚 API Reference
 
 ### AvatarKit
 
-SDK 的核心管理类，负责初始化和全局配置。
+The core management class of the SDK, responsible for initialization and global configuration.
 
 ```typescript
-// 初始化 SDK
+// Initialize SDK
 await AvatarKit.initialize(appId: string, configuration: Configuration)
 
-// 检查初始化状态
+// Check initialization status
 const isInitialized = AvatarKit.isInitialized
 
-// 清理资源（不再使用时必须调用）
+// Cleanup resources (must be called when no longer in use)
 AvatarKit.cleanup()
 ```
 
 ### AvatarManager
 
-角色资源管理器，负责下载、缓存和加载角色数据。
+Character resource manager, responsible for downloading, caching, and loading character data.
 
 ```typescript
 const manager = new AvatarManager()
 
-// 加载角色
+// Load character
 const avatar = await manager.load(
   characterId: string, 
   onProgress?: (progress: LoadProgressInfo) => void
 )
 
-// 清理缓存
+// Clear cache
 manager.clearCache()
 ```
 
 ### AvatarView
 
-3D 渲染视图，内部自动创建和管理 AvatarController。
+3D rendering view (rendering layer), responsible for 3D rendering only. Internally automatically creates and manages `AvatarController`.
 
-**⚠️ 重要限制：** 目前 SDK 只支持同时存在一个 AvatarView 实例。如果需要切换角色，必须先调用 `dispose()` 方法清理当前的 AvatarView，然后再创建新的实例。
+**⚠️ Important Limitation:** Currently, the SDK only supports one AvatarView instance at a time. If you need to switch characters, you must first call the `dispose()` method to clean up the current AvatarView, then create a new instance.
+
+**Playback Mode Configuration:**
+- The playback mode is fixed when creating `AvatarView` and persists throughout its lifecycle
+- Cannot be changed after creation
 
 ```typescript
-// 创建视图（Canvas 会自动添加到容器中）
-const avatarView = new AvatarView(avatar: Avatar, container?: HTMLElement)
+import { AvatarPlaybackMode } from '@spatialwalk/avatarkit'
+
+// Create view (Canvas is automatically added to container)
+// Network mode (default)
+const container = document.getElementById('avatar-container')
+const avatarView = new AvatarView(avatar: Avatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.network // Optional, default is 'network'
+})
+
+// External data mode
+const avatarView = new AvatarView(avatar: Avatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.external
+})
 
-// 获取 Canvas 元素
+// Get Canvas element
 const canvas = avatarView.getCanvas()
 
-// 设置背景
-avatarView.setBackgroundImage('path/to/image.jpg')
-avatarView.setBackgroundOpaque(true)
+// Get playback mode
+const mode = avatarView.playbackMode // 'network' | 'external'
 
-// 更新相机配置
+// Update camera configuration
 avatarView.updateCameraConfig(cameraConfig: CameraConfig)
 
-// 清理资源（切换角色前必须调用）
+// Cleanup resources (must be called before switching characters)
 avatarView.dispose()
 ```
 
-**切换角色示例：**
+**Character Switching Example:**
 
 ```typescript
-// 切换角色前，必须先清理旧的 AvatarView
+// Before switching characters, must clean up old AvatarView first
 if (currentAvatarView) {
   currentAvatarView.dispose()
   currentAvatarView = null
 }
 
-// 加载新角色
+// Load new character
 const newAvatar = await avatarManager.load('new-character-id')
 
-// 创建新的 AvatarView
-currentAvatarView = new AvatarView(newAvatar, container)
-await currentAvatarView.avatarController.start()
+// Create new AvatarView (with same or different playback mode)
+currentAvatarView = new AvatarView(newAvatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.network
+})
+
+// Network mode: start connection
+if (currentAvatarView.playbackMode === AvatarPlaybackMode.network) {
+  await currentAvatarView.avatarController.start()
+}
 ```
 
 ### AvatarController
 
-实时通信控制器，处理 WebSocket 连接和动画数据。
+Audio/animation playback controller (playback layer), manages synchronized playback of audio and animation. Automatically composes `NetworkLayer` in network mode.
+
+**Two Usage Patterns:**
+
+#### Network Mode Methods
 
 ```typescript
-// 启动连接
+// Start WebSocket service
 await avatarView.avatarController.start()
 
-// 发送音频数据
+// Send audio data (SDK handles receiving animation data automatically)
 avatarView.avatarController.send(audioData: ArrayBuffer, end: boolean)
-// audioData: 音频数据（ArrayBuffer 格式）
-// end: false（默认）- 正常发送音频数据，服务端会积累音频数据，积累到一定量后会自动返回动画数据并开始同步播放动画和音频
-// end: true - 立即返回动画数据，不再积累，用于结束当前对话或需要立即响应的场景
+// audioData: Audio data (ArrayBuffer format, must be 16kHz mono PCM16)
+//   - Sample rate: 16kHz (16000 Hz) - backend requirement
+//   - Format: PCM16 (16-bit signed integer, little-endian)
+//   - Channels: Mono (single channel)
+//   - Example: 1 second = 16000 samples × 2 bytes = 32000 bytes
+// end: false (default) - Normal audio data sending, server will accumulate audio data, automatically returns animation data and starts synchronized playback of animation and audio after accumulating enough data
+// end: true - Immediately return animation data, no longer accumulating, used for ending current conversation or scenarios requiring immediate response
+
+// Close WebSocket service
+avatarView.avatarController.close()
+```
+
+#### External Data Mode Methods
+
+```typescript
+// Start playback with initial audio and animation data
+await avatarView.avatarController.play(
+  initialAudioChunks?: Array<{ data: Uint8Array, isLast: boolean }>,  // Initial audio chunks (16kHz mono PCM16)
+  initialKeyframes?: any[]  // Initial animation keyframes (obtained from your service)
+)
 
-// 打断对话
+// Stream additional audio chunks (after play() is called)
+avatarView.avatarController.sendAudioChunk(
+  data: Uint8Array,               // Audio chunk data
+  isLast: boolean = false         // Whether this is the last chunk
+)
+
+// Stream additional animation keyframes (after play() is called)
+avatarView.avatarController.sendKeyframes(
+  keyframes: any[]                 // Additional animation keyframes (obtained from your service)
+)
+```
+
+#### Common Methods (Both Modes)
+
+```typescript
+// Interrupt current playback (stops and clears data)
 avatarView.avatarController.interrupt()
 
-// 关闭连接
+// Clear all data and resources
+avatarView.avatarController.clear()
+
+// Get connection state (network mode only)
+const isConnected = avatarView.avatarController.connected
+
+// Start service (network mode only)
+await avatarView.avatarController.start()
+
+// Close service (network mode only)
 avatarView.avatarController.close()
 
-// 设置事件回调
-avatarView.avatarController.onConnectionState = (state: ConnectionState) => {}
+// Get current avatar state
+const state = avatarView.avatarController.state
+
+// Set event callbacks
+avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // Network mode only
 avatarView.avatarController.onAvatarState = (state: AvatarState) => {}
 avatarView.avatarController.onError = (error: Error) => {}
-
-// 注意：不支持 sendText() 方法，调用会抛出错误
 ```
 
-## 🔧 配置
+**Important Notes:**
+- `start()` and `close()` are only available in network mode
+- `play()`, `sendAudioChunk()`, and `sendKeyframes()` are only available in external data mode
+- `interrupt()` and `clear()` are available in both modes
+- The playback mode is determined when creating `AvatarView` and cannot be changed
+
+## 🔧 Configuration
 
 ### Configuration
 
@@ -206,14 +389,37 @@ interface Configuration {
 }
 ```
 
-**说明：**
-- `environment`: 指定环境（cn/us/test），SDK 会根据环境自动使用对应的 API 地址和 WebSocket 地址
-- `sessionToken`: 通过 `AvatarKit.setSessionToken()` 单独设置，而不是在 Configuration 中
+**Description:**
+- `environment`: Specifies the environment (cn/us/test), SDK will automatically use the corresponding API address and WebSocket address based on the environment
+- `sessionToken`: Set separately via `AvatarKit.setSessionToken()`, not in Configuration
 
+```typescript
 enum Environment {
-  cn = 'cn',    // 中国区
-  us = 'us',    // 美国区
-  test = 'test' // 测试环境
+  cn = 'cn',    // China region
+  us = 'us',    // US region
+  test = 'test' // Test environment
+}
+```
+
+### AvatarViewOptions
+
+```typescript
+interface AvatarViewOptions {
+  playbackMode?: AvatarPlaybackMode  // Playback mode, default is 'network'
+  container?: HTMLElement            // Canvas container element
+}
+```
+
+**Description:**
+- `playbackMode`: Specifies the playback mode (`'network'` or `'external'`), default is `'network'`
+  - `'network'`: SDK handles WebSocket communication, send audio via `send()`
+  - `'external'`: External components provide audio and animation data, SDK handles synchronized playback
+- `container`: Optional container element for Canvas, if not provided, Canvas will be created but not added to DOM
+
+```typescript
+enum AvatarPlaybackMode {
+  network = 'network',   // Network mode: SDK handles WebSocket communication
+  external = 'external'  // External data mode: External provides data, SDK handles playback
 }
 ```
 
@@ -221,17 +427,17 @@ enum Environment {
 
 ```typescript
 interface CameraConfig {
-  position: [number, number, number]  // 相机位置
-  target: [number, number, number]    // 相机目标
-  fov: number                         // 视野角度
-  near: number                        // 近裁剪面
-  far: number                         // 远裁剪面
-  up?: [number, number, number]       // 上方向
-  aspect?: number                     // 宽高比
+  position: [number, number, number]  // Camera position
+  target: [number, number, number]    // Camera target
+  fov: number                         // Field of view angle
+  near: number                        // Near clipping plane
+  far: number                         // Far clipping plane
+  up?: [number, number, number]       // Up direction
+  aspect?: number                     // Aspect ratio
 }
 ```
 
-## 📊 状态管理
+## 📊 State Management
 
 ### ConnectionState
 
@@ -248,77 +454,77 @@ enum ConnectionState {
 
 ```typescript
 enum AvatarState {
-  idle = 'idle',      // 空闲状态，呈现呼吸态
-  active = 'active',  // 活跃中，等待可播放内容
-  playing = 'playing' // 播放中
+  idle = 'idle',      // Idle state, showing breathing animation
+  active = 'active',  // Active, waiting for playable content
+  playing = 'playing' // Playing
 }
 ```
 
-## 🎨 渲染系统
+## 🎨 Rendering System
 
-SDK 支持两种渲染后端：
+The SDK supports two rendering backends:
 
-- **WebGPU** - 现代浏览器的高性能渲染
-- **WebGL** - 兼容性更好的传统渲染
+- **WebGPU** - High-performance rendering for modern browsers
+- **WebGL** - Better compatibility traditional rendering
 
-渲染系统会自动选择最佳的后端，无需手动配置。
+The rendering system automatically selects the best backend, no manual configuration needed.
 
-## 🔍 调试和监控
+## 🔍 Debugging and Monitoring
 
-### 日志系统
+### Logging System
 
-SDK 内置了完整的日志系统，支持不同级别的日志输出：
+The SDK has a built-in complete logging system, supporting different levels of log output:
 
 ```typescript
 import { logger } from '@spatialwalk/avatarkit'
 
-// 设置日志级别
+// Set log level
 logger.setLevel('verbose') // 'basic' | 'verbose'
 
-// 手动日志输出
+// Manual log output
 logger.log('Info message')
 logger.warn('Warning message')
 logger.error('Error message')
 ```
 
-### 性能监控
+### Performance Monitoring
 
-SDK 提供了性能监控接口，可以监控渲染性能：
+The SDK provides performance monitoring interfaces to monitor rendering performance:
 
 ```typescript
-// 获取渲染性能统计
+// Get rendering performance statistics
 const stats = avatarView.getPerformanceStats()
 
 if (stats) {
-  console.log(`渲染耗时: ${stats.renderTime.toFixed(2)}ms`)
-  console.log(`排序耗时: ${stats.sortTime.toFixed(2)}ms`)
-  console.log(`渲染后端: ${stats.backend}`)
+  console.log(`Render time: ${stats.renderTime.toFixed(2)}ms`)
+  console.log(`Sort time: ${stats.sortTime.toFixed(2)}ms`)
+  console.log(`Rendering backend: ${stats.backend}`)
   
-  // 计算帧率
+  // Calculate frame rate
   const fps = 1000 / stats.renderTime
-  console.log(`帧率: ${fps.toFixed(2)} FPS`)
+  console.log(`Frame rate: ${fps.toFixed(2)} FPS`)
 }
 
-// 定期监控性能
+// Regular performance monitoring
 setInterval(() => {
   const stats = avatarView.getPerformanceStats()
   if (stats) {
-    // 发送到监控服务或显示在 UI 上
+    // Send to monitoring service or display on UI
     console.log('Performance:', stats)
   }
 }, 1000)
 ```
 
-**性能统计说明**：
-- `renderTime`: 总渲染耗时（毫秒），包含排序和 GPU 渲染
-- `sortTime`: 排序耗时（毫秒），使用 Radix Sort 算法对点云进行深度排序
-- `backend`: 当前使用的渲染后端（`'webgpu'` | `'webgl'` | `null`）
+**Performance Statistics Description:**
+- `renderTime`: Total rendering time (milliseconds), includes sorting and GPU rendering
+- `sortTime`: Sorting time (milliseconds), uses Radix Sort algorithm to depth-sort point cloud
+- `backend`: Currently used rendering backend (`'webgpu'` | `'webgl'` | `null`)
 
-## 🚨 错误处理
+## 🚨 Error Handling
 
 ### SPAvatarError
 
-SDK 使用自定义错误类型，提供更详细的错误信息：
+The SDK uses custom error types, providing more detailed error information:
 
 ```typescript
 import { SPAvatarError } from '@spatialwalk/avatarkit'
@@ -334,70 +540,135 @@ try {
 }
 ```
 
-### 错误回调
+### Error Callbacks
 
 ```typescript
 avatarView.avatarController.onError = (error: Error) => {
   console.error('AvatarController error:', error)
-  // 处理错误，比如重连、用户提示等
+  // Handle error, such as reconnection, user notification, etc.
 }
 ```
 
-## 🔄 资源管理
+## 🔄 Resource Management
+
+### Lifecycle Management
 
-### 生命周期管理
+#### Network Mode Lifecycle
 
 ```typescript
-// 初始化
-const avatarView = new AvatarView(avatar, container)
+// Initialize
+const container = document.getElementById('avatar-container')
+const avatarView = new AvatarView(avatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.network
+})
 await avatarView.avatarController.start()
 
-// 使用
+// Use
 avatarView.avatarController.send(audioData, false)
 
-// 清理（切换角色前必须调用）
-avatarView.dispose() // 自动清理所有资源
+// Cleanup
+avatarView.avatarController.close()
+avatarView.dispose() // Automatically cleans up all resources
 ```
 
-**⚠️ 重要提示：** 
-- SDK 目前只支持同时存在一个 AvatarView 实例
-- 切换角色时，必须先调用 `dispose()` 清理旧的 AvatarView，然后再创建新的实例
-- 未正确清理可能导致资源泄漏和渲染错误
+#### External Data Mode Lifecycle
 
-### 内存优化
+```typescript
+// Initialize
+const container = document.getElementById('avatar-container')
+const avatarView = new AvatarView(avatar, {
+  container: container,
+  playbackMode: AvatarPlaybackMode.external
+})
+
+// Use
+const initialAudioChunks = [{ data: audioData1, isLast: false }]
+await avatarView.avatarController.play(initialAudioChunks, initialKeyframes)
+avatarView.avatarController.sendAudioChunk(audioChunk, false)
+avatarView.avatarController.sendKeyframes(keyframes)
+
+// Cleanup
+avatarView.avatarController.clear() // Clear all data and resources
+avatarView.dispose() // Automatically cleans up all resources
+```
 
-- SDK 自动管理 WASM 内存分配
-- 支持角色和动画资源的动态加载/卸载
-- 提供内存使用监控接口
+**⚠️ Important Notes:** 
+- SDK currently only supports one AvatarView instance at a time
+- When switching characters, must first call `dispose()` to clean up old AvatarView, then create new instance
+- Not properly cleaning up may cause resource leaks and rendering errors
+- In network mode, call `close()` before `dispose()` to properly close WebSocket connections
+- In external data mode, call `clear()` before `dispose()` to clear all playback data
 
-### 音频数据发送
+### Memory Optimization
 
-`send()` 方法接收 `ArrayBuffer` 格式的音频数据：
+- SDK automatically manages WASM memory allocation
+- Supports dynamic loading/unloading of character and animation resources
+- Provides memory usage monitoring interface
+
+### Audio Data Sending
+
+#### Network Mode
+
+The `send()` method receives audio data in `ArrayBuffer` format:
+
+**Audio Format Requirements:**
+- **Sample Rate**: 16kHz (16000 Hz) - **Backend requirement, must be exactly 16kHz**
+- **Format**: PCM16 (16-bit signed integer, little-endian)
+- **Channels**: Mono (single channel)
+- **Data Size**: Each sample is 2 bytes, so 1 second of audio = 16000 samples × 2 bytes = 32000 bytes
+
+**Usage:**
+- `audioData`: Audio data (ArrayBuffer format, must be 16kHz mono PCM16)
+- `end=false` (default) - Normal audio data sending, server will accumulate audio data, automatically returns animation data and starts synchronized playback of animation and audio after accumulating enough data
+- `end=true` - Immediately return animation data, no longer accumulating, used for ending current conversation or scenarios requiring immediate response
+- **Important**: No need to wait for `end=true` to start playing, it will automatically start playing after accumulating enough audio data
+
+#### External Data Mode
+
+The `play()` method starts playback with initial data, then use `sendAudioChunk()` to stream additional audio:
+
+**Audio Format Requirements:**
+- Same as network mode: 16kHz mono PCM16 format
+- Audio data should be provided as `Uint8Array` in chunks with `isLast` flag
+
+**Usage:**
+```typescript
+// Start playback with initial audio and animation data
+// Note: Audio and animation data should be obtained from your backend service
+const initialAudioChunks = [
+  { data: audioData1, isLast: false },
+  { data: audioData2, isLast: false }
+]
+await avatarController.play(initialAudioChunks, initialKeyframes)
+
+// Stream additional audio chunks
+avatarController.sendAudioChunk(audioChunk, isLast)
+```
 
-**使用说明：**
-- `audioData`: 音频数据（ArrayBuffer 格式）
-- `end=false`（默认）- 正常发送音频数据，服务端会积累音频数据，积累到一定量后会自动返回动画数据并开始同步播放动画和音频
-- `end=true` - 立即返回动画数据，不再积累，用于结束当前对话或需要立即响应的场景
-- **重要**：不需要等待 `end=true` 才开始播放，积累到一定音频数据后就会自动开始播放
+**Resampling (Both Modes):**
+- If your audio source is at a different sample rate (e.g., 24kHz, 48kHz), you **must** resample it to 16kHz before sending
+- For high-quality resampling, use Web Audio API's `OfflineAudioContext` with anti-aliasing filtering
+- See example projects (`vanilla`, `react`, `vue`) for complete resampling implementation
 
-## 🌐 浏览器兼容性
+## 🌐 Browser Compatibility
 
-- **Chrome/Edge** 90+ (推荐 WebGPU)
+- **Chrome/Edge** 90+ (WebGPU recommended)
 - **Firefox** 90+ (WebGL)
 - **Safari** 14+ (WebGL)
-- **移动端** iOS 14+, Android 8+
+- **Mobile** iOS 14+, Android 8+
 
-## 📝 许可证
+## 📝 License
 
 MIT License
 
-## 🤝 贡献
+## 🤝 Contributing
 
-欢迎提交 Issue 和 Pull Request！
+Issues and Pull Requests are welcome!
 
-## 📞 支持
+## 📞 Support
 
-如有问题，请联系：
-- 邮箱：support@spavatar.com
-- 文档：https://docs.spavatar.com
-- GitHub：https://github.com/spavatar/sdk
+For questions, please contact:
+- Email: support@spavatar.com
+- Documentation: https://docs.spavatar.com
+- GitHub: https://github.com/spavatar/sdk