AvatarKit Web SDK Reference

import { AvatarSDK } from '@spatius/avatarkit'

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

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

AvatarSDK.setUserId('user-123')

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
  }
})

AvatarManager.shared.clearAll()

import { AvatarView } from '@spatius/avatarkit'

const avatarView = new AvatarView(avatar, container)

avatarView.dispose()

// 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)
}

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)

controller.yieldFramesData(motionFrames, conversationId)

controller.pause()                     // Pause audio + animation
controller.resume()                    // Resume playback
controller.interrupt()                 // Stop current playback

// 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'; 'ap-northeast' is also supported
  drivingServiceMode?: DrivingServiceMode    // Default: DrivingServiceMode.sdk
  logLevel?: LogLevel                        // Default: LogLevel.off
  audioFormat?: AudioFormat                  // Default: { channelCount: 1, sampleRate: 16000 }
}

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

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)
}

// 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
  }
}