@spatialwalk/avatarkit/CHANGELOG.md

SPAvatar SDK - 3D Gaussian Splatting Avatar Rendering SDK

# 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.9] - 2025-11-15

### 🐛 Bug Fixes
- Fixed memory leaks when disposing AvatarView instances
  - Improved resource cleanup to prevent memory leaks when switching or disposing avatar instances
  - Properly clears all callbacks, event listeners, and large data buffers on disposal

---

## [1.0.0-beta.8] - 2025-11-14

### 🐛 Bug Fixes
- Fixed audio-animation synchronization issue after normal playback completion
  - Playback state is now properly cleaned up when audio finishes normally, preventing synchronization issues in subsequent conversations

---

## [1.0.0-beta.7] - 2025-11-14

### 🔄 Refactoring
- Improved rendering state management for better stability and maintainability

### 🐛 Bug Fixes
- Fixed interrupt not generating transition animation when interrupting during playback
- Fixed transition animation being regenerated and reset in external data mode when sending keyframes after playback starts

---

## [1.0.0-beta.6] - 2025-11-14

### 🐛 Bug Fixes
- Fixed transition animation being regenerated and reset in external data mode when sending keyframes after playback starts, causing the transition to play twice

---

## [1.0.0-beta.5] - 2025-11-14

### 🐛 Bug Fixes
- Fixed missing `AvatarPlaybackMode` enum export in published package

---

## [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...)