API Reference

/// SDK entry class
export class AvatarKit {
  /// Initialize SDK
  /// @param appId - Application ID
  /// @param configuration - SDK configuration
  static async initialize(
    appId: string,
    configuration: Configuration
  ): Promise<void>
  
  /// Check initialization status
  static readonly isInitialized: boolean
  
  /// Get the App ID provided during initialization
  static readonly appId: string | null
  
  /// Get the configuration object provided during initialization
  static readonly configuration: Configuration | null
  
  /// Set session token for WebSocket authentication
  /// @param token - Session token
  /// Note: sessionToken is not in the Configuration interface, it must be set separately using this method
  static setSessionToken(token: string): void
  
  /// Get the currently set session token
  static readonly sessionToken: string | null
  
  /// Set user ID for logging and analytics
  /// @param userId - User ID
  static setUserId(userId: string): void
  
  /// Get the currently set user ID
  static readonly userId: string | null
  
  /// Get SDK version
  static readonly version: string
  
  /// Clean up SDK global resources
  /// If you no longer need the digital human SDK, you must call this to release all occupied resources, including WASM modules, memory, etc.
  /// Note: Only call this when the entire application no longer needs digital human functionality.
  static cleanup(): void
}

export class AvatarManager {
  /// Get singleton instance
  static readonly shared: AvatarManager
  
  /// Load character resources
  /// @param characterId - Character ID
  /// @param onProgress - Progress callback (optional)
  /// @returns Promise<Avatar> - Successfully loaded character object
  async load(
    characterId: string,
    onProgress?: (progress: LoadProgressInfo) => void
  ): Promise<Avatar>
  
  /// Clear cache
  clearCache(): void
}

export class AvatarView {
  /// Create view instance
  /// @param avatar - Loaded character object
  /// @param container - Container element (required)
  ///   - Canvas automatically uses the full size of the container (width and height)
  ///   - Canvas aspect ratio adapts to container size - set container size to control aspect ratio
  ///   - Canvas is automatically added to the container
  constructor(avatar: Avatar, container: HTMLElement)
  
  /// Real-time communication controller
  readonly avatarController: AvatarController
  
  /// Wait for first frame to render
  readonly ready: Promise<void>
  
  /// Get rendering Canvas element
  getCanvas(): HTMLCanvasElement
  
  /// Set background image
  /// @param imageUrl - Image URL
  setBackgroundImage(imageUrl: string): void
  
  /// Update camera configuration
  /// @param config - Camera configuration object
  updateCameraConfig(config: CameraConfig): void
  
  /// Clean up view resources
  dispose(): void
}

export class AvatarController {
  /// Start WebSocket connection
  async start(): Promise<void>
  
  /// Send audio data
  /// @param audioData - Audio data (ArrayBuffer format, must be 16kHz mono PCM16)
  ///   - Sample rate: 16kHz (16000 Hz) - backend requirement
  ///   - Format: PCM16 (16-bit signed integer, little-endian)
  ///   - Channels: Mono (single channel)
  ///   - Example: 1 second = 16000 samples × 2 bytes = 32000 bytes
  /// @param end - Whether to end sending
  ///   - `false` (default) - Continue sending audio data for current conversation
  ///   - `true` - Mark the end of current conversation round. After end=true, sending new audio data will interrupt any ongoing playback from the previous conversation round
  /// @returns conversationId - Conversation ID (mainly used internally in SDK mode, not required for basic usage)
  /// Important Notes:
  /// - SDK will start returning animation data and playing once it collects enough audio data, no need to wait for `end=true`
  /// - After `end=true`, sending new audio data will interrupt any ongoing playback from the previous conversation round
  send(audioData: ArrayBuffer, end?: boolean): string
  
  /// Stream audio chunks (Host mode only)
  /// @param data - Audio chunk data (Uint8Array format, 16kHz mono PCM16)
  /// @param isLast - Whether this is the last chunk (default: false)
  /// @returns conversationId - Conversation ID for this audio session
  /// Important Notes:
  /// - Can be called directly to start a new session
  /// - If no conversationId exists, a new one will be automatically generated
  /// - Returns the conversationId that must be used when sending animation data via yieldFramesData()
  yieldAudioData(data: Uint8Array, isLast?: boolean): string
  
  /// Stream animation keyframes (Host mode only)
  /// @param keyframes - Animation keyframes (obtained from your service)
  /// @param conversationId - Conversation ID (required)
  ///   - Use getCurrentConversationId() or yieldAudioData() to get conversationId
  ///   - Animation data with mismatched conversationId will be discarded
  /// Important Notes:
  /// - Requires a valid conversationId from audio data
  /// - Animation data with mismatched conversationId will be discarded
  /// - Must send audio data first to get conversationId before calling this method
  yieldFramesData(keyframes: any[], conversationId: string): void
  
  /// Interrupt current playback (stops and clears data)
  interrupt(): void
  
  /// Clear all data and resources
  clear(): void
  
  /// Close connection (SDK mode only)
  close(): void
  
  /// Get current conversation ID (for Host mode)
  /// Returns: Current conversationId for the active audio session, or null if no active session
  getCurrentConversationId(): string | null
  
  /// Volume control (affects only avatar audio player, not system volume)
  /// @param volume - Volume level from 0.0 to 1.0
  setVolume(volume: number): void
  
  /// Get current volume level
  /// @returns Current volume level from 0.0 to 1.0
  getVolume(): number
  
  /// Connection state callback (SDK mode only)
  onConnectionState?: (state: ConnectionState) => void
  
  /// Conversation state callback
  onConversationState?: (state: ConversationState) => void
  
  /// Error callback
  onError?: (error: Error) => void
}

interface Configuration {
  /// Environment configuration
  environment: Environment
  /// Driving service mode (optional, default is 'sdk')
  drivingServiceMode?: DrivingServiceMode
}

enum DrivingServiceMode {
  sdk = 'sdk'   // SDK mode: SDK handles WebSocket communication automatically
}

enum Environment {
  /// China region
  cn = 'cn'
  /// International region
  intl = 'intl'
  /// Test environment
  test = 'test'
}

interface CameraConfig {
  /// Camera position
  position: [number, number, number]
  /// Camera target point
  target: [number, number, number]
  /// Field of view angle (degrees)
  fov: number
  /// Near clipping plane
  near: number
  /// Far clipping plane
  far: number
  /// Up direction vector (optional)
  up?: [number, number, number]
  /// Aspect ratio (optional)
  aspect?: number
}

enum ConnectionState {
  /// Not connected
  disconnected = 'disconnected'
  /// Connecting
  connecting = 'connecting'
  /// Connected
  connected = 'connected'
  /// Connection failed
  failed = 'failed'
}

enum ConversationState {
  /// Idle state, showing breathing animation
  idle = 'idle'
  /// Playing conversation content (including transition animation period)
  playing = 'playing'
}

enum LoadProgress {
  /// Downloading
  downloading = 'downloading'
  /// Completed
  completed = 'completed'
  /// Failed
  failed = 'failed'
}

type LoadProgressInfo = {
  /// Load progress type
  type: LoadProgress
  /// Progress percentage 0-100
  progress?: number
  /// Error information
  error?: Error
}