@spatialwalk/avatarkit 1.0.0-beta.21 → 1.0.0-beta.23

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.23] - 2025-01-26
+
+### 🔧 API Changes
+- **Breaking Change** - `playback()` method is no longer supported and has been removed from public API
+
+## [1.0.0-beta.22] - 2025-01-26
+
+### 🔧 API Changes
+- **State Callback Renamed** - `onAvatarState` has been renamed to `onConversationState` for better clarity
+  - The callback now uses `ConversationState` enum with states: `idle` and `playing`
+- **Environment Enum Updated** - `Environment.us` has been renamed to `Environment.intl` for better internationalization support
+  - All references to `Environment.us` should be updated to `Environment.intl`
+  - Remote config endpoints now use `intl` instead of `us`
+
+### ✨ New Features
+- **Volume Control** - Added volume control API for audio playback
+  - `setVolume(volume: number)` - Set audio volume (0.0 to 1.0)
+  - `getVolume(): number` - Get current audio volume
+  - Volume control only affects the avatar's audio player, not system volume
+  - Volume changes take effect immediately, including for currently playing audio
+
 ## [1.0.0-beta.21] - 2025-01-25
 
 ### ✨ New Features
@@ -221,7 +242,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0-beta.5] - 2025-11-14
 
 ### 🐛 Bug Fixes
-- Fixed missing `AvatarPlaybackMode` enum export in published package
+- Fixed missing `DrivingServiceMode` enum export in published package
 
 ---
 
@@ -286,7 +307,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   // New API
   new AvatarView(avatar, {
     container: container,
-    playbackMode: AvatarPlaybackMode.network // or AvatarPlaybackMode.external
+    playbackMode: DrivingServiceMode.sdk // or DrivingServiceMode.host
   })
   ```
 

package/README.md

@@ -28,11 +28,11 @@ import {
   AvatarManager, 
   AvatarView,
   Configuration,
-  Environment 
+  Environment,
+  DrivingServiceMode
 } from '@spatialwalk/avatarkit'
 
 // 1. Initialize SDK
-import { DrivingServiceMode } from '@spatialwalk/avatarkit'
 
 const configuration: Configuration = {
   environment: Environment.test,
@@ -62,19 +62,15 @@ const avatarView = new AvatarView(avatar, container)
 // 4. Start real-time communication (SDK mode only)
 await avatarView.avatarController.start()
 
-// 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
+// 5. Send audio data (SDK mode, must be 16kHz mono PCM16 format)
+const audioData = new ArrayBuffer(1024) // Example: 16kHz PCM16 audio data
+avatarView.avatarController.send(audioData, false) // Send audio data
 avatarView.avatarController.send(audioData, true) // end=true marks the end of current conversation round
 ```
 
 ### Host Mode Example
 
 ```typescript
-import { AvatarPlaybackMode } from '@spatialwalk/avatarkit'
 
 // 1-3. Same as SDK mode (initialize SDK, load character)
 
@@ -83,22 +79,9 @@ const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
 // 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.
-
-// 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 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
+// Send audio data first to get conversationId, then use it to send animation data
+const conversationId = avatarView.avatarController.yieldAudioData(audioData, false)
+avatarView.avatarController.yieldFramesData(animationData, conversationId)
 ```
 
 ### Complete Examples
@@ -186,15 +169,9 @@ RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 External data source (audio + animation)
     ↓
-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.yieldFramesData(keyframes, conversationId) // Requires conversationId
+AvatarController.yieldFramesData(keyframes, conversationId)
     ↓
 AvatarController → AnimationPlayer (synchronized playback)
     ↓
@@ -205,10 +182,6 @@ AvatarController (playback loop) → AvatarView.renderRealtimeFrame()
 RenderSystem → WebGPU/WebGL → Canvas rendering
 ```
 
-**Note:** 
-- 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
 
 **⚠️ Important:** The SDK requires audio data to be in **16kHz mono PCM16** format:
@@ -288,21 +261,28 @@ manager.clearCache()
 
 3D rendering view (rendering layer), responsible for 3D rendering only. Internally automatically creates and manages `AvatarController`.
 
-**Playback Mode Configuration:**
+```typescript
+constructor(avatar: Avatar, container: HTMLElement)
+```
+
+**Parameters:**
+- `avatar`: Avatar 实例
+- `container`: Canvas 容器元素（必选）
+  - Canvas 自动使用容器的完整尺寸（宽度和高度）
+  - Canvas 宽高比适应容器尺寸 - 设置容器尺寸以控制宽高比
+  - Canvas 会自动添加到容器中
+  - SDK automatically handles resize events via ResizeObserver
+
+**Playback Mode:**
+- The playback mode is determined by `drivingServiceMode` in `AvatarKit.initialize()` configuration
 - The playback mode is fixed when creating `AvatarView` and persists throughout its lifecycle
 - Cannot be changed after creation
 
 ```typescript
-import { AvatarPlaybackMode } from '@spatialwalk/avatarkit'
-
 // Create view (Canvas is automatically added to container)
-// Create view (playback mode is determined by drivingServiceMode in AvatarKit configuration)
 const container = document.getElementById('avatar-container')
 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
 
@@ -324,10 +304,8 @@ const newAvatar = await avatarManager.load('new-character-id')
 // Create new AvatarView
 currentAvatarView = new AvatarView(newAvatar, container)
 
-// SDK mode: start connection
-if (currentAvatarView.playbackMode === AvatarPlaybackMode.network) {
+// SDK mode: start connection (will throw error if not in SDK mode)
   await currentAvatarView.controller.start()
-}
 ```
 
 ### AvatarController
@@ -342,14 +320,9 @@ Audio/animation playback controller (playback layer), manages synchronized playb
 // Start WebSocket service
 await avatarView.avatarController.start()
 
-// Send audio data
+// Send audio data (must be 16kHz mono PCM16 format)
 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
+// Returns: conversationId - Conversation ID for this conversation session
 // 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
 
@@ -360,25 +333,17 @@ avatarView.avatarController.close()
 #### Host Mode Methods
 
 ```typescript
-// Playback existing audio and animation data (starts a new conversation)
-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: conversationId - New conversation ID for this conversation session
-
-// Stream audio chunks (can be called directly to start a new session, or after playback() to add more data)
+// Stream audio chunks (must be 16kHz mono PCM16 format)
 const conversationId = avatarView.avatarController.yieldAudioData(
   data: Uint8Array,               // Audio chunk data
   isLast: boolean = false         // Whether this is the last chunk
 )
 // Returns: conversationId - Conversation ID for this audio session
-// Note: If no conversationId exists, a new one will be automatically generated
 
 // Stream animation keyframes (requires conversationId from audio data)
 avatarView.avatarController.yieldFramesData(
   keyframes: any[],                // Animation keyframes (obtained from your service)
-  conversationId: string                    // Conversation ID (required). Use getCurrentConversationId() or yieldAudioData() to get conversationId.
+  conversationId: string          // Conversation ID (required)
 )
 ```
 
@@ -386,36 +351,14 @@ avatarView.avatarController.yieldFramesData(
 
 **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
+- `end=true` marks the end of a conversation round
 
 **Host Mode:**
-For each conversation session, you **must**:
-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:
+- `yieldAudioData()` returns a conversationId (automatically generates if starting new session)
    - `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
-// 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 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
-
 #### Common Methods (Both Modes)
 
 ```typescript
@@ -435,18 +378,21 @@ avatarView.avatarController.clear()
 const conversationId = avatarView.avatarController.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)
+
 // Set event callbacks
 avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // SDK mode only
-avatarView.avatarController.onAvatarState = (state: AvatarState) => {}
+avatarView.avatarController.onConversationState = (state: ConversationState) => {}
 avatarView.avatarController.onError = (error: Error) => {}
 ```
 
 **Important Notes:**
 - `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
+- `yieldAudioData()` and `yieldFramesData()` are only available in Host mode
+- `pause()`, `resume()`, `interrupt()`, `clear()`, `getCurrentConversationId()`, `setVolume()`, and `getVolume()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
-- **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
 
@@ -460,7 +406,7 @@ interface Configuration {
 ```
 
 **Description:**
-- `environment`: Specifies the environment (cn/us/test), SDK will automatically use the corresponding API address and WebSocket address based on the environment
+- `environment`: Specifies the environment (cn/intl/test), SDK will automatically use the corresponding API address and WebSocket address based on the environment
 - `drivingServiceMode`: Specifies the driving service mode
   - `DrivingServiceMode.sdk` (default): SDK mode - SDK handles WebSocket communication automatically
   - `DrivingServiceMode.host`: Host mode - Host application provides audio and animation data
@@ -469,34 +415,11 @@ interface Configuration {
 ```typescript
 enum Environment {
   cn = 'cn',    // China region
-  us = 'us',    // US region
+  intl = 'intl',    // International region
   test = 'test' // Test environment
 }
 ```
 
-### AvatarView Constructor
-
-```typescript
-constructor(avatar: Avatar, container: HTMLElement)
-```
-
-**Parameters:**
-- `avatar`: Avatar 实例
-- `container`: Canvas 容器元素（必选）
-  - Canvas 自动使用容器的完整尺寸（宽度和高度）
-  - Canvas 宽高比适应容器尺寸 - 设置容器尺寸以控制宽高比
-  - Canvas 会自动添加到容器中
-
-**Note:** 播放模式由 `AvatarKit.initialize()` 配置中的 `drivingServiceMode` 决定，而不是在构造函数参数中
-  - SDK automatically handles resize events via ResizeObserver
-
-```typescript
-enum AvatarPlaybackMode {
-  network = 'network',   // SDK mode: SDK handles WebSocket communication
-  external = 'external'  // Host mode: Host provides data, SDK handles playback
-}
-```
-
 ### CameraConfig
 
 ```typescript
@@ -524,17 +447,23 @@ enum ConnectionState {
 }
 ```
 
-### AvatarState
+### ConversationState
 
 ```typescript
-enum AvatarState {
-  idle = 'idle',      // Idle state, showing breathing animation
-  active = 'active',  // Active, waiting for playable content
-  playing = 'playing', // Playing
-  paused = 'paused'   // Paused (can be resumed)
+enum ConversationState {
+  idle = 'idle',      // 呼吸态
+  playing = 'playing' // 播放态
 }
 ```
 
+**状态说明：**
+- `idle`: 数字人处于呼吸态，等待对话开始
+- `playing`: 数字人正在播放对话内容（包括过渡动画期间）
+
+**注意：** 过渡动画期间会提前通知目标状态：
+- 从 `idle` 过渡到 `playing` 时，立即通知 `playing` 状态
+- 从 `playing` 过渡到 `idle` 时，立即通知 `idle` 状态
+
 ## 🎨 Rendering System
 
 The SDK supports two rendering backends:
@@ -601,13 +530,8 @@ const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
 // Use
-const initialAudioChunks = [{ data: audioData1, isLast: false }]
-// 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)
+const conversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
+avatarView.avatarController.yieldFramesData(keyframes, conversationId)
 
 // Cleanup
 avatarView.avatarController.clear() // Clear all data and resources
@@ -626,67 +550,6 @@ avatarView.dispose() // Automatically cleans up all resources
 - Supports dynamic loading/unloading of character and animation resources
 - Provides memory usage monitoring interface
 
-### Audio Data Sending
-
-#### SDK 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) - 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
-
-#### 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)
-
-Then use `yieldAudioData()` to stream additional audio:
-
-**Audio Format Requirements:**
-- Same as SDK mode: 16kHz mono PCM16 format
-- Audio data should be provided as `Uint8Array` in chunks with `isLast` flag
-
-**Usage:**
-```typescript
-// Playback existing audio and animation data (starts a new conversation)
-// Note: Audio and animation data should be obtained from your backend service
-const initialAudioChunks = [
-  { data: audioData1, isLast: false },
-  { data: audioData2, isLast: false }
-]
-const conversationId = await avatarController.playback(initialAudioChunks, initialKeyframes)
-// Returns: conversationId - New conversation ID for this conversation session
-
-// Stream additional audio chunks
-const conversationId = avatarController.yieldAudioData(audioChunk, isLast)
-// Returns: conversationId - Conversation ID for this audio session
-```
-
-**⚠️ 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
-- 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 recommended)

package/dist/{StreamingAudioPlayer-DEXcuhRW.js → StreamingAudioPlayer-PkzxBP93.js}

@@ -1,38 +1,42 @@
 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-ChKhyUK4.js";
+var s = (h, t, e) => g(h, typeof t != "symbol" ? t + "" : t, e);
+import { A as m, e as f, a as c, l as n } from "./index-DYf1u8L7.js";
 class y {
   constructor(t) {
     // AudioContext is managed internally
-    i(this, "audioContext", null);
-    i(this, "sampleRate");
-    i(this, "channelCount");
-    i(this, "debug");
+    s(this, "audioContext", null);
+    s(this, "sampleRate");
+    s(this, "channelCount");
+    s(this, "debug");
     // Session-level state
-    i(this, "sessionId");
-    i(this, "sessionStartTime", 0);
+    s(this, "sessionId");
+    s(this, "sessionStartTime", 0);
     // AudioContext time when session started
-    i(this, "pausedTimeOffset", 0);
+    s(this, "pausedTimeOffset", 0);
     // Accumulated paused time
-    i(this, "pausedAt", 0);
+    s(this, "pausedAt", 0);
     // Time when paused
-    i(this, "pausedAudioContextTime", 0);
+    s(this, "pausedAudioContextTime", 0);
     // audioContext.currentTime when paused (for resume calculation)
-    i(this, "scheduledTime", 0);
+    s(this, "scheduledTime", 0);
     // Next chunk schedule time in AudioContext time
     // Playback state
-    i(this, "isPlaying", !1);
-    i(this, "isPaused", !1);
-    i(this, "autoStartEnabled", !0);
+    s(this, "isPlaying", !1);
+    s(this, "isPaused", !1);
+    s(this, "autoStartEnabled", !0);
     // Control whether to auto-start when buffer is ready
     // Audio buffer queue
-    i(this, "audioChunks", []);
-    i(this, "scheduledChunks", 0);
+    s(this, "audioChunks", []);
+    s(this, "scheduledChunks", 0);
     // Number of chunks already scheduled
-    i(this, "activeSources", /* @__PURE__ */ new Set());
+    s(this, "activeSources", /* @__PURE__ */ new Set());
+    // Volume control
+    s(this, "gainNode", null);
+    s(this, "volume", 1);
+    // Default volume 1.0 (0.0 - 1.0)
     // Event callbacks
-    i(this, "onEndedCallback");
+    s(this, "onEndedCallback");
     this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`, this.sampleRate = (t == null ? void 0 : t.sampleRate) ?? m.audio.sampleRate, this.channelCount = (t == null ? void 0 : t.channelCount) ?? 1, this.debug = (t == null ? void 0 : t.debug) ?? !1;
   }
   /**
@@ -43,7 +47,7 @@ class y {
       try {
         this.audioContext = new AudioContext({
           sampleRate: this.sampleRate
-        }), this.audioContext.state === "suspended" && await this.audioContext.resume(), this.log("AudioContext initialized", {
+        }), this.gainNode = this.audioContext.createGain(), this.gainNode.gain.value = this.volume, this.gainNode.connect(this.audioContext.destination), this.audioContext.state === "suspended" && await this.audioContext.resume(), this.log("AudioContext initialized", {
           sessionId: this.sessionId,
           sampleRate: this.audioContext.sampleRate,
           state: this.audioContext.state
@@ -53,7 +57,7 @@ class y {
         throw c.logEvent("activeAudioSessionFailed", "warning", {
           sessionId: this.sessionId,
           reason: e
-        }), u.error("Failed to initialize AudioContext:", e), t instanceof Error ? t : new Error(e);
+        }), n.error("Failed to initialize AudioContext:", e), t instanceof Error ? t : new Error(e);
       }
   }
   /**
@@ -61,7 +65,7 @@ class y {
    */
   addChunk(t, e = !1) {
     if (!this.audioContext) {
-      u.error("AudioContext not initialized");
+      n.error("AudioContext not initialized");
       return;
     }
     this.audioChunks.push({ data: t, isLast: e }), this.log(`Added chunk ${this.audioChunks.length}`, {
@@ -132,16 +136,16 @@ class y {
     }
     const r = e.data, o = e.isLast, a = this.pcmToAudioBuffer(r);
     if (!a) {
-      u.error("Failed to create AudioBuffer from PCM data"), c.logEvent("character_player", "error", {
+      n.error("Failed to create AudioBuffer from PCM data"), c.logEvent("character_player", "error", {
         sessionId: this.sessionId,
         event: "audio_buffer_creation_failed"
       });
       return;
     }
     try {
-      const s = this.audioContext.createBufferSource();
-      s.buffer = a, s.connect(this.audioContext.destination), s.start(this.scheduledTime), this.activeSources.add(s), s.onended = () => {
-        this.activeSources.delete(s), o && this.activeSources.size === 0 && (this.log("Last audio chunk ended, marking playback as ended"), this.markEnded());
+      const i = this.audioContext.createBufferSource();
+      i.buffer = a, i.connect(this.gainNode), i.start(this.scheduledTime), this.activeSources.add(i), i.onended = () => {
+        this.activeSources.delete(i), o && this.activeSources.size === 0 && (this.log("Last audio chunk ended, marking playback as ended"), this.markEnded());
       }, this.scheduledTime += a.duration, this.scheduledChunks++, this.log(`[StreamingAudioPlayer] Scheduled chunk ${t + 1}/${this.audioChunks.length}`, {
         startTime: this.scheduledTime - a.duration,
         duration: a.duration,
@@ -149,11 +153,11 @@ class y {
         isLast: o,
         activeSources: this.activeSources.size
       });
-    } catch (s) {
-      u.errorWithError("Failed to schedule audio chunk:", s), c.logEvent("character_player", "error", {
+    } catch (i) {
+      n.errorWithError("Failed to schedule audio chunk:", i), c.logEvent("character_player", "error", {
         sessionId: this.sessionId,
         event: "schedule_chunk_failed",
-        reason: s instanceof Error ? s.message : String(s)
+        reason: i instanceof Error ? i.message : String(i)
       });
     }
   }
@@ -165,25 +169,25 @@ class y {
     if (!this.audioContext)
       return null;
     if (t.length === 0) {
-      const l = Math.floor(this.sampleRate * 0.01), n = this.audioContext.createBuffer(
+      const l = Math.floor(this.sampleRate * 0.01), u = this.audioContext.createBuffer(
         this.channelCount,
         l,
         this.sampleRate
       );
       for (let d = 0; d < this.channelCount; d++)
-        n.getChannelData(d).fill(0);
-      return n;
+        u.getChannelData(d).fill(0);
+      return u;
     }
     const e = new Uint8Array(t), r = new Int16Array(e.buffer, 0, e.length / 2), o = r.length / this.channelCount, a = this.audioContext.createBuffer(
       this.channelCount,
       o,
       this.sampleRate
     );
-    for (let s = 0; s < this.channelCount; s++) {
-      const l = a.getChannelData(s);
-      for (let n = 0; n < o; n++) {
-        const d = n * this.channelCount + s;
-        l[n] = r[d] / 32768;
+    for (let i = 0; i < this.channelCount; i++) {
+      const l = a.getChannelData(i);
+      for (let u = 0; u < o; u++) {
+        const d = u * this.channelCount + i;
+        l[u] = r[d] / 32768;
       }
     }
     return a;
@@ -204,7 +208,7 @@ class y {
    */
   pause() {
     !this.isPlaying || this.isPaused || !this.audioContext || (this.pausedAt = this.getCurrentTime(), this.pausedAudioContextTime = this.audioContext.currentTime, this.isPaused = !0, this.audioContext.state === "running" && this.audioContext.suspend().catch((t) => {
-      u.errorWithError("Failed to suspend AudioContext:", t), this.isPaused = !1;
+      n.errorWithError("Failed to suspend AudioContext:", t), this.isPaused = !1;
     }), this.log("Playback paused", {
       pausedAt: this.pausedAt,
       pausedAudioContextTime: this.pausedAudioContextTime,
@@ -221,7 +225,7 @@ class y {
       try {
         await this.audioContext.resume();
       } catch (e) {
-        throw u.errorWithError("Failed to resume AudioContext:", e), e;
+        throw n.errorWithError("Failed to resume AudioContext:", e), e;
       }
     const t = this.audioContext.currentTime;
     this.sessionStartTime = this.pausedAudioContextTime - this.pausedAt - this.pausedTimeOffset, this.isPaused = !1, this.scheduledChunks < this.audioChunks.length && this.scheduleAllChunks(), this.log("Playback resumed", {
@@ -307,7 +311,7 @@ class y {
    * Dispose and cleanup
    */
   dispose() {
-    this.stop(), this.audioContext && (this.audioContext.close(), this.audioContext = null), this.audioChunks = [], this.scheduledChunks = 0, this.sessionStartTime = 0, this.pausedTimeOffset = 0, this.pausedAt = 0, this.pausedAudioContextTime = 0, this.scheduledTime = 0, this.onEndedCallback = void 0, this.log("StreamingAudioPlayer disposed");
+    this.stop(), this.audioContext && (this.audioContext.close(), this.audioContext = null, this.gainNode = null), this.audioChunks = [], this.scheduledChunks = 0, this.sessionStartTime = 0, this.pausedTimeOffset = 0, this.pausedAt = 0, this.pausedAudioContextTime = 0, this.scheduledTime = 0, this.onEndedCallback = void 0, this.log("StreamingAudioPlayer disposed");
   }
   /**
    * Flush buffered audio
@@ -321,14 +325,29 @@ class y {
     }
     this.scheduledChunks < this.audioChunks.length && this.audioChunks.splice(this.scheduledChunks), this.log("Flushed (soft)", { remainingScheduled: this.scheduledChunks });
   }
+  /**
+   * 设置音量 (0.0 - 1.0)
+   * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
+   * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
+   */
+  setVolume(t) {
+    (t < 0 || t > 1) && (n.warn(`[StreamingAudioPlayer] Volume out of range: ${t}, clamping to [0, 1]`), t = Math.max(0, Math.min(1, t))), this.volume = t, this.gainNode && (this.gainNode.gain.value = t);
+  }
+  /**
+   * 获取当前音量
+   * @returns 当前音量值 (0.0 - 1.0)
+   */
+  getVolume() {
+    return this.volume;
+  }
   /**
    * Debug logging
    */
   log(t, e) {
-    this.debug && u.log(`[StreamingAudioPlayer] ${t}`, e || "");
+    this.debug && n.log(`[StreamingAudioPlayer] ${t}`, e || "");
   }
 }
 export {
   y as StreamingAudioPlayer
 };
-//# sourceMappingURL=StreamingAudioPlayer-DEXcuhRW.js.map
+//# sourceMappingURL=StreamingAudioPlayer-PkzxBP93.js.map