@spatius/avatarkit 1.0.0 → 1.1.0-beta.1

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.1.0-beta.1] - 2026-06-08
+
+First 1.1 pre-release. Includes breaking changes — see below.
+
+### Added
+- Render quality tiers (`standard` / `high` / `ultra`), selectable at init via the `renderQuality` configuration option or at runtime via `setRenderQuality()`.
+- Render output resolution cap, to bound rendering cost on high-DPI displays.
+- `Configuration.region` is now part of the public API, so consumers can target non-default regions (e.g. `cn`).
+
+### Changed
+- Unified audio playback path with automatic recovery after a fallback.
+- Smoother RTC-mode speak→idle transition with bezier end interpolation.
+
+### Fixed
+- Fixed unfriendly avatar-load error messages that could expose internal request details.
+- Fixed `Configuration.region` being stripped from the published type declarations, which prevented TypeScript consumers from setting the region.
+
+### Breaking Changes
+- `DrivingServiceMode` values renamed from `sdk` / `host` to `direct` / `backend`.
+- Removed the `eyefocus` option (no longer supported in `CharacterSettings` or post-processing configuration).
+
 ## [1.0.0] - 2026-05-17
 
 First stable release.

package/README.md

@@ -55,7 +55,7 @@ We provide complete example code and best practices to help you quickly integrat
 
 **The demo repository includes:**
 - ✅ Complete integration examples
-- ✅ Usage examples for both SDK mode and Host mode  
+- ✅ Usage examples for both Direct mode and Backend mode  
 - ✅ Audio processing examples (PCM16, WAV, MP3, etc.)
 - ✅ Vite configuration examples
 - ✅ Next.js configuration examples
@@ -224,9 +224,9 @@ import {
 // 1. Initialize SDK
 
 const configuration: Configuration = {
-  drivingServiceMode: DrivingServiceMode.sdk, // Optional, 'sdk' is default
-  // - DrivingServiceMode.sdk: SDK mode - SDK handles network communication
-  // - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
+  drivingServiceMode: DrivingServiceMode.direct, // Optional, `direct` is default
+  // - DrivingServiceMode.direct: Direct mode - SDK handles network communication
+  // - DrivingServiceMode.backend: Backend mode - Host app provides audio and animation data
   logLevel: LogLevel.off, // Optional, 'off' is default
   // - LogLevel.off: Disable all logs
   // - LogLevel.error: Only error logs
@@ -254,8 +254,8 @@ const avatar = await avatarManager.load('character-id', (progress) => {
 
 // 3. Create view (automatically creates Canvas and AvatarController)
 // The playback mode is determined by drivingServiceMode in AvatarSDK configuration
-// - DrivingServiceMode.sdk: SDK mode - SDK handles network communication
-// - DrivingServiceMode.host: Host mode - Host app provides audio and animation data
+// - DrivingServiceMode.direct: Direct mode - SDK handles network communication
+// - DrivingServiceMode.backend: Backend mode - Host app provides audio and animation data
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
@@ -266,7 +266,7 @@ 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)
+  // 5. Start real-time communication (Direct mode only)
   // Note: start() initiates the WebSocket connection asynchronously.
   // Wait for onConnectionState === 'connected' before calling send().
   await avatarView.controller.start()
@@ -278,7 +278,7 @@ button.addEventListener('click', async () => {
     }
   })
 
-  // 7. Send audio data (SDK mode, must be mono PCM16 format matching configured sample rate)
+  // 7. Send audio data (Direct mode, must be mono PCM16 format matching configured sample rate)
   // audioData: ArrayBuffer or Uint8Array containing PCM16 (S16LE) audio samples
   // ⚠️ Byte length MUST be even (2 bytes per sample). Odd-length data will cause server-side
   //    validation error and WebSocket disconnect.
@@ -295,9 +295,9 @@ button.addEventListener('click', async () => {
 
 ```typescript
 
-// 1-3. Same as SDK mode (initialize SDK, load avatar)
+// 1-3. Same as Direct mode (initialize SDK, load avatar)
 
-// 3. Create view with Host mode
+// 3. Create view with Backend mode
 const container = document.getElementById('avatar-container')
 const avatarView = new AvatarView(avatar, container)
 
@@ -317,8 +317,8 @@ button.addEventListener('click', async () => {
 ### Complete Examples
 
 This SDK supports two usage modes:
-- SDK mode: Real-time audio input with automatic animation data reception
-- Host mode: Custom data sources with manual audio/animation data management
+- Direct mode: Real-time audio input with automatic animation data reception
+- Backend mode: Custom data sources with manual audio/animation data management
 
 ## 🏗️ Architecture Overview
 
@@ -334,14 +334,14 @@ This SDK supports two usage modes:
 The SDK supports two playback modes, configured in `AvatarSDK.initialize()`:
 
 #### 1. SDK Mode (Default)
-- Configured via `drivingServiceMode: DrivingServiceMode.sdk` in `AvatarSDK.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.direct` in `AvatarSDK.initialize()`
 - SDK handles network communication automatically
 - Send audio data via `AvatarController.send()`
 - SDK receives animation data from backend and synchronizes playback
 - Best for: Real-time audio input scenarios
 
 #### 2. Host Mode
-- Configured via `drivingServiceMode: DrivingServiceMode.host` in `AvatarSDK.initialize()`
+- Configured via `drivingServiceMode: DrivingServiceMode.backend` in `AvatarSDK.initialize()`
 - Host application manages its own network/data fetching
 - Host application provides both audio and animation data
 - SDK only handles synchronized playback
@@ -618,13 +618,13 @@ const newAvatar = await AvatarManager.shared.load('new-character-id')
 // 3. Create new AvatarView
 currentAvatarView = new AvatarView(newAvatar, container)
 
-// 4. Start connection if SDK mode
+// 4. Start connection if Direct mode
 await currentAvatarView.controller.start()
 ```
 
 ### AvatarController
 
-Audio/animation playback controller, manages synchronized playback of audio and animation. Automatically handles network communication in SDK mode.
+Audio/animation playback controller, manages synchronized playback of audio and animation. Automatically handles network communication in Direct mode.
 
 **Two Usage Patterns:**
 
@@ -708,7 +708,7 @@ 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.controller.onConnectionState = (state: ConnectionState) => {} // SDK mode only
+avatarView.controller.onConnectionState = (state: ConnectionState) => {} // Direct mode only
 avatarView.controller.onConversationState = (state: ConversationState) => {}
 avatarView.controller.onError = (error: AvatarError) => {} // Includes error.code for specific error type
 ```
@@ -731,8 +731,8 @@ avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 } // Right half, double
 ```
 
 **Important Notes:**
-- `start()` and `close()` are only available in SDK mode
-- `yieldAudioData()` and `yieldFramesData()` are only available in Host mode
+- `start()` and `close()` are only available in Direct mode
+- `yieldAudioData()` and `yieldFramesData()` are only available in Backend mode
 - `pause()`, `resume()`, `interrupt()`, `setVolume()`, and `getVolume()` are available in both modes
 - The playback mode is determined when creating `AvatarView` and cannot be changed
 
@@ -742,7 +742,7 @@ avatarView.avatarTransform = { x: 0.5, y: 0, scale: 2.0 } // Right half, double
 
 ```typescript
 interface Configuration {
-  drivingServiceMode?: DrivingServiceMode  // Optional, default is 'sdk' (SDK mode)
+  drivingServiceMode?: DrivingServiceMode  // Optional, default is `direct` (Direct mode)
   logLevel?: LogLevel  // Optional, default is 'off' (no logs)
   audioFormat?: AudioFormat  // Optional, default is { channelCount: 1, sampleRate: 16000 }
 }
@@ -770,8 +770,8 @@ enum LogLevel {
 
 **Description:**
 - `drivingServiceMode`: Specifies the driving service mode
-  - `DrivingServiceMode.sdk` (default): SDK mode - SDK handles network communication automatically
-  - `DrivingServiceMode.host`: Host mode - Host application provides audio and animation data
+  - `DrivingServiceMode.direct` (default): Direct mode - SDK handles network communication automatically
+  - `DrivingServiceMode.backend`: Backend mode - Host application provides audio and animation data
 - `logLevel`: Controls the verbosity of SDK logs
   - `LogLevel.off` (default): Disable all logs
   - `LogLevel.error`: Only error logs
@@ -885,7 +885,7 @@ avatarView.controller.onError = (error: AvatarError) => {
 | `sessionTimeout` | Session timeout | WebSocket close code 4002 |
 | `connectionInProgress` | Connection already in progress | Duplicate `start()` call |
 | **Playback** | | |
-| `networkLayerNotAvailable` | Network layer not available | `send()` in host mode |
+| `networkLayerNotAvailable` | Network layer not available | `send()` in backend mode |
 | `playbackStartFailed` | Failed to start playback | Internal error |
 | `playbackInitFailed` | Playback initialization failed | Internal error |
 | `audioOnlyInitFailed` | Audio-only playback init failed | Fallback mode error |
@@ -931,12 +931,12 @@ avatarView.dispose()
 
 **⚠️ Important Notes:**
 - `dispose()` automatically cleans up all resources, including:
-  - Network connections (SDK mode)
+  - Network connections (Direct 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 connections before disposing, you can call `avatarView.controller.close()` (SDK mode) first, but it's not required as `dispose()` handles this automatically
+- If you need to manually close connections before disposing, you can call `avatarView.controller.close()` (Direct mode) first, but it's not required as `dispose()` handles this automatically
 
 ### Memory Optimization
 

package/dist/{StreamingAudioPlayer-Cq5jTVny.js → StreamingAudioPlayer-DrHXn-YA.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-zTpDp_Pv.js";
+import { A as APP_CONFIG, l as logger, e as errorToMessage, a as logEvent } from "./index-CVQn5uEB.js";
 class StreamingAudioPlayer {
   // Mark if AudioContext is being resumed, avoid concurrent resume requests
   constructor(options) {
@@ -87,8 +87,8 @@ class StreamingAudioPlayer {
       });
     } catch (error) {
       const message = errorToMessage(error);
-      logEvent("activeAudioSessionFailed", "warning", {
-        sessionId: this.sessionId,
+      logEvent("audio_session_init_failed", "warning", {
+        session_id: this.sessionId,
         reason: message
       });
       logger.error("Failed to initialize AudioContext:", message);
@@ -144,7 +144,7 @@ class StreamingAudioPlayer {
       } catch (err) {
         logger.errorWithError("[StreamingAudioPlayer] Failed to resume AudioContext:", err);
         logEvent("audio_context_resume_failed", "error", {
-          sessionId: this.sessionId,
+          session_id: this.sessionId,
           reason: err instanceof Error ? err.message : String(err)
         });
       } finally {
@@ -281,7 +281,7 @@ class StreamingAudioPlayer {
       const errorMessage = "Failed to create AudioBuffer from PCM data";
       logger.error(errorMessage);
       logEvent("audio_buffer_creation_failed", "error", {
-        sessionId: this.sessionId
+        session_id: this.sessionId
       });
       return;
     }
@@ -328,7 +328,7 @@ class StreamingAudioPlayer {
     } catch (err) {
       logger.errorWithError("Failed to schedule audio chunk:", err);
       logEvent("schedule_chunk_failed", "error", {
-        sessionId: this.sessionId,
+        session_id: this.sessionId,
         reason: err instanceof Error ? err.message : String(err)
       });
     }

package/dist/core/AvatarController.d.ts

@@ -22,9 +22,7 @@ export declare class AvatarController {
     set frameRateMonitorEnabled(value: boolean);
     private renderCallback?;
     private characterHandle;
-    private characterId;
     private postProcessingConfig;
-    private audioMonitorLoopId;
     private lastRenderedFrameIndex;
     private keyframesOffset;
     private readonly MAX_KEYFRAMES;

package/dist/core/AvatarSDK.d.ts

@@ -1,4 +1,4 @@
-import { Configuration } from '../types';
+import { Configuration, RenderQuality } from '../types';
 export declare class AvatarSDK {
     private static _initializationState;
     private static _initializingPromise;
@@ -7,6 +7,13 @@ export declare class AvatarSDK {
     private static _avatarCore;
     private static _cachedDeviceScore;
     private static _rendererBackend;
+    /** Render output resolution cap. Disabled by default; when enabled and the
+     *  canvas backing height (css × DPR) exceeds maxHeight, the canvas is sized
+     *  to maxHeight (aspect-preserving) and the browser scales it back up to
+     *  the CSS box. Training material is 1080p so heights above ~1080-1440
+     *  add no real visual information. */
+    static renderResolutionCapEnabled: boolean;
+    static renderResolutionMaxHeight: number;
     /**
      * Initialize SDK
      * @param appId Application ID to be included in both HTTP Headers and WebSocket Headers
@@ -27,6 +34,14 @@ export declare class AvatarSDK {
     static setUserId(userId: string): void;
     static get appId(): string | null;
     static get configuration(): Configuration | null;
+    /**
+     * Update the global render quality tier. Takes effect on the next rendered
+     * frame across all active AvatarView instances. Throws if SDK isn't initialized.
+     */
+    static setRenderQuality(quality: RenderQuality): void;
+    /** Toggle the render output resolution cap. Takes effect on the next layout
+     *  pass across all active AvatarView instances. */
+    static setRenderResolutionCap(enabled: boolean, maxHeight?: number): void;
     static get sessionToken(): string | null;
     static get userId(): string | null;
     static get version(): string;

package/dist/core/AvatarView.d.ts

@@ -16,7 +16,7 @@ export declare class AvatarView {
     private frameCount;
     private lastFpsUpdate;
     private currentFPS;
-    private currentPlayingFrame;
+    private currentFrame;
     private cachedIdleFirstFrame;
     private characterHandle;
     private characterId;
@@ -41,6 +41,20 @@ export declare class AvatarView {
      * Get controller (public interface)
      */
     get controller(): AvatarController;
+    /**
+     * Current native render surface size in pixels (canvas backing buffer
+     * size, post-DPR).
+     *
+     * Differs from the canvas CSS size (`offsetWidth / offsetHeight`): this
+     * reflects the actual pixel buffer the WebGPU renderer is targeting after
+     * the most recent resize has been applied.
+     *
+     * Returns `{ width: 0, height: 0 }` before the canvas has been initialized.
+     */
+    get renderSize(): {
+        width: number;
+        height: number;
+    };
     private _exportBitmapResolve;
     /**
      * Exports the current rendering as a Blob (PNG).
@@ -126,7 +140,17 @@ export declare class AvatarView {
      * @param options.useLinear - Use linear interpolation (default: true)
      * @returns Array of opaque keyframe data for sequential playback
      */
-    generateTransitionFromProtobuf(data: ArrayBuffer | Uint8Array, frameCount: number, options?: {
+    generateTransitionToFrame(data: ArrayBuffer | Uint8Array, frameCount: number, options?: {
+        useLinear?: boolean;
+    }): Promise<unknown[]>;
+    /**
+     * RTC mode: generate `frameCount` interpolated frames from the most recently
+     * rendered frame back to the idle loop start. Caller plays them at 25fps
+     * via `renderFrame`, then hands control back with
+     * `renderFrame(undefined, true)`. Used for speaking → idle and disconnect
+     * soft transitions.
+     */
+    generateTransitionToIdle(frameCount: number, options?: {
         useLinear?: boolean;
     }): Promise<unknown[]>;
     /**
@@ -134,6 +158,12 @@ export declare class AvatarView {
      * Called by renderFromProtobuf when streaming frames arrive during transition.
      */
     cancelFrameSequence(): void;
+    /** 计算 canvas backing-store 像素尺寸. 默认 css × dpr;
+     *  AvatarSDK.setRenderResolutionCap 启用且高度超过阈值时,
+     *  按比例缩到阈值, css 尺寸不变 (浏览器自动拉伸). */
+    private computeCappedBacking;
+    /** Registry hook: AvatarSDK.setRenderResolutionCap 调用时重算 backing size. */
+    applyResolutionCapFromSdk(): void;
     /**
      * Pause rendering loop
      *

package/dist/core/avatarViewRegistry.d.ts

@@ -0,0 +1,9 @@
+import { AvatarView } from './AvatarView';
+declare class AvatarViewRegistry {
+    private entries;
+    register(view: AvatarView): void;
+    unregister(view: AvatarView): void;
+    applyResolutionCapToAll(): void;
+}
+export declare const avatarViewRegistry: AvatarViewRegistry;
+export {};