LiveKit Agents Integration Client

new AvatarPlayer(provider: LiveKitProvider, avatarView: AvatarView, options?: AvatarPlayerOptions)

interface LiveKitProviderOptions {
  /** Exact LiveKit publication track name to treat as the motion data track. */
  animationTrackName?: string

  /** Pattern for LiveKit publication track names to treat as motion data tracks. */
  animationTrackNamePattern?: RegExp
}

const provider = new LiveKitProvider({
  animationTrackName: 'custom-motion-track',
})

interface AvatarPlayerOptions {
  /** Log level: 'info' | 'warning' | 'error' | 'none'. Default: 'warning' */
  logLevel?: LogLevel

  /**
   * Enable jitter buffer for smoother animation playback. When enabled, frames are
   * buffered and rendered in sequence at a steady 25fps, absorbing network jitter
   * and out-of-order delivery. Default: true.
   */
  enableJitterBuffer?: boolean

  /**
   * Max delay (ms) a frame can sit in the jitter buffer before being rendered.
   * Only used when enableJitterBuffer is true. Default: 80 (2 frames @ 25fps).
   */
  maxBufferDelayMs?: number
}

// Connect to LiveKit server
await player.connect(config: LiveKitConnectionConfig): Promise<void>

// Disconnect and clean up
await player.disconnect(): Promise<void>

// Reconnect using last config (useful after stalls)
await player.reconnect(): Promise<void>

// Check connection status
player.isConnected           // boolean
player.getConnectionState()  // string

// Read cumulative RTC playback diagnostics for this player lifetime
player.sessionSummary

interface LiveKitConnectionConfig {
  url: string       // LiveKit server URL (wss://...)
  token: string     // Auth token from your backend
  roomName: string  // Room name
}

// Start microphone (requests permission automatically)
await player.startPublishing()

// Stop microphone
await player.stopPublishing()

// Publish a custom audio track
await player.publishAudio(track: MediaStreamTrack)

// Stop custom audio
await player.unpublishAudio()

import type { LiveKitRoom } from '@spatius/avatarkit-rtc'

// Via provider (recommended — full type safety)
const room = provider.getNativeClient()  // LiveKitRoom | null

// Via player (requires type assertion)
const room = player.getNativeClient() as LiveKitRoom | null

console.log('Remote participants:', room?.remoteParticipants.size)

type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'

player.on(event: string, handler: Function)
player.off(event: string, handler: Function)

const summary = player.sessionSummary

player.on('stalled', async () => {
  console.log('Stream stalled, reconnecting...')
  try {
    await player.reconnect()
  } catch (error) {
    console.error('Reconnection failed:', error)
  }
})

import { AvatarPlayer, LiveKitProvider } from '@spatius/avatarkit-rtc'
import { AvatarSDK, AvatarView, AvatarManager, DrivingServiceMode } from '@spatius/avatarkit'

async function init() {
  // Initialize AvatarKit for LiveKit transport rendering.
  await AvatarSDK.initialize('your-app-id', {
    region: 'us-west',
    drivingServiceMode: DrivingServiceMode.backend,
  })

  // `setSessionToken` is not needed on the RTC Adapter path —
  // `DrivingServiceMode.backend` does not open a Motion Server WebSocket from the client,
  // and `AvatarManager.load()` fetches avatar metadata over an App-ID-scoped public endpoint.

  // Load avatar and create view
  const avatar = await AvatarManager.shared.load('character-id')
  const container = document.getElementById('avatar-container')!
  const avatarView = new AvatarView(avatar, container)

  // Create player
  const provider = new LiveKitProvider()
  const player = new AvatarPlayer(provider, avatarView, {
    logLevel: 'info',
    enableJitterBuffer: true,
    maxBufferDelayMs: 80,
  })

  // Listen to events
  player.on('connected', () => console.log('Connected!'))
  player.on('disconnected', () => console.log('Disconnected!'))
  player.on('error', (err) => console.error('Error:', err))
  player.on('stalled', async () => {
    console.log('Stream stalled, reconnecting...')
    await player.reconnect()
  })

  // Connect to LiveKit server
  await player.connect({
    url: 'wss://your-livekit-server.com',
    token: 'your-livekit-token',
    roomName: 'my-room',
  })

  // Start microphone
  await player.startPublishing()
}