AvatarKit Web SDK Reference

import { AvatarSDK } from '@spatius/avatarkit'

await AvatarSDK.initialize('your-app-id', {
  region: 'us-west',
  drivingServiceMode: DrivingServiceMode.direct,    // optional, default: direct
  logLevel: LogLevel.warning,                       // optional, default: off
  renderQuality: RenderQuality.ultra,               // optional, default: ultra
  audioFormat: {                                    // optional
    channelCount: 1,
    sampleRate: 16000,
  },
})

AvatarSDK.setSessionToken('your-session-token')

AvatarSDK.setUserId('user-123')

AvatarSDK.setRenderQuality(RenderQuality.high)

AvatarSDK.setRenderResolutionCap(true, 1080)

const { cpuScore, gpuScore } = await AvatarSDK.deviceScore()

const supported = await AvatarSDK.isDeviceSupported()

AvatarSDK.cleanup()

import { AvatarManager } from '@spatius/avatarkit'

const avatar = await AvatarManager.shared.load('avatar-id', (progress) => {
  switch (progress.type) {
    case 'downloading': {
      // progress.progress is in 0..1; multiply by 100 to render as a percentage.
      const percent = Math.round((progress.progress ?? 0) * 100)
      console.log(`Loading: ${percent}%`)
      break
    }
    case 'completed':
      console.log('Load complete')
      break
    case 'failed':
      console.error('Load failed:', progress.error)
      break
  }
})

const cancelled = AvatarManager.shared.cancelLoad('avatar-id')

const cachedAvatar = AvatarManager.shared.retrieve('avatar-id')

AvatarManager.shared.clear('avatar-id')

AvatarManager.shared.clearAll()

import { AvatarView } from '@spatius/avatarkit'

const avatarView = new AvatarView(avatar, container)

avatarView.dispose()

const png = await avatarView.exportBitmap()
if (png) {
  // Use the Blob for download, upload, or preview.
}

const camera = avatarView.getCameraConfig()
if (camera) {
  avatarView.updateCameraConfig({
    ...camera,
    fov: 35,
  })
}

avatarView.pauseRendering()
avatarView.resumeRendering()

const rendering = avatarView.isRenderingEnabled()

const rect = avatarView.getBoundingRect()
if (rect) {
  console.log(rect.x, rect.y, rect.width, rect.height)
}

// Accessed via AvatarView
const controller = avatarView.controller

// Connection state changes
controller.onConnectionState = (state: ConnectionState) => {
  // 'disconnected' | 'connecting' | 'connected' | 'failed'
}

// Conversation state changes
controller.onConversationState = (state: ConversationState) => {
  // 'idle' | 'playing' | 'paused'
}

// Error events
controller.onError = (error: AvatarError) => {
  console.error('Error:', error.code, error.message)
}

// Animation type changes
controller.onAnimationState = (type: AnimationType) => {
  // 'idle' | 'mono'
}

// Only fires when frameStarvationMode is FrameStarvationMode.strictSync
controller.onPlaybackStall = (stalled: boolean) => {
  console.log('Playback stalled:', stalled)
}

button.addEventListener('click', async () => {
  await controller.initializeAudioContext()
})

await controller.start()

const conversationId = controller.send(
  audioData,  // PCM16, mono, ArrayBuffer
  end,        // true = end of conversation round
)

controller.close()

const conversationId = controller.yieldAudioData(audioData, false)

const ended = controller.yieldFramesData(motionDataPayloads, conversationId)

controller.pause()                     // Pause audio + animation
await controller.resume()              // Resume playback
controller.interrupt()                 // Stop current playback
controller.getAudioTime()              // Current audio playback time in seconds

// Volume control (avatar audio only, not system volume)
controller.setVolume(0.5)              // 0.0 to 1.0
controller.getVolume()                 // returns current volume

interface Configuration {
  region?: string                            // Defaults to 'us-west'
  drivingServiceMode?: DrivingServiceMode    // Default: DrivingServiceMode.direct
  logLevel?: LogLevel                        // Default: LogLevel.off
  audioFormat?: AudioFormat                  // Default: { channelCount: 1, sampleRate: 16000 }
  customEndpoint?: string                    // Advanced override
  renderQuality?: RenderQuality              // Default: RenderQuality.ultra
}

enum DrivingServiceMode {
  direct = 'direct',    // Client SDK handles the Motion Server connection (Direct Mode)
  backend = 'backend',  // Your backend handles the Motion Server connection (Backend Mode)
}

enum RenderQuality {
  standard = 'standard',
  high = 'high',
  ultra = 'ultra',
}

enum FrameStarvationMode {
  audioIndependent = 'audioIndependent',
  strictSync = 'strictSync',
}

enum AnimationType {
  idle = 'idle',
  mono = 'mono',
}

enum LogLevel {
  off = 'off',          // No logging (default)
  error = 'error',      // Errors only
  warning = 'warning',  // Errors + warnings
  all = 'all',          // All logs
}

enum ConnectionState {
  disconnected = 'disconnected',
  connecting = 'connecting',
  connected = 'connected',
  failed = 'failed',
}

enum ConversationState {
  idle = 'idle',        // Breathing animation, waiting for input
  playing = 'playing',  // Active conversation playback
  paused = 'paused',    // Paused during playback
}

type LoadProgressInfo = {
  type: 'downloading' | 'completed' | 'failed'
  progress?: number  // 0..1
  error?: Error
}

interface AudioFormat {
  readonly channelCount: 1   // Fixed to mono
  readonly sampleRate: number // 8000 | 16000 | 22050 | 24000 | 32000 | 44100 | 48000
}

import { AvatarError } from '@spatius/avatarkit'

try {
  await avatarView.controller.start()
} catch (error) {
  if (error instanceof AvatarError) {
    console.error('SDK error:', error.message, error.code)
  }
}

avatarView.controller.onError = (error: AvatarError) => {
  console.error('Controller error:', error.code, error.message)
}

enum ErrorCode {
  appIDUnrecognized = 'appIDUnrecognized',
  sessionTokenInvalid = 'sessionTokenInvalid',
  sessionTokenExpired = 'sessionTokenExpired',
  insufficientBalance = 'insufficientBalance',
  concurrentLimitExceeded = 'concurrentLimitExceeded',
  avatarIDUnrecognized = 'avatarIDUnrecognized',
  failedToFetchAvatarMetadata = 'failedToFetchAvatarMetadata',
  invalidAvatarMetadata = 'invalidAvatarMetadata',
  failedToDownloadAvatarAssets = 'failedToDownloadAvatarAssets',
  websocketError = 'websocketError',
  websocketClosedAbnormally = 'websocketClosedAbnormally',
  websocketClosedUnexpected = 'websocketClosedUnexpected',
  sessionTimeout = 'sessionTimeout',
  connectionInProgress = 'connectionInProgress',
  networkLayerNotAvailable = 'networkLayerNotAvailable',
  playbackStartFailed = 'playbackStartFailed',
  playbackInitFailed = 'playbackInitFailed',
  audioOnlyInitFailed = 'audioOnlyInitFailed',
  noAudio = 'noAudio',
  audioContextNotInitialized = 'audioContextNotInitialized',
  animationPlayerNotInitialized = 'animationPlayerNotInitialized',
  serverError = 'serverError',
}

// 1. Dispose the current view
currentAvatarView.dispose()

// 2. Load a new avatar
const newAvatar = await AvatarManager.shared.load('new-avatar-id')

// 3. Create a new view (reuse the same container)
currentAvatarView = new AvatarView(newAvatar, container)

// 4. Reconnect
await currentAvatarView.controller.initializeAudioContext()
await currentAvatarView.controller.start()

import {
  AvatarSDK,
  AvatarManager,
  AvatarView,
  ConnectionState,
  ConversationState,
} from '@spatius/avatarkit'

class AvatarApp {
  private avatarView: AvatarView | null = null

  async init(appId: string, sessionToken: string, avatarId: string, container: HTMLElement) {
    // Initialize the SDK
    await AvatarSDK.initialize(appId, { region: 'us-west' })
    AvatarSDK.setSessionToken(sessionToken)

    // Load the avatar
    const avatar = await AvatarManager.shared.load(avatarId)
    if (!avatar) throw new Error('Failed to load avatar')

    // Create the view
    this.avatarView = new AvatarView(avatar, container)
    this.avatarView.onFirstRendering = () => {
      console.log('First frame rendered')
    }

    // Wire up handlers
    this.avatarView.controller.onConnectionState = (state) => {
      console.log('Connection:', state)
    }
    this.avatarView.controller.onConversationState = (state) => {
      console.log('Conversation:', state)
    }
    this.avatarView.controller.onError = (error) => {
      console.error('Error:', error)
    }
  }

  // Must be called inside a user-gesture handler
  async start() {
    await this.avatarView?.controller.initializeAudioContext()
    await this.avatarView?.controller.start()
  }

  send(audioData: ArrayBuffer, isEnd: boolean) {
    this.avatarView?.controller.send(audioData, isEnd)
  }

  interrupt() {
    this.avatarView?.controller.interrupt()
  }

  dispose() {
    this.avatarView?.controller.close()
    this.avatarView?.dispose()
    this.avatarView = null
  }
}