@spatialwalk/avatarkit 1.0.0-beta.27 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.29] - 2025-12-15
+
+### 🔄 Breaking Changes
+- **Environment Enum** - Removed `Environment.test`. Only `Environment.cn` and `Environment.intl` are now supported. Environment configuration must be explicitly provided.
+- **Log Level Default** - Default log level changed from `LogLevel.all` to `LogLevel.off`. Set `logLevel: LogLevel.all` in configuration to enable all logs.
+
+### ✨ New Features
+- **Avatar Caching** - Added avatar caching methods in `AvatarManager`:
+  - `retrieve(id: string): Avatar | undefined` - Get cached avatar by ID
+  - `clear(id: string): void` - Clear cached avatar for specific ID
+  - `clearAll(): void` - Clear all cached avatars
+  - `clearCache()` is now deprecated, use `clearAll()` instead
+- **Background Image Support** - Added background image control in `AvatarView`:
+  - `isOpaque: boolean` - Getter/setter to control canvas background transparency
+  - `setBackgroundImage(image: HTMLImageElement | string | null): void` - Set or remove background image
+
+### 🔧 Improvements
+- **Avatar Version Checking** - Avatar cache now automatically checks version and reloads if cached avatar version differs from latest metadata
+- **Concurrent Loading** - Multiple concurrent `load()` calls for the same avatar ID now reuse the same loading promise
+
+## [1.0.0-beta.28] - 2025-12-08
+
+### 🔄 Breaking Changes
+- **Class Renamed** - `AvatarKit` class has been renamed to `AvatarSDK` for better consistency
+  - Update all imports: `import { AvatarKit } from '@spatialwalk/avatarkit'` → `import { AvatarSDK } from '@spatialwalk/avatarkit'`
+  - Update all API calls: `AvatarKit.initialize()` → `AvatarSDK.initialize()`
+  - All static methods and properties remain the same, only the class name has changed
+
+### 🔧 Improvements
+- **Rendering Optimizations** - Added fragment shader discard optimization to improve performance and edge quality
+- **Shader Alignment** - Removed view matrix transpose to align with Android SDK implementation
+- **Resource Cleanup** - Removed unused `frameMono` and `audioMono` resources from SDK and tests
+
 ## [1.0.0-beta.27] - 2025-12-04
 
 ### 🐛 Bugfix
@@ -115,8 +148,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Fallback mode is interruptible, just like normal playback mode
 
 ### 🔧 API Changes
-- **Playback Mode Configuration** - Moved playback mode configuration from `AvatarView` constructor to `AvatarKit.initialize()`
-  - Playback mode is now determined by `drivingServiceMode` in `AvatarKit.initialize()` configuration
+- **Playback Mode Configuration** - Moved playback mode configuration from `AvatarView` constructor to `AvatarSDK.initialize()`
+  - Playback mode is now determined by `drivingServiceMode` in `AvatarSDK.initialize()` configuration
   - `AvatarView` constructor now only requires `avatar` and `container` parameters
   - Removed `AvatarViewOptions` interface
   - `container` parameter is now required (no longer optional)
@@ -222,7 +255,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 📚 Documentation
 - Updated demo repository link in README.md
-  - Changed example project link from `Avatarkit-web-demo` to `AvatarKit-Web-Demo` to match the new repository name
+  - Changed example project link from `Avatarkit-web-demo` to `AvatarSDK-Web-Demo` to match the new repository name
 
 ---
 
@@ -232,7 +265,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cleaned up public API to hide internal implementation details
   - Marked internal methods with `@internal` JSDoc tag to exclude them from TypeScript declarations
   - Removed unused environment configuration options (`realtimeApiBaseUrl`, `realtimeWsUrl`)
-  - Added `appId` getter to `AvatarKit` for accessing initialized app ID
+  - Added `appId` getter to `AvatarSDK` for accessing initialized app ID
   - Internal methods like `getEnvironmentConfig`, `logEvent`, `getCanvas`, `getCameraConfig`, `updateCameraConfig` are now properly hidden from public API
 
 ### 🐛 Bug Fixes

package/README.md

@@ -1,4 +1,4 @@
-# SPAvatarKit SDK
+# SPAvatarSDK SDK
 
 Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supporting audio-driven animation rendering and high-quality 3D rendering.
 
@@ -24,7 +24,7 @@ npm install @spatialwalk/avatarkit
 
 ```typescript
 import { 
-  AvatarKit, 
+  AvatarSDK, 
   AvatarManager, 
   AvatarView,
   Configuration,
@@ -36,21 +36,21 @@ import {
 // 1. Initialize SDK
 
 const configuration: Configuration = {
-  environment: Environment.test,
+  environment: Environment.cn,
   drivingServiceMode: DrivingServiceMode.sdk, // Optional, 'sdk' is default
   // - DrivingServiceMode.sdk: SDK mode - SDK handles WebSocket communication
   // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
-  logLevel: LogLevel.all, // Optional, 'all' is default
+  logLevel: LogLevel.off, // Optional, 'off' is default
   // - LogLevel.off: Disable all logs
   // - LogLevel.error: Only error logs
   // - LogLevel.warning: Warning and error logs
   // - LogLevel.all: All logs (info, warning, error)
 }
 
-await AvatarKit.initialize('your-app-id', configuration)
+await AvatarSDK.initialize('your-app-id', configuration)
 
 // Set sessionToken (if needed, call separately)
-// AvatarKit.setSessionToken('your-session-token')
+// AvatarSDK.setSessionToken('your-session-token')
 
 // 2. Load character
 const avatarManager = AvatarManager.shared
@@ -59,7 +59,7 @@ const avatar = await avatarManager.load('character-id', (progress) => {
 })
 
 // 3. Create view (automatically creates Canvas and AvatarController)
-// The playback mode is determined by drivingServiceMode in AvatarKit configuration
+// The playback mode is determined by drivingServiceMode in AvatarSDK configuration
 // - 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')
@@ -94,7 +94,7 @@ avatarView.avatarController.yieldFramesData(animationData, conversationId)
 
 Check the example code in the GitHub repository for complete usage flows for both modes.
 
-**Example Project:** [AvatarKit-Web-Demo](https://github.com/spatialwalk/AvatarKit-Web-Demo)
+**Example Project:** [AvatarSDK-Web-Demo](https://github.com/spatialwalk/AvatarSDK-Web-Demo)
 
 This repository contains complete examples for Vanilla JS, Vue 3, and React, demonstrating:
 - SDK mode: Real-time audio input with automatic animation data reception
@@ -112,30 +112,30 @@ The SDK uses a three-layer architecture for clear separation of concerns:
 
 ### Core Components
 
-- **AvatarKit** - SDK initialization and management
+- **AvatarSDK** - SDK initialization and management
 - **AvatarManager** - Character resource loading and management
 - **AvatarView** - 3D rendering view (rendering layer)
 - **AvatarController** - Audio/animation playback controller (playback layer)
 
 ### Playback Modes
 
-The SDK supports two playback modes, configured in `AvatarKit.initialize()`:
+The SDK supports two playback modes, configured in `AvatarSDK.initialize()`:
 
 #### 1. SDK Mode (Default)
-- Configured via `drivingServiceMode: DrivingServiceMode.sdk` in `AvatarKit.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.sdk` in `AvatarSDK.initialize()`
 - 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. Host Mode
-- Configured via `drivingServiceMode: DrivingServiceMode.host` in `AvatarKit.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.host` in `AvatarSDK.initialize()`
 - Host application manages its own network/data fetching
 - Host application provides both audio and animation data
 - SDK only handles synchronized playback
 - Best for: Custom data sources, pre-recorded content, or custom network implementations
 
-**Note:** The playback mode is determined by `drivingServiceMode` in `AvatarKit.initialize()` configuration.
+**Note:** The playback mode is determined by `drivingServiceMode` in `AvatarSDK.initialize()` configuration.
 
 ### Fallback Mechanism
 
@@ -209,40 +209,40 @@ RenderSystem → WebGPU/WebGL → Canvas rendering
 
 ## 📚 API Reference
 
-### AvatarKit
+### AvatarSDK
 
 The core management class of the SDK, responsible for initialization and global configuration.
 
 ```typescript
 // Initialize SDK
-await AvatarKit.initialize(appId: string, configuration: Configuration)
+await AvatarSDK.initialize(appId: string, configuration: Configuration)
 
 // Check initialization status
-const isInitialized = AvatarKit.isInitialized
+const isInitialized = AvatarSDK.isInitialized
 
 // Get initialized app ID
-const appId = AvatarKit.appId
+const appId = AvatarSDK.appId
 
 // Get configuration
-const config = AvatarKit.configuration
+const config = AvatarSDK.configuration
 
 // Set sessionToken (if needed, call separately)
-AvatarKit.setSessionToken('your-session-token')
+AvatarSDK.setSessionToken('your-session-token')
 
 // Set userId (optional, for telemetry)
-AvatarKit.setUserId('user-id')
+AvatarSDK.setUserId('user-id')
 
 // Get sessionToken
-const sessionToken = AvatarKit.sessionToken
+const sessionToken = AvatarSDK.sessionToken
 
 // Get userId
-const userId = AvatarKit.userId
+const userId = AvatarSDK.userId
 
 // Get SDK version
-const version = AvatarKit.version
+const version = AvatarSDK.version
 
 // Cleanup resources (must be called when no longer in use)
-AvatarKit.cleanup()
+AvatarSDK.cleanup()
 ```
 
 ### AvatarManager
@@ -280,7 +280,7 @@ constructor(avatar: Avatar, container: HTMLElement)
   - SDK automatically handles resize events via ResizeObserver
 
 **Playback Mode:**
-- The playback mode is determined by `drivingServiceMode` in `AvatarKit.initialize()` configuration
+- The playback mode is determined by `drivingServiceMode` in `AvatarSDK.initialize()` configuration
 - The playback mode is fixed when creating `AvatarView` and persists throughout its lifecycle
 - Cannot be changed after creation
 
@@ -403,7 +403,7 @@ avatarView.avatarController.onError = (error: Error) => {}
 interface Configuration {
   environment: Environment
   drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (SDK mode)
-  logLevel?: LogLevel  // Optional, default is 'all' (all logs)
+  logLevel?: LogLevel  // Optional, default is 'off' (no logs)
 }
 ```
 
@@ -423,22 +423,21 @@ enum LogLevel {
 **Note:** `LogLevel.off` completely disables all logging, including error logs. Use with caution in production environments.
 
 **Description:**
-- `environment`: Specifies the environment (cn/intl/test), SDK will automatically use the corresponding API address and WebSocket address based on the environment
+- `environment`: Specifies the environment (cn/intl), 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
 - `logLevel`: Controls the verbosity of SDK logs
-  - `LogLevel.off`: Disable all logs
+  - `LogLevel.off` (default): Disable all logs
   - `LogLevel.error`: Only error logs
   - `LogLevel.warning`: Warning and error logs
-  - `LogLevel.all` (default): All logs (info, warning, error)
-- `sessionToken`: Set separately via `AvatarKit.setSessionToken()`, not in Configuration
+  - `LogLevel.all`: All logs (info, warning, error)
+- `sessionToken`: Set separately via `AvatarSDK.setSessionToken()`, not in Configuration
 
 ```typescript
 enum Environment {
   cn = 'cn',    // China region
   intl = 'intl',    // International region
-  test = 'test' // Test environment
 }
 ```
 

package/dist/StreamingAudioPlayer-C-_1X8K-.js

@@ -0,0 +1,398 @@
+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, e as errorToMessage, l as logEvent, a as logger } from "./index-BpVIIm3g.js";
+class StreamingAudioPlayer {
+  constructor(options) {
+    __publicField(this, "audioContext", null);
+    __publicField(this, "sampleRate");
+    __publicField(this, "channelCount");
+    __publicField(this, "debug");
+    __publicField(this, "sessionId");
+    __publicField(this, "sessionStartTime", 0);
+    __publicField(this, "pausedTimeOffset", 0);
+    __publicField(this, "pausedAt", 0);
+    __publicField(this, "pausedAudioContextTime", 0);
+    __publicField(this, "scheduledTime", 0);
+    __publicField(this, "isPlaying", false);
+    __publicField(this, "isPaused", false);
+    __publicField(this, "autoStartEnabled", true);
+    __publicField(this, "audioChunks", []);
+    __publicField(this, "scheduledChunks", 0);
+    __publicField(this, "activeSources", /* @__PURE__ */ new Set());
+    __publicField(this, "gainNode", null);
+    __publicField(this, "volume", 1);
+    __publicField(this, "onEndedCallback");
+    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.sampleRate = (options == null ? void 0 : options.sampleRate) ?? APP_CONFIG.audio.sampleRate;
+    this.channelCount = (options == null ? void 0 : options.channelCount) ?? 1;
+    this.debug = (options == null ? void 0 : options.debug) ?? false;
+  }
+  async initialize() {
+    if (this.audioContext) {
+      return;
+    }
+    try {
+      this.audioContext = new AudioContext({
+        sampleRate: this.sampleRate
+      });
+      this.gainNode = this.audioContext.createGain();
+      this.gainNode.gain.value = this.volume;
+      this.gainNode.connect(this.audioContext.destination);
+      if (this.audioContext.state === "suspended") {
+        await this.audioContext.resume();
+      }
+      this.log("AudioContext initialized", {
+        sessionId: this.sessionId,
+        sampleRate: this.audioContext.sampleRate,
+        state: this.audioContext.state
+      });
+    } catch (error) {
+      const message = errorToMessage(error);
+      logEvent("activeAudioSessionFailed", "warning", {
+        sessionId: this.sessionId,
+        reason: message
+      });
+      logger.error("Failed to initialize AudioContext:", message);
+      throw error instanceof Error ? error : new Error(message);
+    }
+  }
+  addChunk(pcmData, isLast = false) {
+    if (!this.audioContext) {
+      logger.error("AudioContext not initialized");
+      return;
+    }
+    this.audioChunks.push({ data: pcmData, isLast });
+    this.log(`Added chunk ${this.audioChunks.length}`, {
+      size: pcmData.length,
+      totalChunks: this.audioChunks.length,
+      isLast,
+      isPlaying: this.isPlaying,
+      scheduledChunks: this.scheduledChunks
+    });
+    if (!this.isPlaying && this.autoStartEnabled && this.audioChunks.length > 0) {
+      this.log("[StreamingAudioPlayer] Auto-starting playback from addChunk");
+      this.startPlayback();
+    } else if (this.isPlaying && !this.isPaused) {
+      this.log("[StreamingAudioPlayer] Already playing, scheduling next chunk");
+      this.scheduleNextChunk();
+    } else {
+      this.log("[StreamingAudioPlayer] Not playing and no chunks, waiting for more chunks");
+    }
+  }
+  async startNewSession(audioChunks) {
+    this.stop();
+    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.audioChunks = [];
+    this.scheduledChunks = 0;
+    this.pausedTimeOffset = 0;
+    this.pausedAt = 0;
+    this.pausedAudioContextTime = 0;
+    this.log("Starting new session", {
+      chunks: audioChunks.length
+    });
+    for (const chunk of audioChunks) {
+      this.addChunk(chunk.data, chunk.isLast);
+    }
+  }
+  startPlayback() {
+    if (!this.audioContext) {
+      this.log("[StreamingAudioPlayer] Cannot start playback: AudioContext not initialized");
+      return;
+    }
+    if (this.isPlaying) {
+      this.log("[StreamingAudioPlayer] Cannot start playback: Already playing");
+      return;
+    }
+    this.isPlaying = true;
+    this.sessionStartTime = this.audioContext.currentTime;
+    this.scheduledTime = this.sessionStartTime;
+    this.log("[StreamingAudioPlayer] Starting playback", {
+      sessionStartTime: this.sessionStartTime,
+      bufferedChunks: this.audioChunks.length,
+      scheduledChunks: this.scheduledChunks,
+      activeSources: this.activeSources.size
+    });
+    this.scheduleAllChunks();
+  }
+  scheduleAllChunks() {
+    while (this.scheduledChunks < this.audioChunks.length) {
+      this.scheduleNextChunk();
+    }
+  }
+  scheduleNextChunk() {
+    if (!this.audioContext) {
+      this.log("[StreamingAudioPlayer] Cannot schedule chunk: AudioContext not initialized");
+      return;
+    }
+    if (!this.isPlaying || this.isPaused) {
+      this.log("[StreamingAudioPlayer] Cannot schedule chunk: Not playing or paused");
+      return;
+    }
+    const chunkIndex = this.scheduledChunks;
+    if (chunkIndex >= this.audioChunks.length) {
+      this.log(`[StreamingAudioPlayer] No more chunks to schedule (chunkIndex: ${chunkIndex}, totalChunks: ${this.audioChunks.length})`);
+      return;
+    }
+    const chunk = this.audioChunks[chunkIndex];
+    if (chunk.data.length === 0 && !chunk.isLast) {
+      this.scheduledChunks++;
+      return;
+    }
+    const pcmData = chunk.data;
+    const isLast = chunk.isLast;
+    const audioBuffer = this.pcmToAudioBuffer(pcmData);
+    if (!audioBuffer) {
+      const errorMessage = "Failed to create AudioBuffer from PCM data";
+      logger.error(errorMessage);
+      logEvent("character_player", "error", {
+        sessionId: this.sessionId,
+        event: "audio_buffer_creation_failed"
+      });
+      return;
+    }
+    try {
+      const source = this.audioContext.createBufferSource();
+      source.buffer = audioBuffer;
+      source.connect(this.gainNode);
+      source.start(this.scheduledTime);
+      this.activeSources.add(source);
+      source.onended = () => {
+        this.activeSources.delete(source);
+        if (isLast && this.activeSources.size === 0) {
+          this.log("Last audio chunk ended, marking playback as ended");
+          this.markEnded();
+        }
+      };
+      this.scheduledTime += audioBuffer.duration;
+      this.scheduledChunks++;
+      this.log(`[StreamingAudioPlayer] Scheduled chunk ${chunkIndex + 1}/${this.audioChunks.length}`, {
+        startTime: this.scheduledTime - audioBuffer.duration,
+        duration: audioBuffer.duration,
+        nextScheduleTime: this.scheduledTime,
+        isLast,
+        activeSources: this.activeSources.size
+      });
+    } catch (err) {
+      logger.errorWithError("Failed to schedule audio chunk:", err);
+      logEvent("character_player", "error", {
+        sessionId: this.sessionId,
+        event: "schedule_chunk_failed",
+        reason: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  pcmToAudioBuffer(pcmData) {
+    if (!this.audioContext) {
+      return null;
+    }
+    if (pcmData.length === 0) {
+      const silenceDuration = 0.01;
+      const numSamples2 = Math.floor(this.sampleRate * silenceDuration);
+      const audioBuffer2 = this.audioContext.createBuffer(
+        this.channelCount,
+        numSamples2,
+        this.sampleRate
+      );
+      for (let channel = 0; channel < this.channelCount; channel++) {
+        const channelData = audioBuffer2.getChannelData(channel);
+        channelData.fill(0);
+      }
+      return audioBuffer2;
+    }
+    const alignedData = new Uint8Array(pcmData);
+    const int16Array = new Int16Array(alignedData.buffer, 0, alignedData.length / 2);
+    const numSamples = int16Array.length / this.channelCount;
+    const audioBuffer = this.audioContext.createBuffer(
+      this.channelCount,
+      numSamples,
+      this.sampleRate
+    );
+    for (let channel = 0; channel < this.channelCount; channel++) {
+      const channelData = audioBuffer.getChannelData(channel);
+      for (let i = 0; i < numSamples; i++) {
+        const sampleIndex = i * this.channelCount + channel;
+        channelData[i] = int16Array[sampleIndex] / 32768;
+      }
+    }
+    return audioBuffer;
+  }
+  getCurrentTime() {
+    if (!this.audioContext || !this.isPlaying) {
+      return 0;
+    }
+    if (this.isPaused) {
+      return this.pausedAt;
+    }
+    const currentAudioTime = this.audioContext.currentTime;
+    const elapsed = currentAudioTime - this.sessionStartTime - this.pausedTimeOffset;
+    return Math.max(0, elapsed);
+  }
+  pause() {
+    if (!this.isPlaying || this.isPaused || !this.audioContext) {
+      return;
+    }
+    this.pausedAt = this.getCurrentTime();
+    this.pausedAudioContextTime = this.audioContext.currentTime;
+    this.isPaused = true;
+    if (this.audioContext.state === "running") {
+      this.audioContext.suspend().catch((err) => {
+        logger.errorWithError("Failed to suspend AudioContext:", err);
+        this.isPaused = false;
+      });
+    }
+    this.log("Playback paused", {
+      pausedAt: this.pausedAt,
+      pausedAudioContextTime: this.pausedAudioContextTime,
+      audioContextState: this.audioContext.state
+    });
+  }
+  async resume() {
+    if (!this.isPaused || !this.audioContext || !this.isPlaying) {
+      return;
+    }
+    if (this.audioContext.state === "suspended") {
+      try {
+        await this.audioContext.resume();
+      } catch (err) {
+        logger.errorWithError("Failed to resume AudioContext:", err);
+        throw err;
+      }
+    }
+    const currentAudioTime = this.audioContext.currentTime;
+    this.sessionStartTime = this.pausedAudioContextTime - this.pausedAt - this.pausedTimeOffset;
+    this.isPaused = false;
+    if (this.scheduledChunks < this.audioChunks.length) {
+      this.scheduleAllChunks();
+    }
+    this.log("Playback resumed", {
+      pausedAt: this.pausedAt,
+      pausedAudioContextTime: this.pausedAudioContextTime,
+      currentAudioContextTime: currentAudioTime,
+      adjustedSessionStartTime: this.sessionStartTime,
+      audioContextState: this.audioContext.state
+    });
+  }
+  stop() {
+    if (!this.audioContext) {
+      return;
+    }
+    if (this.isPaused && this.audioContext.state === "suspended") {
+      this.audioContext.resume().catch(() => {
+      });
+      this.isPaused = false;
+    }
+    this.isPlaying = false;
+    this.isPaused = false;
+    this.sessionStartTime = 0;
+    this.scheduledTime = 0;
+    for (const source of this.activeSources) {
+      source.onended = null;
+      try {
+        source.stop(0);
+      } catch {
+      }
+      try {
+        source.disconnect();
+      } catch {
+      }
+    }
+    this.activeSources.clear();
+    this.audioChunks = [];
+    this.scheduledChunks = 0;
+    this.log("[StreamingAudioPlayer] Playback stopped, state reset");
+  }
+  setAutoStart(enabled) {
+    this.autoStartEnabled = enabled;
+    this.log(`Auto-start ${enabled ? "enabled" : "disabled"}`);
+  }
+  play() {
+    if (this.isPlaying) {
+      return;
+    }
+    this.autoStartEnabled = true;
+    this.startPlayback();
+  }
+  markEnded() {
+    var _a;
+    this.log("Playback ended");
+    this.isPlaying = false;
+    (_a = this.onEndedCallback) == null ? void 0 : _a.call(this);
+  }
+  onEnded(callback) {
+    this.onEndedCallback = callback;
+  }
+  isPlayingNow() {
+    return this.isPlaying && !this.isPaused;
+  }
+  getBufferedDuration() {
+    if (!this.audioContext) {
+      return 0;
+    }
+    let totalSamples = 0;
+    for (const chunk of this.audioChunks) {
+      totalSamples += chunk.data.length / 2 / this.channelCount;
+    }
+    return totalSamples / this.sampleRate;
+  }
+  getRemainingDuration() {
+    const total = this.getBufferedDuration();
+    const played = this.getCurrentTime();
+    return Math.max(0, total - played);
+  }
+  dispose() {
+    this.stop();
+    if (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(options) {
+    const hard = (options == null ? void 0 : options.hard) === true;
+    if (hard) {
+      this.stop();
+      this.audioChunks = [];
+      this.scheduledChunks = 0;
+      this.sessionStartTime = 0;
+      this.pausedAt = 0;
+      this.scheduledTime = 0;
+      this.log("Flushed (hard)");
+      return;
+    }
+    if (this.scheduledChunks < this.audioChunks.length) {
+      this.audioChunks.splice(this.scheduledChunks);
+    }
+    this.log("Flushed (soft)", { remainingScheduled: this.scheduledChunks });
+  }
+  setVolume(volume) {
+    if (volume < 0 || volume > 1) {
+      logger.warn(`[StreamingAudioPlayer] Volume out of range: ${volume}, clamping to [0, 1]`);
+      volume = Math.max(0, Math.min(1, volume));
+    }
+    this.volume = volume;
+    if (this.gainNode) {
+      this.gainNode.gain.value = volume;
+    }
+  }
+  getVolume() {
+    return this.volume;
+  }
+  log(message, data) {
+    if (this.debug) {
+      logger.log(`[StreamingAudioPlayer] ${message}`, data || "");
+    }
+  }
+}
+export {
+  StreamingAudioPlayer
+};

package/dist/animation/AnimationWebSocketClient.d.ts

@@ -19,31 +19,11 @@ export declare class AnimationWebSocketClient extends EventEmitter {
     private isManuallyDisconnected;
     private reconnectTimer;
     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;