@spatialwalk/avatarkit 1.0.0-beta.71 → 1.0.0-beta.72

package/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.72] - 2026-01-17
+
+### 📚 Documentation
+- **README Optimization** - Enhanced README with authentication section and improved API documentation
+
 ## [1.0.0-beta.71] - 2026-01-17
 
 ### 🔧 Improvements

package/README.md

@@ -18,13 +18,34 @@ Real-time virtual avatar rendering SDK based on 3D Gaussian Splatting, supportin
 npm install @spatialwalk/avatarkit
 ```
 
-## 🔧 Vite 配置（推荐）
+## 🚀 Demo Repository
 
-如果你使用 Vite 作为构建工具，强烈推荐使用我们的 Vite 插件来自动处理 WASM 文件配置。插件会自动处理所有必要的配置，让你无需手动设置。
+<div align="center">
 
-### 使用插件
+### 📌 **Quick Start: Check Out Our Demo Repository**
 
-在 `vite.config.ts` 中添加插件：
+We provide complete example code and best practices to help you quickly integrate the SDK.
+
+**The demo repository includes:**
+- ✅ Complete integration examples
+- ✅ Usage examples for both SDK mode and Host mode  
+- ✅ Audio processing examples (PCM16, WAV, MP3, etc.)
+- ✅ Vite configuration examples
+- ✅ Best practices for common scenarios
+
+**[👉 View Demo Repository](https://github.com/spatialwalk/avatarkit-demo)** | *If not yet created, please contact the team*
+
+</div>
+
+---
+
+## 🔧 Vite Configuration (Recommended)
+
+If you are using Vite as your build tool, we strongly recommend using our Vite plugin to automatically handle WASM file configuration. The plugin automatically handles all necessary configurations, so you don't need to set them up manually.
+
+### Using the Plugin
+
+Add the plugin to `vite.config.ts`:
 
 ```typescript
 import { defineConfig } from 'vite'
@@ -32,27 +53,27 @@ import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
 
 export default defineConfig({
   plugins: [
-    avatarkitVitePlugin(), // 添加这一行即可
+    avatarkitVitePlugin(), // Just add this line
   ],
 })
 ```
 
-### 插件功能
+### Plugin Features
 
-插件会自动处理：
+The plugin automatically handles:
 
-- ✅ **开发服务器**：自动设置 WASM 文件的正确 MIME 类型 (`application/wasm`)
-- ✅ **构建时**：自动复制 WASM 文件到 `dist/assets/` 目录
-  - 智能检测：从 JS glue 文件中提取引用的 WASM 文件名（包括 hash）
-  - 自动匹配：确保复制的 WASM 文件与 JS glue 文件中的引用匹配
-  - 支持 hash：正确处理带 hash 的 WASM 文件（如 `avatar_core_wasm-{hash}.wasm`）
-- ✅ **WASM JS Glue**：自动复制 WASM JS glue 文件到 `dist/assets/` 目录
-- ✅ **Cloudflare Pages**：自动生成 `_headers` 文件，确保 WASM 文件使用正确的 MIME 类型
-- ✅ **Vite 配置**：自动配置 `optimizeDeps`、`assetsInclude`、`assetsInlineLimit` 等选项
+- ✅ **Development Server**: Automatically sets the correct MIME type (`application/wasm`) for WASM files
+- ✅ **Build Time**: Automatically copies WASM files to `dist/assets/` directory
+  - Smart Detection: Extracts referenced WASM file names (including hash) from JS glue files
+  - Auto Matching: Ensures copied WASM files match references in JS glue files
+  - Hash Support: Correctly handles hashed WASM files (e.g., `avatar_core_wasm-{hash}.wasm`)
+- ✅ **WASM JS Glue**: Automatically copies WASM JS glue files to `dist/assets/` directory
+- ✅ **Cloudflare Pages**: Automatically generates `_headers` file to ensure WASM files use the correct MIME type
+- ✅ **Vite Configuration**: Automatically configures `optimizeDeps`, `assetsInclude`, `assetsInlineLimit`, and other options
 
-### 手动配置（不使用插件）
+### Manual Configuration (Without Plugin)
 
-如果你不使用 Vite 插件，需要手动配置以下内容：
+If you don't use the Vite plugin, you need to manually configure the following:
 
 ```typescript
 // vite.config.ts
@@ -74,7 +95,7 @@ export default defineConfig({
       },
     },
   },
-  // 开发服务器需要手动配置中间件设置 WASM MIME 类型
+  // Development server needs to manually configure middleware to set WASM MIME type
   configureServer(server) {
     server.middlewares.use((req, res, next) => {
       if (req.url?.endsWith('.wasm')) {
@@ -86,6 +107,53 @@ export default defineConfig({
 })
 ```
 
+## 🔐 Authentication
+
+All environments require an **App ID** and **Session Token** for authentication.
+
+### App ID
+
+The App ID is used to identify your application. You can obtain your App ID by:
+
+1. **For Testing**: Use the default test App ID provided in demo repositories (paired with test Session Token, only works with publicly available test avatars like Rohan, Dr.Kellan, Priya, Josh, etc.)
+2. **For Production**: Visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and avatars. You will receive your own App ID after creating an App.
+
+### Session Token
+
+The Session Token is required for WebSocket authentication and must be obtained from your SDK provider.
+
+**⚠️ Important Notes:**
+- The Session Token must be valid and not expired
+- In production applications, you **must** manually inject a valid Session Token obtained from your SDK provider
+- The default Session Token provided in demo repositories is **only for demonstration purposes** and can only be used with test avatars
+- If you want to create your own avatars and test them, please visit the [Developer Platform](https://dash.spatialreal.ai) to create your own App and generate Session Tokens
+
+**How to Set Session Token:**
+
+```typescript
+// Initialize SDK with App ID
+await AvatarSDK.initialize('your-app-id', configuration)
+
+// Set Session Token (can be called before or after initialization)
+// If called before initialization, the token will be automatically set when you initialize the SDK
+AvatarSDK.setSessionToken('your-session-token')
+
+// Get current Session Token
+const sessionToken = AvatarSDK.sessionToken
+```
+
+**Token Management:**
+- The Session Token can be set at any time using `AvatarSDK.setSessionToken(token)`
+- If you set the token before initializing the SDK, it will be automatically applied during initialization
+- If you set the token after initialization, it will be applied immediately
+- Handle token refresh logic in your application as needed (e.g., when token expires)
+
+**For Production Integration:**
+- Obtain a valid Session Token from your SDK provider
+- Store the token securely (never expose it in client-side code if possible)
+- Implement token refresh logic to handle token expiration
+- Use `AvatarSDK.setSessionToken(token)` to inject the token programmatically
+
 ## 🎯 Quick Start
 
 ### ⚠️ Important: Audio Context Initialization
@@ -126,8 +194,10 @@ const configuration: Configuration = {
 
 await AvatarSDK.initialize('your-app-id', configuration)
 
-// Set sessionToken (if needed, call separately)
-// AvatarSDK.setSessionToken('your-session-token')
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section above for more details
+AvatarSDK.setSessionToken('your-session-token')
 
 // 2. Load avatar
 const avatarManager = AvatarManager.shared
@@ -408,7 +478,9 @@ const appId = AvatarSDK.appId
 // Get configuration
 const config = AvatarSDK.configuration
 
-// Set sessionToken (if needed, call separately)
+// Set Session Token (required for authentication)
+// You must obtain a valid Session Token from your SDK provider
+// See Authentication section for more details
 AvatarSDK.setSessionToken('your-session-token')
 
 // Set userId (optional, for telemetry)
@@ -437,7 +509,7 @@ const manager = AvatarManager.shared
 
 // Load avatar
 const avatar = await manager.load(
-  characterId: string, 
+  id: string, 
   onProgress?: (progress: LoadProgressInfo) => void
 )
 
@@ -505,7 +577,7 @@ const newAvatar = await avatarManager.load('new-character-id')
 currentAvatarView = new AvatarView(newAvatar, container)
 
 // SDK mode: start connection (will throw error if not in SDK mode)
-  await currentAvatarView.controller.start()
+await currentAvatarView.controller.start()
 ```
 
 ### AvatarController
@@ -581,24 +653,30 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
+// Pause playback (from playing state)
+avatarView.controller.pause()
+
+// Resume playback (from paused state)
+await avatarView.controller.resume()
+
 // Interrupt current playback (stops and clears data)
-avatarView.avatarController.interrupt()
+avatarView.controller.interrupt()
 
 // Clear all data and resources
-avatarView.avatarController.clear()
+avatarView.controller.clear()
 
 // Get current conversation ID (for Host mode)
-const conversationId = avatarView.avatarController.getCurrentConversationId()
+const conversationId = avatarView.controller.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)
+avatarView.controller.setVolume(0.5)  // Set volume to 50% (0.0 to 1.0)
+const currentVolume = avatarView.controller.getVolume()  // Get current volume (0.0 to 1.0)
 
 // Set event callbacks
-avatarView.avatarController.onConnectionState = (state: ConnectionState) => {} // SDK mode only
-avatarView.avatarController.onConversationState = (state: ConversationState) => {}
-avatarView.avatarController.onError = (error: Error) => {}
+avatarView.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
+avatarView.controller.onConversationState = (state: ConversationState) => {}
+avatarView.controller.onError = (error: Error) => {}
 ```
 
 #### Avatar Transform Methods
@@ -674,7 +752,7 @@ enum LogLevel {
     - Supported values: 8000, 16000, 22050, 24000, 32000, 44100, 48000
     - The configured sample rate will be used for both audio recording and playback
 - `characterApiBaseUrl`: Internal debug config, can be ignored
-- `sessionToken`: Set separately via `AvatarSDK.setSessionToken()`, not in Configuration
+- `sessionToken`: **Required for authentication**. Set separately via `AvatarSDK.setSessionToken()`, not in Configuration. See [Authentication](#-authentication) section for details
 
 ```typescript
 enum Environment {
@@ -734,7 +812,7 @@ enum ConversationState {
 The SDK supports two rendering backends:
 
 - **WebGPU** - High-performance rendering for modern browsers
-- **WebGL** - Better compatibility traditional rendering
+- **WebGL** - Better compatibility for traditional rendering
 
 The rendering system automatically selects the best backend, no manual configuration needed.
 
@@ -748,7 +826,7 @@ The SDK uses custom error types, providing more detailed error information:
 import { AvatarError } from '@spatialwalk/avatarkit'
 
 try {
-  await avatarView.avatarController.start()
+  await avatarView.controller.start()
 } catch (error) {
   if (error instanceof AvatarError) {
     console.error('SDK Error:', error.message, error.code)
@@ -761,7 +839,7 @@ try {
 ### Error Callbacks
 
 ```typescript
-avatarView.avatarController.onError = (error: Error) => {
+avatarView.controller.onError = (error: Error) => {
   console.error('AvatarController error:', error)
   // Handle error, such as reconnection, user notification, etc.
 }
@@ -777,14 +855,13 @@ avatarView.avatarController.onError = (error: Error) => {
 // Initialize
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
-await avatarView.avatarController.start()
+await avatarView.controller.start()
 
 // Use
-avatarView.avatarController.send(audioData, false)
+avatarView.controller.send(audioData, false)
 
-// Cleanup
-avatarView.avatarController.close()
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including WebSocket connections
+avatarView.dispose()
 ```
 
 #### Host Mode Lifecycle
@@ -795,19 +872,21 @@ const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
 // Use
-const conversationId = avatarView.avatarController.yieldAudioData(audioChunk, false)
-avatarView.avatarController.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
+const conversationId = avatarView.controller.yieldAudioData(audioChunk, false)
+avatarView.controller.yieldFramesData(keyframesDataArray, conversationId) // keyframesDataArray: (Uint8Array | ArrayBuffer)[]
 
-// Cleanup
-avatarView.avatarController.clear() // Clear all data and resources
-avatarView.dispose() // Automatically cleans up all resources
+// Cleanup - dispose() automatically cleans up all resources including playback data
+avatarView.dispose()
 ```
 
 **⚠️ Important Notes:** 
-- When disposing AvatarView instances, must call `dispose()` to properly clean up resources
-- Not properly cleaning up may cause resource leaks and rendering errors
-- In SDK mode, call `close()` before `dispose()` to properly close WebSocket connections
-- In Host mode, call `clear()` before `dispose()` to clear all playback data
+- `dispose()` automatically cleans up all resources, including:
+  - WebSocket connections (SDK mode)
+  - Playback data and animation resources (both modes)
+  - Render system and canvas elements
+  - All event listeners and callbacks
+- Not properly calling `dispose()` may cause resource leaks and rendering errors
+- If you need to manually close WebSocket connections or clear playback data before disposing, you can call `avatarView.controller.close()` (SDK mode) or `avatarView.controller.clear()` (both modes) first, but it's not required as `dispose()` handles this automatically
 
 ### Memory Optimization
 

package/dist/{StreamingAudioPlayer-D8Q8WiEg.js → StreamingAudioPlayer-fV-zTOrl.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-U8QcNdma.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-BginsqFH.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {

package/dist/{index-U8QcNdma.js → index-BginsqFH.js}

@@ -7860,7 +7860,7 @@ const _AnimationPlayer = class _AnimationPlayer {
     if (this.streamingPlayer) {
       return;
     }
-    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-D8Q8WiEg.js");
+    const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-fV-zTOrl.js");
     const { AvatarSDK: AvatarSDK2 } = await Promise.resolve().then(() => AvatarSDK$1);
     const audioFormat = AvatarSDK2.getAudioFormat();
     this.streamingPlayer = new StreamingAudioPlayer({
@@ -9531,7 +9531,7 @@ class AvatarSDK {
 }
 __publicField(AvatarSDK, "_isInitialized", false);
 __publicField(AvatarSDK, "_configuration", null);
-__publicField(AvatarSDK, "_version", "1.0.0-beta.71");
+__publicField(AvatarSDK, "_version", "1.0.0-beta.72");
 __publicField(AvatarSDK, "_avatarCore", null);
 __publicField(AvatarSDK, "_dynamicSdkConfig", null);
 const AvatarSDK$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({

package/dist/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.71",
+  "version": "1.0.0-beta.72",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
   "author": "AvatarKit Team",