@spatialwalk/avatarkit 1.0.0-beta.2 → 1.0.0-beta.4

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+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.4] - 2025-11-14
+
+### 🔄 Updates
+- Updated WASM module (avatar_core_wasm.wasm)
+
+---
+
+## [1.0.0-beta.3] - 2025-11-13
+
+### 🎉 Major Changes
+
+#### Architecture Refactoring - Three-Layer Architecture
+- **Rendering Layer (AvatarView)**: Pure rendering responsibility, receives rendering instructions from the playback layer
+- **Playback Layer (AvatarController)**: Unified data controller responsible for audio playback and animation rendering synchronization
+- **Network Layer (NetworkLayer)**: Optional network communication layer, automatically composed only in network mode
+
+#### Dual Playback Mode Support
+- **Network Mode**: 
+  - Send audio data to server via WebSocket
+  - Automatically receive and play animation data returned from server
+  - Use `controller.start()` and `controller.send()` methods
+  
+- **External Data Mode**:
+  - External components fully control audio and animation data acquisition
+  - SDK only responsible for synchronized playback of externally provided data
+  - Use `controller.play()`, `controller.sendAudioChunk()` and `controller.sendKeyframes()` methods
+
+### ✨ New Features
+
+- **Transition Animation Optimization**: 
+  - Transition animation duration adjusted to 200ms
+  - Improved audio-animation synchronization logic, ensuring audio and animation start playing together after transition animation ends
+  - Optimized transition frame generation and alignment logic
+
+- **Camera Configuration Enhancement**:
+  - Default transparent background, background rendering functionality removed
+  - Camera configuration aligned with iOS (Reversed-Z projection, near=0.01, far=100)
+  - Support dynamic camera configuration loading from characterSettings and camera.json
+
+- **Audio Sample Rate Configuration**:
+  - Updated default audio sample rate to 16kHz (previously 24kHz) to match backend requirements
+  - Audio format requirement: 16kHz mono PCM16
+
+- **Telemetry Migration**:
+  - Migrated from PostHog to Tencent Cloud CLS (Cloud Log Service)
+  - Support environment-based dynamic configuration (cn/test/us)
+  - Support both Token and SecretId/SecretKey authentication methods
+  - Aligned with iOS SDK configuration
+
+### 🔧 API Changes
+
+#### Breaking Changes
+
+- **AvatarView Constructor**:
+  ```typescript
+  // Old API
+  new AvatarView(avatar, container)
+  
+  // New API
+  new AvatarView(avatar, {
+    container: container,
+    playbackMode: AvatarPlaybackMode.network // or AvatarPlaybackMode.external
+  })
+  ```
+
+- **AvatarController Methods**:
+  - Network Mode: `start()` / `close()` / `send()`
+  - External Data Mode: `play()` / `sendAudioChunk()` / `sendKeyframes()`
+  - Common Methods: `interrupt()` / `clear()` / `dispose()`
+
+- **Removed Properties**:
+  - `realtimeStartTime` property removed (no longer needed)
+
+### 🐛 Bug Fixes
+
+- Fixed audio-animation desynchronization during transition animation
+- Fixed animation freezing issue in external data mode
+- Fixed audio playback speed abnormality caused by sample rate mismatch
+- Fixed camera configuration priority logic
+- Fixed WebSocket connection state callback timing issues
+
+### 📚 Documentation
+
+- Updated README.md with detailed explanation of three-layer architecture and two playback modes
+- Added audio format requirements documentation (16kHz mono PCM16)
+- Updated API reference documentation and code examples
+- Added architecture diagrams and flowcharts
+
+### 🧪 Testing
+
+- Updated unit tests to cover new architecture
+- Added unit tests for external data mode
+- Updated E2E tests to use new API
+- All tests passing (69 unit tests + 24 E2E tests)
+
+### 🔄 Internal Changes
+
+- Refactored `AvatarController` into unified playback layer
+- Extracted `NetworkLayer` as independent component
+- Optimized animation playback loop and audio-animation synchronization logic
+- Updated WASM module (avatar_core_wasm.wasm)
+- Improved error handling and logging
+
+### 📦 Dependencies
+
+- No new dependencies added
+- Maintained existing dependency versions
+
+---
+
+## [1.0.0-beta.2] - Previous Version
+
+(Previous version changelog entries...)