@spatialwalk/avatarkit 1.0.0-beta.62 → 1.0.0-beta.64

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.0-beta.64] - 2026-01-14
+
+### ✨ New Features
+- **Vite Plugin for WASM Configuration** - Added `avatarkitVitePlugin` to automate WASM file configuration
+  - Automatically handles WASM MIME types in dev server
+  - Copies WASM files to dist/assets/ during build
+  - Generates `_headers` file for Cloudflare Pages deployment
+  - Configures Vite's optimizeDeps, assetsInclude, and assetsInlineLimit
+
+### 🔧 Improvements
+- **Unified Transition Logic** - All transitions now start from the current playing frame, ensuring smooth transitions from any state (Idle, Speaking, or Transitioning)
+- **Idle State Performance** - Optimized idle state to avoid unnecessary frame parameter fetching on every frame
+- **Transition Animation** - Idle->Speaking uses linear interpolation, Speaking->Idle uses Bezier curve easing
+
+### 🐛 Bugfixes
+- Fixed vanilla demo audio context initialization issue
+- Fixed recording button only working once in vanilla demo
+- Fixed host mode data loading to use local files instead of API endpoint
+
+### 📚 Documentation
+- Added transition animation technical specification document for cross-platform alignment
+
+## [1.0.0-beta.63] - 2026-01-14
+
+### ✨ New Features
+- **Audio Context Initialization API** - Added `initializeAudioContext()` method to `AvatarController`
+  - Must be called in a user gesture context (click, touchstart, etc.) before any audio operations
+  - Ensures AudioContext is created and initialized in a user gesture context, preventing browser security policy issues
+  - All audio operations (`send()`, `yieldAudioData()`, `start()`, `playback()`, etc.) now require prior initialization
+
+### 🔧 Improvements
+- **Initialization Flow** - Removed all lazy initialization logic for audio context
+  - Audio context initialization is now centralized in `initializeAudioContext()` method
+  - All audio operations check for initialization before proceeding
+  - Clear error messages when audio operations are attempted without initialization
+
+### 🐛 Bugfixes
+- **Audio Context User Gesture Requirement** - Fixed issue where AudioContext could not be properly initialized when external applications request recording permissions
+  - Audio context must now be initialized in user gesture context, ensuring browser security policies are satisfied
+
 ## [1.0.0-beta.62] - 2026-01-14
 
 ### ✨ New Features

package/README.md

@@ -18,8 +18,76 @@ Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supportin
 npm install @spatialwalk/avatarkit
 ```
 
+## 🔧 Vite 配置（推荐）
+
+如果你使用 Vite 作为构建工具，强烈推荐使用我们的 Vite 插件来自动处理 WASM 文件配置。插件会自动处理所有必要的配置，让你无需手动设置。
+
+### 使用插件
+
+在 `vite.config.ts` 中添加插件：
+
+```typescript
+import { defineConfig } from 'vite'
+import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
+
+export default defineConfig({
+  plugins: [
+    avatarkitVitePlugin(), // 添加这一行即可
+  ],
+})
+```
+
+### 插件功能
+
+插件会自动处理：
+
+- ✅ **开发服务器**：自动设置 WASM 文件的正确 MIME 类型 (`application/wasm`)
+- ✅ **构建时**：自动复制 WASM 文件到 `dist/assets/` 目录
+- ✅ **Cloudflare Pages**：自动生成 `_headers` 文件
+- ✅ **Vite 配置**：自动配置 `optimizeDeps`、`assetsInclude`、`assetsInlineLimit` 等选项
+
+### 手动配置（不使用插件）
+
+如果你不使用 Vite 插件，需要手动配置以下内容：
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['@spatialwalk/avatarkit'],
+  },
+  assetsInclude: ['**/*.wasm'],
+  build: {
+    assetsInlineLimit: 0,
+    rollupOptions: {
+      output: {
+        assetFileNames: (assetInfo) => {
+          if (assetInfo.name?.endsWith('.wasm')) {
+            return 'assets/[name][extname]'
+          }
+          return 'assets/[name]-[hash][extname]'
+        },
+      },
+    },
+  },
+  // 开发服务器需要手动配置中间件设置 WASM MIME 类型
+  configureServer(server) {
+    server.middlewares.use((req, res, next) => {
+      if (req.url?.endsWith('.wasm')) {
+        res.setHeader('Content-Type', 'application/wasm')
+      }
+      next()
+    })
+  },
+})
+```
+
 ## 🎯 Quick Start
 
+### ⚠️ Important: Audio Context Initialization
+
+**Before using any audio-related features, you MUST initialize the audio context in a user gesture context** (e.g., `click`, `touchstart` event handlers). This is required by browser security policies. Calling `initializeAudioContext()` outside a user gesture will fail.
+
 ### Basic Usage
 
 ```typescript
@@ -70,13 +138,21 @@ const avatar = await avatarManager.load('character-id', (progress) => {
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
-// 4. Start real-time communication (SDK mode only)
-await avatarView.avatarController.start()
-
-// 5. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
-const audioData = new ArrayBuffer(1024) // Example: PCM16 audio data at configured sample rate
-avatarView.avatarController.send(audioData, false) // Send audio data
-avatarView.avatarController.send(audioData, true) // end=true marks the end of current conversation round
+// 4. ⚠️ CRITICAL: Initialize audio context (MUST be called in user gesture context)
+// This method MUST be called within a user gesture event handler (click, touchstart, etc.)
+// to satisfy browser security policies. Calling it outside a user gesture will fail.
+button.addEventListener('click', async () => {
+  // Initialize audio context - MUST be in user gesture context
+  await avatarView.controller.initializeAudioContext()
+  
+  // 5. Start real-time communication (SDK mode only)
+  await avatarView.controller.start()
+  
+  // 6. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
+  const audioData = new ArrayBuffer(1024) // Example: PCM16 audio data at configured sample rate
+  avatarView.controller.send(audioData, false) // Send audio data
+  avatarView.controller.send(audioData, true) // end=true marks the end of current conversation round
+})
 ```
 
 ### Host Mode Example
@@ -89,10 +165,17 @@ avatarView.avatarController.send(audioData, true) // end=true marks the end of c
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
-// 4. Host Mode Workflow:
-// Send audio data first to get conversationId, then use it to send animation data
-const conversationId = avatarView.avatarController.yieldAudioData(audioData, false)
-avatarView.avatarController.yieldFramesData(animationDataArray, conversationId) // animationDataArray: (Uint8Array | ArrayBuffer)[]
+// 4. ⚠️ CRITICAL: Initialize audio context (MUST be called in user gesture context)
+// This method MUST be called within a user gesture event handler (click, touchstart, etc.)
+// to satisfy browser security policies. Calling it outside a user gesture will fail.
+button.addEventListener('click', async () => {
+  // Initialize audio context - MUST be in user gesture context
+  await avatarView.controller.initializeAudioContext()
+  
+  // 5. Host Mode Workflow:
+  // Send audio data first to get conversationId, then use it to send animation data
+  const conversationId = avatarView.controller.yieldAudioData(audioData, false)
+  avatarView.controller.yieldFramesData(animationDataArray, conversationId) // animationDataArray: (Uint8Array | ArrayBuffer)[]
 ```
 
 ### Complete Examples
@@ -350,34 +433,52 @@ Audio/animation playback controller (playback layer), manages synchronized playb
 #### SDK Mode Methods
 
 ```typescript
-// Start WebSocket service
-await avatarView.avatarController.start()
-
-// 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
-// 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
+// ⚠️ CRITICAL: Initialize audio context first (MUST be called in user gesture context)
+// This method MUST be called within a user gesture event handler (click, touchstart, etc.)
+// to satisfy browser security policies. Calling it outside a user gesture will fail.
+// All audio operations (start, send, etc.) require prior initialization.
+button.addEventListener('click', async () => {
+  // Initialize audio context - MUST be in user gesture context
+  await avatarView.controller.initializeAudioContext()
+  
+  // Start WebSocket service
+  await avatarView.controller.start()
+  
+  // Send audio data (must be 16kHz mono PCM16 format)
+  const conversationId = avatarView.controller.send(audioData: ArrayBuffer, end: boolean)
+  // 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
+})
 
 // Close WebSocket service
-avatarView.avatarController.close()
+avatarView.controller.close()
 ```
 
 #### Host Mode Methods
 
 ```typescript
-// 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
-
-// Stream animation keyframes (requires conversationId from audio data)
-avatarView.avatarController.yieldFramesData(
-  keyframesDataArray: (Uint8Array | ArrayBuffer)[],  // Animation keyframes binary data array (each element is a protobuf encoded Message)
-  conversationId: string                              // Conversation ID (required)
-)
+// ⚠️ CRITICAL: Initialize audio context first (MUST be called in user gesture context)
+// This method MUST be called within a user gesture event handler (click, touchstart, etc.)
+// to satisfy browser security policies. Calling it outside a user gesture will fail.
+// All audio operations (yieldAudioData, yieldFramesData, etc.) require prior initialization.
+button.addEventListener('click', async () => {
+  // Initialize audio context - MUST be in user gesture context
+  await avatarView.controller.initializeAudioContext()
+  
+  // Stream audio chunks (must be 16kHz mono PCM16 format)
+  const conversationId = avatarView.controller.yieldAudioData(
+    data: Uint8Array,               // Audio chunk data
+    isLast: boolean = false         // Whether this is the last chunk
+  )
+  // Returns: conversationId - Conversation ID for this audio session
+
+  // Stream animation keyframes (requires conversationId from audio data)
+  avatarView.controller.yieldFramesData(
+    keyframesDataArray: (Uint8Array | ArrayBuffer)[],  // Animation keyframes binary data array (each element is a protobuf encoded Message)
+    conversationId: string                              // Conversation ID (required)
+  )
+})
 ```
 
 **⚠️ Important: Conversation ID (conversationId) Management**
@@ -555,17 +656,17 @@ The rendering system automatically selects the best backend, no manual configura
 
 ## 🚨 Error Handling
 
-### SPAvatarError
+### AvatarError
 
 The SDK uses custom error types, providing more detailed error information:
 
 ```typescript
-import { SPAvatarError } from '@spatialwalk/avatarkit'
+import { AvatarError } from '@spatialwalk/avatarkit'
 
 try {
   await avatarView.avatarController.start()
 } catch (error) {
-  if (error instanceof SPAvatarError) {
+  if (error instanceof AvatarError) {
     console.error('SDK Error:', error.message, error.code)
   } else {
     console.error('Unknown error:', error)

package/dist/{StreamingAudioPlayer-BWsAt_s7.js → StreamingAudioPlayer-CugAsNXV.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, l as logger, e as errorToMessage, a as logEvent } from "./index-Bhjn1nq3.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-D0sXXlqd.js";
 class StreamingAudioPlayer {
   constructor(options) {
     __publicField(this, "audioContext", null);