@spatialwalk/avatarkit 1.0.0-beta.57 → 1.0.0-beta.59

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.0-beta.59] - 2026-01-14
+
+### 🐛 Bugfixes
+- **AudioContext Auto-Resume** - Fixed issue where audio playback would get stuck after external applications request recording permissions. AudioContext now automatically resumes when suspended during playback
+- **PostHog Instance Initialization** - Fixed PostHog named instance initialization to avoid conflicts with external PostHog instances
+
+## [1.0.0-beta.58] - 2026-01-14
+
+### ✨ New Features
+- **Pure Rendering Mode APIs** - Added `renderFlame()` and `generateTransitionFromIdle()` methods to `AvatarView` for external-controlled rendering without audio synchronization
+
 ## [1.0.0-beta.57] - 2026-01-09
 
 ### 🐛 Bugfixes

package/dist/{StreamingAudioPlayer-Co3xec_k.js → StreamingAudioPlayer-BbUBoPqm.js}

@@ -1,7 +1,7 @@
 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-cfYSlUmQ.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-B0MJ_hCJ.js";
 class StreamingAudioPlayer {
   constructor(options) {
     __publicField(this, "audioContext", null);
@@ -27,6 +27,8 @@ class StreamingAudioPlayer {
     __publicField(this, "gainNode", null);
     __publicField(this, "volume", 1);
     __publicField(this, "onEndedCallback");
+    __publicField(this, "stateChangeHandler");
+    __publicField(this, "isResuming", false);
     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;
@@ -46,6 +48,15 @@ class StreamingAudioPlayer {
       if (this.audioContext.state === "suspended") {
         await this.audioContext.resume();
       }
+      this.stateChangeHandler = (event) => {
+        const context = event.target;
+        if (context.state === "suspended" && this.isPlaying && !this.isPaused) {
+          this.ensureAudioContextRunning().catch((err) => {
+            logger.errorWithError("[StreamingAudioPlayer] Failed to auto-resume AudioContext after external suspend:", err);
+          });
+        }
+      };
+      this.audioContext.addEventListener("statechange", this.stateChangeHandler);
       this.log("AudioContext initialized", {
         sessionId: this.sessionId,
         sampleRate: this.audioContext.sampleRate,
@@ -61,11 +72,64 @@ class StreamingAudioPlayer {
       throw error instanceof Error ? error : new Error(message);
     }
   }
+  async ensureAudioContextRunning() {
+    if (!this.audioContext) {
+      return;
+    }
+    const state = this.audioContext.state;
+    if (state === "running") {
+      return;
+    }
+    if (state === "closed") {
+      this.log("AudioContext is closed, cannot resume", {
+        sessionId: this.sessionId,
+        state
+      });
+      return;
+    }
+    if (state === "suspended" && this.isPlaying && !this.isPaused) {
+      if (this.isResuming) {
+        this.log("AudioContext resume already in progress, skipping duplicate request", {
+          sessionId: this.sessionId,
+          state
+        });
+        return;
+      }
+      this.isResuming = true;
+      try {
+        this.log("AudioContext is suspended during playback, resuming...", {
+          sessionId: this.sessionId,
+          state,
+          isPlaying: this.isPlaying,
+          isPaused: this.isPaused
+        });
+        await this.audioContext.resume();
+        this.log("AudioContext resumed successfully", {
+          sessionId: this.sessionId,
+          state: this.audioContext.state
+        });
+      } catch (err) {
+        logger.errorWithError("[StreamingAudioPlayer] Failed to resume AudioContext:", err);
+        logEvent("character_player", "error", {
+          sessionId: this.sessionId,
+          event: "audio_context_resume_failed",
+          reason: err instanceof Error ? err.message : String(err)
+        });
+      } finally {
+        this.isResuming = false;
+      }
+    }
+  }
   addChunk(pcmData, isLast = false) {
     if (!this.audioContext) {
       logger.error("AudioContext not initialized");
       return;
     }
+    if (this.isPlaying && !this.isPaused && this.audioContext.state === "suspended") {
+      this.ensureAudioContextRunning().catch((err) => {
+        logger.errorWithError("[StreamingAudioPlayer] Failed to ensure AudioContext running in addChunk:", err);
+      });
+    }
     this.audioChunks.push({ data: pcmData, isLast });
     this.log(`Added chunk ${this.audioChunks.length}`, {
       size: pcmData.length,
@@ -83,7 +147,9 @@ class StreamingAudioPlayer {
     }
     if (!this.isPlaying && this.autoStartEnabled && this.audioChunks.length > 0) {
       this.log("[StreamingAudioPlayer] Auto-starting playback from addChunk");
-      this.startPlayback();
+      this.startPlayback().catch((err) => {
+        logger.errorWithError("[StreamingAudioPlayer] Failed to start playback from addChunk:", err);
+      });
     } else if (this.isPlaying && !this.isPaused) {
       this.log("[StreamingAudioPlayer] Already playing, scheduling next chunk");
       this.scheduleNextChunk();
@@ -107,7 +173,7 @@ class StreamingAudioPlayer {
       this.addChunk(chunk.data, chunk.isLast);
     }
   }
-  startPlayback() {
+  async startPlayback() {
     if (!this.audioContext) {
       this.log("[StreamingAudioPlayer] Cannot start playback: AudioContext not initialized");
       return;
@@ -116,6 +182,7 @@ class StreamingAudioPlayer {
       this.log("[StreamingAudioPlayer] Cannot start playback: Already playing");
       return;
     }
+    await this.ensureAudioContextRunning();
     this.isPlaying = true;
     this.sessionStartTime = this.audioContext.currentTime;
     this.scheduledTime = this.sessionStartTime;
@@ -126,7 +193,8 @@ class StreamingAudioPlayer {
       sessionStartTime: this.sessionStartTime,
       bufferedChunks: this.audioChunks.length,
       scheduledChunks: this.scheduledChunks,
-      activeSources: this.activeSources.size
+      activeSources: this.activeSources.size,
+      audioContextState: this.audioContext.state
     });
     this.scheduleAllChunks();
   }
@@ -144,6 +212,11 @@ class StreamingAudioPlayer {
       this.log("[StreamingAudioPlayer] Cannot schedule chunk: Not playing or paused");
       return;
     }
+    if (this.audioContext.state === "suspended") {
+      this.ensureAudioContextRunning().catch((err) => {
+        logger.errorWithError("[StreamingAudioPlayer] Failed to ensure AudioContext running in scheduleNextChunk:", err);
+      });
+    }
     const chunkIndex = this.scheduledChunks;
     if (chunkIndex >= this.audioChunks.length) {
       this.log(`[StreamingAudioPlayer] No more chunks to schedule (chunkIndex: ${chunkIndex}, totalChunks: ${this.audioChunks.length})`);
@@ -345,6 +418,7 @@ class StreamingAudioPlayer {
     }
     this.isPlaying = false;
     this.isPaused = false;
+    this.isResuming = false;
     this.sessionStartTime = 0;
     this.scheduledTime = 0;
     for (const source of this.activeSources) {
@@ -373,7 +447,9 @@ class StreamingAudioPlayer {
       return;
     }
     this.autoStartEnabled = true;
-    this.startPlayback();
+    this.startPlayback().catch((err) => {
+      logger.errorWithError("[StreamingAudioPlayer] Failed to start playback from play():", err);
+    });
   }
   markEnded() {
     var _a;
@@ -389,6 +465,10 @@ class StreamingAudioPlayer {
   }
   dispose() {
     this.stop();
+    if (this.audioContext && this.stateChangeHandler) {
+      this.audioContext.removeEventListener("statechange", this.stateChangeHandler);
+      this.stateChangeHandler = void 0;
+    }
     if (this.audioContext) {
       this.audioContext.close();
       this.audioContext = null;

package/dist/audio/StreamingAudioPlayer.d.ts

@@ -27,8 +27,11 @@ export declare class StreamingAudioPlayer {
     private gainNode;
     private volume;
     private onEndedCallback?;
+    private stateChangeHandler?;
+    private isResuming;
     constructor(options?: StreamingAudioPlayerOptions);
     initialize(): Promise<void>;
+    private ensureAudioContextRunning;
     addChunk(pcmData: Uint8Array, isLast?: boolean): void;
     startNewSession(audioChunks: Array<{
         data: Uint8Array;

package/dist/config/sdk-config-loader.d.ts

@@ -1,5 +1,7 @@
 import { Environment } from '../types';
 
+export declare const DEFAULT_SDK_CONFIG: Partial<Record<Environment, string>>;
+
 export declare function fetchSdkConfig(version: string): Promise<Partial<Record<Environment, string>>>;
 
 export declare function clearSdkConfigCache(): void;

package/dist/core/AvatarView.d.ts

@@ -27,6 +27,7 @@ export declare class AvatarView {
     private idleCurrentFrameIndex;
     private characterHandle;
     private characterId;
+    private isPureRenderingMode;
     private alignFlamePair;
     private generateAndAlignTransitionFrames;
     private getCachedIdleFirstFrame;
@@ -57,7 +58,8 @@ export declare class AvatarView {
     private startRealtimeRendering;
     private stopRealtimeRendering;
     dispose(): void;
-    renderFlame(flame: Flame): Promise<void>;
+    renderFlame(flame: Flame, enableIdleRendering?: boolean): Promise<void>;
+    generateTransitionFromIdle(toFlame: Flame, frameCount: number): Promise<Flame[]>;
     private rerenderCurrentFrameWithNewCamera;
     private handleResize;
     get transform(): {

package/dist/{index-cfYSlUmQ.js → index-B0MJ_hCJ.js}

@@ -7397,19 +7397,7 @@ let isInitialized = false;
 const SDK_POSTHOG_INSTANCE_NAME = "spatialwalk-posthog";
 let sdkPosthogInstance = null;
 const eventQueue = [];
-const FILTERED_HOSTNAMES = ["localhost", "127.0.0.1", "0.0.0.0"];
-function shouldFilterHostname() {
-  if (typeof window === "undefined") {
-    return false;
-  }
-  const hostname = window.location.hostname;
-  return FILTERED_HOSTNAMES.includes(hostname);
-}
 function initializePostHog(environment, version) {
-  if (shouldFilterHostname()) {
-    logger.log(`[PostHog] Tracking disabled due to filtered hostname: ${window.location.hostname}`);
-    return;
-  }
   const { host, apiKey, disableCompression } = getPostHogConfig(environment);
   if (!apiKey) {
     logger.warn(`[PostHog] API Key not configured for environment: ${environment}, tracking disabled`);
@@ -7425,7 +7413,6 @@ function initializePostHog(environment, version) {
     const logContext = idManager.getLogContext();
     Vo.init(apiKey, {
       api_host: host,
-      name: SDK_POSTHOG_INSTANCE_NAME,
       person_profiles: "identified_only",
       capture_pageview: false,
       capture_pageleave: false,
@@ -7455,7 +7442,7 @@ function initializePostHog(environment, version) {
         }
         flushEventQueue();
       }
-    });
+    }, SDK_POSTHOG_INSTANCE_NAME);
   } catch (error) {
     logger.warn("[PostHog] Failed to initialize:", error instanceof Error ? error.message : String(error));
   }
@@ -7505,9 +7492,6 @@ function flushEventQueue() {
   }, 0);
 }
 function trackEvent(event, level = "info", contents = {}) {
-  if (shouldFilterHostname()) {
-    return;
-  }
   const instance = getSdkPosthogInstance();
   if (!instance) {
     eventQueue.push({ event, level, contents });
@@ -7639,7 +7623,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-Co3xec_k.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-BbUBoPqm.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -7786,6 +7770,10 @@ const _AnimationPlayer = class _AnimationPlayer {
 };
 __publicField(_AnimationPlayer, "audioUnlocked", false);
 let AnimationPlayer = _AnimationPlayer;
+const DEFAULT_SDK_CONFIG = {
+  [Environment.cn]: "https://api.open.spatialwalk.top",
+  [Environment.intl]: "https://api.intl.spatialwalk.cloud"
+};
 const configCache = {
   config: null,
   promise: null
@@ -7824,10 +7812,7 @@ async function fetchSdkConfig(version) {
       configCache.config = config;
       logger.log(`[SdkConfigLoader] SDK config fetched successfully:`, config);
     } catch (error) {
-      configCache.config = {
-        [Environment.cn]: "https://api.open.spatialwalk.top",
-        [Environment.intl]: "https://api.intl.spatialwalk.cloud"
-      };
+      configCache.config = { ...DEFAULT_SDK_CONFIG };
       logger.log("[SdkConfigLoader] Using default SDK config:", configCache.config);
     } finally {
       configCache.promise = null;
@@ -8887,6 +8872,7 @@ class AvatarSDK {
       idManager.setAppId(appId);
       logger.log(`[AvatarSDK] Client ID: ${idManager.getClientId()}`);
       initializePostHog(configuration.environment, this._version);
+      this._dynamicSdkConfig = { ...DEFAULT_SDK_CONFIG };
       this._fetchSdkConfig().catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         logger.warn("Failed to fetch SDK config from remote, using defaults:", message);
@@ -9062,7 +9048,7 @@ class AvatarSDK {
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.57");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.59");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = Object.freeze(Object.defineProperty({
@@ -11419,7 +11405,6 @@ class AvatarController {
       return true;
     }
     const audioContextState = ((_c = streamingPlayer.audioContext) == null ? void 0 : _c.state) || "unknown";
-    const isAudioContextSuspended = audioContextState === "suspended";
     const activeSourcesCount = ((_d = streamingPlayer.activeSources) == null ? void 0 : _d.size) || 0;
     const scheduledChunks = streamingPlayer.scheduledChunks || 0;
     const hasScheduledButNoActive = scheduledChunks > 0 && activeSourcesCount === 0;
@@ -11434,7 +11419,7 @@ class AvatarController {
       state.audioTimeStuckCount = 0;
     }
     state.lastAudioTime = audioTime;
-    const shouldReport = state.audioTimeZeroCount > this.MAX_AUDIO_TIME_ZERO_COUNT || state.audioTimeStuckCount > this.MAX_AUDIO_TIME_STUCK_COUNT || isAudioContextSuspended && this.isPlaying || hasScheduledButNoActive && this.isPlaying;
+    const shouldReport = state.audioTimeZeroCount > this.MAX_AUDIO_TIME_ZERO_COUNT || state.audioTimeStuckCount > this.MAX_AUDIO_TIME_STUCK_COUNT || hasScheduledButNoActive && this.isPlaying;
     if (shouldReport && isNotPaused) {
       state.reported = true;
       logEvent("character_player", "error", {
@@ -11442,7 +11427,6 @@ class AvatarController {
         avatar_id: this.avatar.id,
         conversationId: ((_e2 = this.networkLayer) == null ? void 0 : _e2.getCurrentConversationId()) || void 0,
         audioContextState,
-        isAudioContextSuspended,
         audioTime,
         audioTimeZero: audioTime === 0,
         audioTimeZeroCount: state.audioTimeZeroCount,
@@ -13990,6 +13974,7 @@ class AvatarView {
     __publicField(this, "idleCurrentFrameIndex", 0);
     __publicField(this, "characterHandle", null);
     __publicField(this, "characterId");
+    __publicField(this, "isPureRenderingMode", false);
     this.avatar = avatar;
     this.characterId = `${avatar.id}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
     if (!AvatarSDK.configuration) {
@@ -14335,6 +14320,10 @@ class AvatarView {
           return;
         }
         lastTime = currentTime;
+        if (this.isPureRenderingMode) {
+          this.idleAnimationLoopId = requestAnimationFrame(renderFrame);
+          return;
+        }
         const avatarCore = AvatarSDK.getAvatarCore();
         if (!avatarCore) {
           return;
@@ -14345,6 +14334,9 @@ class AvatarView {
           if (this.renderingState !== "idle") {
             return;
           }
+          if (this.isPureRenderingMode) {
+            return;
+          }
           this.renderSystem.loadSplatsFromPackedData(splatData);
           this.renderSystem.renderFrame();
         }
@@ -14683,10 +14675,15 @@ class AvatarView {
       }
     }
   }
-  async renderFlame(flame) {
+  async renderFlame(flame, enableIdleRendering) {
     if (!this.isInitialized || !this.renderSystem) {
       throw new Error("AvatarView not initialized");
     }
+    if (enableIdleRendering === true) {
+      this.isPureRenderingMode = false;
+      return;
+    }
+    this.isPureRenderingMode = true;
     try {
       const processedFlame = this.avatarController.applyPostProcessingToFlame(flame);
       const wasmParams = convertProtoFlameToWasmParams(processedFlame);
@@ -14707,6 +14704,38 @@ class AvatarView {
       throw error;
     }
   }
+  async generateTransitionFromIdle(toFlame, frameCount) {
+    if (!this.isInitialized) {
+      throw new Error("AvatarView not initialized");
+    }
+    if (frameCount <= 0) {
+      throw new Error("Frame count must be greater than 0");
+    }
+    const avatarCore = AvatarSDK.getAvatarCore();
+    if (!avatarCore) {
+      throw new Error("AvatarCore not available");
+    }
+    try {
+      const idleParams = await avatarCore.getCurrentFrameParams(this.idleCurrentFrameIndex, this.characterId);
+      const idleFrameProto = convertWasmParamsToProtoFlame(idleParams);
+      const toFlameWithPostProcessing = this.avatarController.applyPostProcessingToFlame(toFlame);
+      const aligned = this.alignFlamePair(idleFrameProto, toFlameWithPostProcessing);
+      const fps = APP_CONFIG.animation.fps;
+      const durationMs = frameCount / fps * 1e3;
+      const transitionFrames = generateTransitionFrames(
+        aligned.from,
+        aligned.to,
+        durationMs,
+        fps
+      );
+      transitionFrames[0] = aligned.from;
+      transitionFrames[transitionFrames.length - 1] = aligned.to;
+      return transitionFrames;
+    } catch (error) {
+      logger.error("[AvatarView] Failed to generate transition from idle:", error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  }
   async rerenderCurrentFrameWithNewCamera() {
     if (this.avatarController.state !== AvatarState.paused || this.renderingState !== "speaking" || !this.renderSystem) {
       return;
@@ -14755,7 +14784,7 @@ export {
   LogLevel$1 as L,
   ResourceType as R,
   SPAvatarError as S,
-  logger as a,
+  logEvent as a,
   Avatar as b,
   AvatarController as c,
   AvatarSDK as d,
@@ -14766,6 +14795,6 @@ export {
   ConversationState as i,
   AvatarState as j,
   ErrorCode as k,
-  logEvent as l,
+  logger as l,
   extractResourceUrls as m
 };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { b, c, f, d, j, g, C, i, D, E, k, h, L, R, S, m } from "./index-cfYSlUmQ.js";
+import { b, c, f, d, j, g, C, i, D, E, k, h, L, R, S, m } from "./index-B0MJ_hCJ.js";
 export {
   b as Avatar,
   c as AvatarController,

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.57",
-  "packageManager": "pnpm@10.18.2",
+  "version": "1.0.0-beta.59",
   "description": "SPAvatar SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "SPAvatar Team",
   "license": "MIT",
@@ -32,16 +31,6 @@
     "CHANGELOG.md",
     "dist"
   ],
-  "scripts": {
-    "build": "SDK_BUILD=true vite build --mode library",
-    "dev": "vite build --mode library --watch",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit",
-    "test": "cd tests && pnpm test",
-    "test:watch": "cd tests && pnpm run test:watch",
-    "test:e2e": "cd tests && pnpm run test:e2e",
-    "test:perf": "cd tests && pnpm run test:perf"
-  },
   "peerDependencies": {
     "@webgpu/types": "*"
   },
@@ -58,5 +47,15 @@
     "typescript": "^5.0.0",
     "vite": "^5.0.0",
     "vite-plugin-dts": "^4.5.4"
+  },
+  "scripts": {
+    "build": "SDK_BUILD=true vite build --mode library",
+    "dev": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "cd tests && pnpm test",
+    "test:watch": "cd tests && pnpm run test:watch",
+    "test:e2e": "cd tests && pnpm run test:e2e",
+    "test:perf": "cd tests && pnpm run test:perf"
   }
-}
+}

package/dist/docs/render-flame-api-example.d.ts

@@ -1,28 +0,0 @@
-import { AvatarView, Flame } from '@spatialwalk/avatarkit';
-declare function initializeSDK(): Promise<void>;
-declare function createAvatarView(characterId: string, container: HTMLElement): Promise<AvatarView>;
-declare function fetchFlameDataFromServer(characterId: string, audioData: ArrayBuffer): Promise<Flame[]>;
-declare class FlameRenderer {
-    private avatarView;
-    private keyframes;
-    private currentFrameIndex;
-    private animationFrameId;
-    private isPlaying;
-    private fps;
-    private frameInterval;
-    private lastRenderTime;
-    constructor(avatarView: AvatarView);
-    setKeyframes(keyframes: Flame[]): void;
-    start(): void;
-    stop(): void;
-    renderFrame(frameIndex: number): Promise<void>;
-    private renderLoop;
-    setFPS(fps: number): void;
-    seek(frameIndex: number): void;
-    getCurrentFrameIndex(): number;
-    getTotalFrames(): number;
-}
-declare function main(): Promise<void>;
-declare function fetchAudioData(): Promise<ArrayBuffer>;
-
-export { initializeSDK, createAvatarView, fetchFlameDataFromServer, FlameRenderer, main, fetchAudioData };