@spatialwalk/avatarkit 1.0.0-beta.17 → 1.0.0-beta.19

package/CHANGELOG.md

@@ -5,11 +5,33 @@ 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.19] - 2025-01-25
+
+### 📚 Documentation
+- **Fixed misleading documentation** - Corrected Host mode API documentation to accurately reflect that `yieldAudioData()` can be called directly to start a new session without requiring `playback()` first
+  - Removed misleading "after playback() is called" comments
+  - Clarified two ways to start a session: using `playback()` for existing data, or `yieldAudioData()` directly for streaming
+  - Updated all examples and workflow descriptions to reflect correct API usage
+
+## [1.0.0-beta.18] - 2025-01-25
+
+### 🔧 API Changes
+- **Renamed `reqId` to `conversationId`** - Updated terminology for better clarity
+  - All methods and parameters that used `reqId` now use `conversationId`
+  - `getCurrentReqId()` → `getCurrentConversationId()`
+  - `generateReqId()` → `generateConversationId()`
+  - Updated all event logs and documentation to use `conversationId`
+  - Note: Protobuf protocol still uses `reqId` field name internally, but SDK API uses `conversationId`
+
+### 📚 Documentation
+- Enhanced Host mode documentation to clearly emphasize the workflow: send audio data first to get conversationId, then use that conversationId to send animation data
+- Updated Host Mode Example and Host Mode Flow sections with clearer step-by-step instructions
+
 ## [1.0.0-beta.17] - 2025-01-24
 
 ### ✨ New Features
 - **Audio-Only Fallback Mechanism** - SDK now includes automatic fallback to audio-only playback when animation data is unavailable
-  - Network mode: Automatically enters audio-only mode when server returns an error
+  - SDK mode: Automatically enters audio-only mode when server returns an error
   - Host mode: Automatically enters audio-only mode when empty animation data is provided
   - Once in audio-only mode, subsequent animation data for that session is ignored
   - Fallback mode is interruptible, just like normal playback mode
@@ -20,6 +42,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `AvatarView` constructor now only requires `avatar` and `container` parameters
   - Removed `AvatarViewOptions` interface
   - `container` parameter is now required (no longer optional)
+- **Method Renames** - Renamed methods in `AvatarController` for Host mode to better reflect their purpose
+  - `play()` → `playback()`: Renamed to better reflect that the method is used for playback of existing data (replay mode)
+    - Old API: `avatarController.play(initialAudioChunks, initialKeyframes)`
+    - New API: `avatarController.playback(initialAudioChunks, initialKeyframes)`
+  - `sendAudioChunk()` → `yieldAudioData()`: Renamed to better reflect that the method yields/streams audio data
+    - Old API: `avatarController.sendAudioChunk(data, isLast)`
+    - New API: `avatarController.yieldAudioData(data, isLast)`
+  - `sendKeyframes()` → `yieldFramesData()`: Renamed to better reflect that the method yields/streams animation keyframes
+    - Old API: `avatarController.sendKeyframes(keyframes, reqId)`
+    - New API: `avatarController.yieldFramesData(keyframes, conversationId)`
 
 ### 🔧 Improvements
 - Extended transition animation duration from 200ms to 400ms for smoother end-of-playback transitions

package/README.md

@@ -37,8 +37,8 @@ import { DrivingServiceMode } from '@spatialwalk/avatarkit'
 const configuration: Configuration = {
   environment: Environment.test,
   drivingServiceMode: DrivingServiceMode.sdk, // Optional, 'sdk' is default
-  // - DrivingServiceMode.sdk: SDK mode (network mode) - SDK handles WebSocket communication
-  // - DrivingServiceMode.host: Host mode (external data mode) - Host app provides audio and animation data
+  // - DrivingServiceMode.sdk: SDK mode - SDK handles WebSocket communication
+  // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
 }
 
 await AvatarKit.initialize('your-app-id', configuration)
@@ -47,59 +47,58 @@ await AvatarKit.initialize('your-app-id', configuration)
 // AvatarKit.setSessionToken('your-session-token')
 
 // 2. Load character
-const avatarManager = new AvatarManager()
+const avatarManager = AvatarManager.shared
 const avatar = await avatarManager.load('character-id', (progress) => {
   console.log(`Loading progress: ${progress.progress}%`)
 })
 
 // 3. Create view (automatically creates Canvas and AvatarController)
 // The playback mode is determined by drivingServiceMode in AvatarKit configuration
-// - DrivingServiceMode.sdk: SDK mode (network mode) - SDK handles WebSocket communication
-// - DrivingServiceMode.host: Host mode (external data mode) - Host app provides audio and animation data
+// - DrivingServiceMode.sdk: SDK mode - SDK handles WebSocket communication
+// - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
-// 4. Start real-time communication (network mode only)
+// 4. Start real-time communication (SDK mode only)
 await avatarView.avatarController.start()
 
-// 5. Send audio data (network mode)
+// 5. Send audio data (SDK 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
+avatarView.avatarController.send(audioData, true) // end=true marks the end of current conversation round
 ```
 
-### External Data Mode Example
+### Host Mode Example
 
 ```typescript
 import { AvatarPlaybackMode } from '@spatialwalk/avatarkit'
 
-// 1-3. Same as network mode (initialize SDK, load character)
+// 1-3. Same as SDK mode (initialize SDK, load character)
 
-// 3. Create view with external data mode
+// 3. Create view with Host mode
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
-// 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
+// 4. Host Mode Workflow:
+// ⚠️ IMPORTANT: In Host mode, you MUST send audio data FIRST to get a conversationId,
+//    then use that conversationId to send animation data.
+//    Animation data with mismatched conversationId will be discarded.
 
-// 4. Start playback with initial data (obtained from your service)
-// Note: Audio and animation data should be obtained from your backend service
+// Option A: Playback existing audio and animation data (replay mode)
 const initialAudioChunks = [{ data: audioData1, isLast: false }, { data: audioData2, isLast: false }]
 const initialKeyframes = animationData1 // Animation keyframes from your service
-
-// Step 1: Send audio first to get reqId (required for session management)
-const reqId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
-
-// 5. Stream additional data as needed
-// Important: Always send audio first to get reqId, then use that reqId for animation data
-const currentReqId = avatarView.avatarController.yieldAudioData(audioData3, false)
-// Step 2: Use the reqId to send animation data (mismatched reqId will be discarded)
-avatarView.avatarController.yieldFramesData(animationData2, currentReqId || reqId)
+// Step 1: Send audio first to get conversationId
+const conversationId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
+
+// Option B: Stream new audio and animation data (start a new session directly)
+// Step 1: Send audio data first to get conversationId (automatically generates conversationId if starting new session)
+const currentConversationId = avatarView.avatarController.yieldAudioData(audioData3, false)
+// Step 2: Use the conversationId to send animation data (mismatched conversationId will be discarded)
+avatarView.avatarController.yieldFramesData(animationData2, currentConversationId || conversationId)
+// Note: To start playback, you need to call playback() with the accumulated data, or ensure enough audio data is sent
 ```
 
 ### Complete Examples
@@ -109,8 +108,8 @@ Check the example code in the GitHub repository for complete usage flows for bot
 **Example Project:** [AvatarKit-Web-Demo](https://github.com/spatialwalk/AvatarKit-Web-Demo)
 
 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
+- SDK mode: Real-time audio input with automatic animation data reception
+- Host mode: Custom data sources with manual audio/animation data management
 
 ## 🏗️ Architecture Overview
 
@@ -120,7 +119,7 @@ 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** - Handles WebSocket communication (only in network mode, internal implementation)
+3. **Network Layer** - Handles WebSocket communication (only in SDK mode, internal implementation)
 
 ### Core Components
 
@@ -153,14 +152,14 @@ The SDK supports two playback modes, configured in `AvatarKit.initialize()`:
 
 The SDK includes a fallback mechanism to ensure audio playback continues even when animation data is unavailable:
 
-- **Network Mode**: If the server returns an error or fails to provide animation data, the SDK automatically enters audio-only mode and continues playing audio independently
+- **SDK Mode**: If the server returns an error or fails to provide animation data, the SDK automatically enters audio-only mode and continues playing audio independently
 - **Host Mode**: If empty animation data is provided (empty array or undefined), the SDK automatically enters audio-only mode
 - Once in audio-only mode, any subsequent animation data for that session will be ignored, and only audio will continue playing
 - The fallback mode is interruptible, just like normal playback mode
 
 ### Data Flow
 
-#### Network Mode Flow
+#### SDK Mode Flow
 
 ```
 User audio input (16kHz mono PCM16) 
@@ -180,15 +179,20 @@ AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
 RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 
-#### External Data Mode Flow
+#### Host Mode Flow
 
 ```
 External data source (audio + animation)
     ↓
-AvatarController.playback(initialAudio, initialKeyframes) // Start playback
+Step 1: Send audio data FIRST to get conversationId
+    ↓
+AvatarController.playback(initialAudio, initialKeyframes) // Returns conversationId
+    OR
+AvatarController.yieldAudioData(audioChunk) // Returns conversationId
+    ↓
+Step 2: Use conversationId to send animation data
     ↓
-AvatarController.yieldAudioData() // Stream additional audio
-AvatarController.yieldFramesData() // Stream additional animation
+AvatarController.yieldFramesData(keyframes, conversationId) // Requires conversationId
     ↓
 AvatarController → AnimationPlayer (synchronized playback)
     ↓
@@ -200,8 +204,8 @@ RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 
 **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
+- In SDK mode, users provide audio data, SDK handles network communication and animation data reception
+- In Host mode, users provide both audio and animation data, SDK handles synchronized playback only
 
 ### Audio Format Requirements
 
@@ -262,10 +266,11 @@ AvatarKit.cleanup()
 
 ### AvatarManager
 
-Character resource manager, responsible for downloading, caching, and loading character data.
+Character resource manager, responsible for downloading, caching, and loading character data. Use the singleton instance via `AvatarManager.shared`.
 
 ```typescript
-const manager = new AvatarManager()
+// Get singleton instance
+const manager = AvatarManager.shared
 
 // Load character
 const avatar = await manager.load(
@@ -296,6 +301,9 @@ const avatarView = new AvatarView(avatar, container)
 // Get playback mode
 const mode = avatarView.playbackMode // 'network' | 'external'
 
+// Wait for first frame to render
+await avatarView.ready // Promise that resolves when the first frame is rendered
+
 // Cleanup resources (must be called before switching characters)
 avatarView.dispose()
 ```
@@ -314,7 +322,7 @@ const newAvatar = await avatarManager.load('new-character-id')
 // Create new AvatarView
 currentAvatarView = new AvatarView(newAvatar, container)
 
-// Network mode: start connection
+// SDK mode: start connection
 if (currentAvatarView.playbackMode === AvatarPlaybackMode.network) {
   await currentAvatarView.controller.start()
 }
@@ -322,77 +330,86 @@ if (currentAvatarView.playbackMode === AvatarPlaybackMode.network) {
 
 ### AvatarController
 
-Audio/animation playback controller (playback layer), manages synchronized playback of audio and animation. Automatically handles WebSocket communication in network mode.
+Audio/animation playback controller (playback layer), manages synchronized playback of audio and animation. Automatically handles WebSocket communication in SDK mode.
 
 **Two Usage Patterns:**
 
-#### Network Mode Methods
+#### SDK 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)
+// Send audio data
+const conversationId = avatarView.avatarController.send(audioData: ArrayBuffer, end: boolean)
+// Returns: conversationId - Conversation ID for this conversation session (used to distinguish each conversation round)
 // 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
+// end: false (default) - Continue sending audio data for current conversation
+// end: true - Mark the end of current conversation round. After end=true, sending new audio data will interrupt any ongoing playback from the previous conversation round
 
 // Close WebSocket service
 avatarView.avatarController.close()
 ```
 
-#### External Data Mode Methods
+#### Host Mode Methods
 
 ```typescript
 // Playback existing audio and animation data (starts a new conversation)
-const reqId = await avatarView.avatarController.playback(
+const conversationId = await avatarView.avatarController.playback(
   initialAudioChunks?: Array<{ data: Uint8Array, isLast: boolean }>,  // Existing audio chunks (16kHz mono PCM16)
   initialKeyframes?: any[]  // Existing animation keyframes (obtained from your service)
 )
-// Returns: reqId - New request ID for this conversation session
+// Returns: conversationId - New conversation ID for this conversation session
 
-// Stream additional audio chunks (after playback() is called)
-const reqId = avatarView.avatarController.yieldAudioData(
+// Stream audio chunks (can be called directly to start a new session, or after playback() to add more data)
+const conversationId = avatarView.avatarController.yieldAudioData(
   data: Uint8Array,               // Audio chunk data
   isLast: boolean = false         // Whether this is the last chunk
 )
-// Returns: reqId - Request ID for this audio session
+// Returns: conversationId - Conversation ID for this audio session
+// Note: If no conversationId exists, a new one will be automatically generated
 
-// Stream additional animation keyframes (after playback() is called)
+// Stream animation keyframes (requires conversationId from audio data)
 avatarView.avatarController.yieldFramesData(
-  keyframes: any[],                // Additional animation keyframes (obtained from your service)
-  reqId: string                    // Request ID (required). Use getCurrentReqId() or yieldAudioData() to get reqId.
+  keyframes: any[],                // Animation keyframes (obtained from your service)
+  conversationId: string                    // Conversation ID (required). Use getCurrentConversationId() or yieldAudioData() to get conversationId.
 )
 ```
 
-**⚠️ Important: Request ID (reqId) Management**
+**⚠️ Important: Conversation ID (conversationId) Management**
+
+**SDK Mode:**
+- `send()` returns a conversationId to distinguish each conversation round
+- `end=true` marks the end of a conversation round. After `end=true`, sending new audio data will interrupt any ongoing playback from the previous conversation round
 
+**Host Mode:**
 For each conversation session, you **must**:
-1. **First send audio data** to get a reqId:
-   - `playback()` returns a reqId when starting a new conversation
-   - `yieldAudioData()` returns a reqId for the current audio session
-2. **Then use that reqId** to send animation data:
-   - `yieldFramesData()` requires a valid reqId parameter
-   - Animation data with mismatched reqId will be **discarded**
-   - Use `getCurrentReqId()` to retrieve the current active reqId
-
-**Example Flow:**
+1. **First send audio data** to get a conversationId (used to distinguish each conversation round):
+   - `playback()` returns a conversationId when playback existing audio and animation data (replay mode)
+   - `yieldAudioData()` returns a conversationId for streaming new audio data
+2. **Then use that conversationId** to send animation data:
+   - `yieldFramesData()` requires a valid conversationId parameter
+   - Animation data with mismatched conversationId will be **discarded**
+   - Use `getCurrentConversationId()` to retrieve the current active conversationId
+
+**Example Flow (Host Mode):**
 ```typescript
-// Step 1: Send audio first to get reqId
-const reqId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
-// or
-const reqId = avatarView.avatarController.yieldAudioData(audioChunk, false)
-
-// Step 2: Use the reqId to send animation data
-avatarView.avatarController.yieldFramesData(keyframes, reqId)
+// Option A: Playback existing complete data (replay mode)
+const conversationId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
+
+// Option B: Start streaming new data directly
+// Step 1: Send audio data first to get conversationId (automatically generates if starting new session)
+const conversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
+// Step 2: Use the conversationId to send animation data
+avatarView.avatarController.yieldFramesData(keyframes, conversationId)
+// Note: To start playback with Option B, call playback() with accumulated data or ensure enough audio is sent
 ```
 
-**Why reqId is required:**
+**Why conversationId is required:**
 - Ensures audio and animation data belong to the same conversation session
 - Prevents data from different sessions from being mixed
 - Automatically discards mismatched animation data for data integrity
@@ -412,18 +429,22 @@ avatarView.avatarController.interrupt()
 // Clear all data and resources
 avatarView.avatarController.clear()
 
+// Get current conversation ID (for Host mode)
+const conversationId = avatarView.avatarController.getCurrentConversationId()
+// Returns: Current conversationId for the active audio session, or null if no active session
+
 // Set event callbacks
-avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // Network mode only
+avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // SDK mode only
 avatarView.avatarController.onAvatarState = (state: AvatarState) => {}
 avatarView.avatarController.onError = (error: Error) => {}
 ```
 
 **Important Notes:**
-- `start()` and `close()` are only available in network mode
-- `playback()`, `yieldAudioData()`, and `yieldFramesData()` are only available in external data mode
-- `pause()`, `resume()`, `interrupt()`, and `clear()` are available in both modes
+- `start()` and `close()` are only available in SDK mode
+- `playback()`, `yieldAudioData()`, and `yieldFramesData()` are only available in Host mode
+- `pause()`, `resume()`, `interrupt()`, `clear()`, and `getCurrentConversationId()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
-- **Request ID (reqId)**: In external data mode, always send audio data first to obtain a reqId, then use that reqId when sending animation data. Animation data with mismatched reqId will be discarded.
+- **Conversation ID**: In Host mode, always send audio data first to obtain a conversationId, then use that conversationId when sending animation data. Animation data with mismatched conversationId will be discarded. Use `getCurrentConversationId()` to retrieve the current active conversationId.
 
 ## 🔧 Configuration
 
@@ -432,7 +453,7 @@ avatarView.avatarController.onError = (error: Error) => {}
 ```typescript
 interface Configuration {
   environment: Environment
-  drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (network mode)
+  drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (SDK mode)
 }
 ```
 
@@ -469,8 +490,8 @@ constructor(avatar: Avatar, container: HTMLElement)
 
 ```typescript
 enum AvatarPlaybackMode {
-  network = 'network',   // Network mode: SDK handles WebSocket communication
-  external = 'external'  // External data mode: External provides data, SDK handles playback
+  network = 'network',   // SDK mode: SDK handles WebSocket communication
+  external = 'external'  // Host mode: Host provides data, SDK handles playback
 }
 ```
 
@@ -554,14 +575,12 @@ avatarView.avatarController.onError = (error: Error) => {
 
 ### Lifecycle Management
 
-#### Network Mode Lifecycle
+#### SDK Mode Lifecycle
 
 ```typescript
 // Initialize
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
-  playbackMode: AvatarPlaybackMode.network
-})
 await avatarView.avatarController.start()
 
 // Use
@@ -572,7 +591,7 @@ avatarView.avatarController.close()
 avatarView.dispose() // Automatically cleans up all resources
 ```
 
-#### External Data Mode Lifecycle
+#### Host Mode Lifecycle
 
 ```typescript
 // Initialize
@@ -581,12 +600,12 @@ const avatarView = new AvatarView(avatar, container)
 
 // Use
 const initialAudioChunks = [{ data: audioData1, isLast: false }]
-// Step 1: Send audio first to get reqId
-const reqId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
-// Step 2: Stream additional audio (returns reqId)
-const currentReqId = avatarView.avatarController.yieldAudioData(audioChunk, false)
-// Step 3: Use reqId to send animation data (mismatched reqId will be discarded)
-avatarView.avatarController.yieldFramesData(keyframes, currentReqId || reqId)
+// Step 1: Send audio first to get conversationId
+const conversationId = await avatarView.avatarController.playback(initialAudioChunks, initialKeyframes)
+// Step 2: Stream additional audio (returns conversationId)
+const currentConversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
+// Step 3: Use conversationId to send animation data (mismatched conversationId will be discarded)
+avatarView.avatarController.yieldFramesData(keyframes, currentConversationId || conversationId)
 
 // Cleanup
 avatarView.avatarController.clear() // Clear all data and resources
@@ -596,8 +615,8 @@ avatarView.dispose() // Automatically cleans up all resources
 **⚠️ 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 network mode, call `close()` before `dispose()` to properly close WebSocket connections
-- In external data mode, call `clear()` before `dispose()` to clear all playback data
+- In SDK mode, call `close()` before `dispose()` to properly close WebSocket connections
+- In Host mode, call `clear()` before `dispose()` to clear all playback data
 
 ### Memory Optimization
 
@@ -607,7 +626,7 @@ avatarView.dispose() // Automatically cleans up all resources
 
 ### Audio Data Sending
 
-#### Network Mode
+#### SDK Mode
 
 The `send()` method receives audio data in `ArrayBuffer` format:
 
@@ -619,16 +638,22 @@ The `send()` method receives audio data in `ArrayBuffer` format:
 
 **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
+- `end=false` (default) - Continue sending audio data for current conversation
+- `end=true` - Mark the end of current conversation round. After `end=true`, sending new audio data will interrupt any ongoing playback from the previous conversation round
 - **Important**: No need to wait for `end=true` to start playing, it will automatically start playing after accumulating enough audio data
 
-#### External Data Mode
+#### Host Mode
+
+The `playback()` method is used to playback existing audio and animation data (replay mode), generating a new conversationId and interrupting any existing conversation. 
+
+**Two ways to start a session in Host mode:**
+1. **Use `playback()`** - For replaying existing complete audio and animation data
+2. **Use `yieldAudioData()` directly** - For streaming new audio data (automatically generates conversationId if needed)
 
-The `playback()` method starts playback with existing audio and animation data, generating a new reqId and interrupting any existing conversation. Then use `yieldAudioData()` to stream additional audio:
+Then use `yieldAudioData()` to stream additional audio:
 
 **Audio Format Requirements:**
-- Same as network mode: 16kHz mono PCM16 format
+- Same as SDK mode: 16kHz mono PCM16 format
 - Audio data should be provided as `Uint8Array` in chunks with `isLast` flag
 
 **Usage:**
@@ -639,18 +664,21 @@ const initialAudioChunks = [
   { data: audioData1, isLast: false },
   { data: audioData2, isLast: false }
 ]
-const reqId = await avatarController.playback(initialAudioChunks, initialKeyframes)
-// Returns: reqId - New request ID for this conversation session
+const conversationId = await avatarController.playback(initialAudioChunks, initialKeyframes)
+// Returns: conversationId - New conversation ID for this conversation session
 
 // Stream additional audio chunks
-const reqId = avatarController.yieldAudioData(audioChunk, isLast)
-// Returns: reqId - Request ID for this audio session
+const conversationId = avatarController.yieldAudioData(audioChunk, isLast)
+// Returns: conversationId - Conversation ID for this audio session
 ```
 
-**⚠️ Request ID Workflow:**
-1. **Send audio first** → Get reqId from `playback()` or `yieldAudioData()`
-2. **Send animation with reqId** → Use the reqId from step 1 in `yieldFramesData()`
-3. **Data matching** → Only animation data with matching reqId will be accepted
+**⚠️ Conversation ID Workflow:**
+1. **Start a session** → Choose one of two ways:
+   - **Option A**: Use `playback(initialAudioChunks, initialKeyframes)` to replay existing complete data
+   - **Option B**: Use `yieldAudioData(audioChunk)` directly to start streaming (automatically generates conversationId)
+2. **Get conversationId** → Both methods return a conversationId
+3. **Send animation with conversationId** → Use the conversationId from step 1 in `yieldFramesData()`
+4. **Data matching** → Only animation data with matching conversationId will be accepted
 
 **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

package/dist/{StreamingAudioPlayer-a8MwHQ3Q.js → StreamingAudioPlayer-Cw8IygPS.js}

@@ -1,7 +1,7 @@
 var C = Object.defineProperty;
 var g = (h, t, e) => t in h ? C(h, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : h[t] = e;
 var i = (h, t, e) => g(h, typeof t != "symbol" ? t + "" : t, e);
-import { A as m, e as f, a as c, l as u } from "./index-suaZGA5u.js";
+import { A as m, e as f, a as c, l as u } from "./index-CRv3XrVE.js";
 class y {
   constructor(t) {
     // AudioContext is managed internally
@@ -331,4 +331,4 @@ class y {
 export {
   y as StreamingAudioPlayer
 };
-//# sourceMappingURL=StreamingAudioPlayer-a8MwHQ3Q.js.map
+//# sourceMappingURL=StreamingAudioPlayer-Cw8IygPS.js.map