# 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.16] - 2025-11-21

### ✨ New Features
- **Multi-AvatarView Support** - SDK now supports multiple `AvatarView` instances simultaneously
  - Each `AvatarView` instance can manage its own character independently
  - Multiple characters can be displayed and controlled at the same time
  - Each instance maintains its own rendering context, playback state, and network connection
  - Removed the previous limitation of "only one AvatarView instance at a time"

### 📚 Documentation
- Updated README.md to reflect multi-character support capabilities
- Added multi-character usage examples
- Removed outdated limitation notes about single AvatarView instance

---

## [1.0.0-beta.15] - 2025-01-20

### ✨ New Features
- Added authentication support for API requests
  - `appId` is now automatically included in HTTP headers (`X-App-Id`) and WebSocket URL query parameters
  - `sessionToken` is now automatically included in HTTP headers (`Authorization: Bearer {token}`) and WebSocket URL query parameters
  - All network requests (character loading, resource downloads, WebSocket connections) now include authentication credentials

### 🔧 Improvements
- Fixed canvas resize handling for different aspect ratios
  - Projection matrix is now correctly updated when canvas aspect ratio changes
  - Rendering system properly handles portrait (9:16) and landscape (16:9) aspect ratios
  - Canvas automatically adapts to container size changes via ResizeObserver

### 🐛 Bug Fixes
- Fixed `RenderSystem.handleResize()` to update projection matrix when canvas size changes
  - Previously only updated aspect ratio, now also updates projection matrix for correct rendering

---

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

### ✨ New Features
- Added pause and resume functionality for avatar playback
  - New `pause()` method to pause audio and animation playback
  - New `resume()` method to resume playback from paused state
  - Added `paused` state to `AvatarState` enum
  - State changes are communicated via `onAvatarState` callback
  - Works in both network mode and external data mode

### 🔧 Improvements
- Canvas now uses container's full dimensions instead of fixed 1:1 aspect ratio
  - Canvas automatically adapts to container size (width and height)
  - External developers can control canvas aspect ratio by setting container dimensions
  - Rendering system correctly handles any aspect ratio without distortion

---

## [1.0.0-beta.13] - 2025-11-17

### 🔒 API Improvements
- Reduced console noise by setting default log level to Warning
  - Logger now only outputs warnings and errors by default
  - Set `VITE_DEBUG_LOG=true` to enable all logs
  - Simplified logger configuration using `setGlobalLogLevel(LogLevel.Warning)`

### 🐛 Bug Fixes
- Fixed SDK config loader warning in non-debug mode
  - Config loading failures are now silently handled in production
  - Warnings only shown when `VITE_DEBUG_LOG=true`

---

## [1.0.0-beta.12] - 2025-11-17

### 🔒 API Improvements
- Marked performance monitoring APIs as internal
  - `RenderPerformanceStats` interface and `getPerformanceStats()` method are now marked with `@internal` tag
  - These APIs are not exposed in the public TypeScript definitions
  - Reverted performance monitoring implementation to simpler version (only `renderTime` and `sortTime`)

---

## [1.0.0-beta.11] - 2025-11-17

### 📚 Documentation
- Updated demo repository link in README.md
  - Changed example project link from `Avatarkit-web-demo` to `AvatarKit-Web-Demo` to match the new repository name

---

## [1.0.0-beta.10] - 2025-11-16

### 🔒 API Improvements
- Cleaned up public API to hide internal implementation details
  - Marked internal methods with `@internal` JSDoc tag to exclude them from TypeScript declarations
  - Removed unused environment configuration options (`realtimeApiBaseUrl`, `realtimeWsUrl`)
  - Added `appId` getter to `AvatarKit` for accessing initialized app ID
  - Internal methods like `getEnvironmentConfig`, `logEvent`, `getCanvas`, `getCameraConfig`, `updateCameraConfig` are now properly hidden from public API

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