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

package/CHANGELOG.md

@@ -5,7 +5,25 @@ 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).
 
-## [Unreleased]
+## [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
 

package/README.md

@@ -36,11 +36,11 @@ 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
@@ -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)
+  - `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;

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

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

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

@@ -10,16 +10,9 @@ export interface FlameParams {
     eyelid?: number[];
     has_eyelid?: boolean;
 }
-/**
- * Convert proto Flame to WASM FlameParams format
- */
+
 export declare function convertProtoFlameToWasmParams(protoFlame: Flame): FlameParams;
-/**
- * Convert WASM FlameParams to proto Flame format
- * Used for transition animation from idle to speaking
- */
+
 export declare function convertWasmParamsToProtoFlame(wasmParams: FlameParams): Flame;
-/**
- * Create a neutral proto Flame (zero pose)
- */
+
 export declare function createNeutralFlameProto(): Flame;

package/dist/audio/AnimationPlayer.d.ts

@@ -7,69 +7,23 @@ export declare class AnimationPlayer {
     private onEndedCallback?;
     private static audioUnlocked;
     private useStreaming;
-    /**
-     * 解锁音频上下文（Safari 自动播放策略）
-     * 必须在用户交互事件（如 click）中调用
-     */
     static unlockAudioContext(): Promise<void>;
-    /**
-     * Initialize with HTMLAudioElement (traditional way)
-     */
     initialize(audioUrl: string, onEnded?: () => void): Promise<void>;
-    /**
-     * Initialize with StreamingAudioPlayer (streaming way)
-     * @deprecated 使用 prepareStreamingPlayer() 代替
-     */
     initializeStreaming(streamingPlayer: StreamingAudioPlayer, onEnded?: () => void): Promise<void>;
-    /**
-     * 检查流式播放器是否已准备好
-     */
     isStreamingReady(): boolean;
-    /**
-     * 获取流式播放器实例
-     */
     getStreamingPlayer(): StreamingAudioPlayer | null;
-    /**
-     * 创建并初始化流式播放器
-     * 在服务连接建立时调用
-     */
     createAndInitializeStreamingPlayer(): Promise<void>;
-    /**
-     * 准备流式播放器（如果未创建则创建并初始化）
-     * 停止之前的播放并更新结束回调
-     */
     prepareStreamingPlayer(onEnded?: () => void): Promise<void>;
     private setupEventListeners;
     play(): Promise<void>;
     stop(): void;
     isPlaying(): boolean;
     getCurrentFrameIndex(): number;
-    /**
-     * Get current playback time
-     */
     getCurrentTime(): number;
-    /**
-     * 添加音频块（仅用于流式播放）
-     */
     addAudioChunk(audio: Uint8Array, isLast?: boolean): void;
-    /**
-     * 暂停播放
-     */
     pause(): void;
-    /**
-     * 继续播放
-     */
     resume(): Promise<void>;
-    /**
-     * 设置音量 (0.0 - 1.0)
-     * 注意：这仅控制数字人音频播放器的音量，不影响系统音量
-     * @param volume 音量值，范围 0.0 到 1.0（0.0 为静音，1.0 为最大音量）
-     */
     setVolume(volume: number): void;
-    /**
-     * 获取当前音量
-     * @returns 当前音量值 (0.0 - 1.0)
-     */
     getVolume(): number;
     dispose(): void;
 }