Skip to main content
@spatius/avatarkit-rtc is the Web RTC transport adapter for AvatarKit. It lets a browser app render a Spatius avatar from an RTC room by connecting to the room, playing the remote audio track through WebRTC, and feeding motion data into @spatius/avatarkit.

​
What it is

PackageRole
@spatius/avatarkitWeb avatar rendering SDK.
@spatius/avatarkit-rtcWeb transport adapter for RTC rooms. Depends on @spatius/avatarkit.
The RTC Adapter is part of the Web SDK family, not a standalone cross-platform SDK and not a diagnostic tool. Native Agora Convo AI clients use the platform RTC packages documented in Agora Convo AI Client, not this npm package.
Web only. The RTC Adapter currently targets browser apps.

​
When to use the RTC Adapter

ScenarioUse RTC Adapter?
Direct ModeNo. Use @spatius/avatarkit directly.
Backend Mode with your own WebSocketUsually no. Your client manually calls yieldAudioData() / yieldFramesData().
Backend Mode with LiveKit / Agora egress transportYes. The Web client uses the RTC Adapter.
LiveKit Agents IntegrationYes. The Web client uses the RTC Adapter with LiveKitProvider.
Agora Convo AI IntegrationYes for Web. Native clients use their platform RTC packages with AgoraProvider.
The platform-integrations/livekit-room-demo demo is the minimal LiveKit example for the RTC Adapter; it is not the full Backend Mode + RTC transport voice-agent demo. For Agora, see Agora Convo AI Client.

​
Install

pnpm add @spatius/avatarkit-rtc @spatius/avatarkit
Pin livekit-client to 2.16.1 if you install it directly in your app. @spatius/avatarkit-rtc is built against this version; other 2.x releases can introduce protocol changes that break the adapter’s room wiring.
package.json
{
  "dependencies": {
    "livekit-client": "2.16.1"
  }
}
@spatius/[email protected] requires @spatius/[email protected] or newer.

​
How it works

The RTC Adapter is a thin layer on top of @spatius/avatarkit:
  1. It initializes the underlying SDK with DrivingServiceMode.backend so the avatar accepts externally driven motion data.
  2. A provider opens an RTC connection to the room. This page documents and demos LiveKitProvider; AgoraProvider is also exported by @spatius/avatarkit-rtc with the same AvatarPlayer surface.
  3. The provider publishes the local microphone track (when startPublishing() is called) and subscribes to the remote audio track and the motion data stream published by Motion Server.
  4. The browser plays the remote audio track through WebRTC. The RTC Adapter feeds motion data into @spatius/avatarkit for local rendering.
Do not call yieldAudioData() or yieldFramesData() manually when using the RTC Adapter. The adapter owns the data flow from the room to the renderer. Manual feeds bypass the provider and corrupt playback timing.

​
Provider abstraction

import { AvatarPlayer, LiveKitProvider } from '@spatius/avatarkit-rtc'

const provider = new LiveKitProvider()
const player = new AvatarPlayer(provider, avatarView, options)

​
LiveKitProviderOptions

Most LiveKit integrations use the default provider constructor. If your LiveKit transport publishes the motion data track under a custom publication name, pass a LiveKitProviderOptions object. 
import { LiveKitProvider, type LiveKitProviderOptions } from '@spatius/avatarkit-rtc'

const providerOptions: LiveKitProviderOptions = {
  animationTrackName: 'custom-motion-track',
  // Or match a family of track names:
  // animationTrackNamePattern: /^spatius-motion-/,
}

const provider = new LiveKitProvider(providerOptions)
OptionTypeDescription
animationTrackNamestringExact LiveKit publication track name to treat as the motion data track.
animationTrackNamePatternRegExpPattern for LiveKit publication track names to treat as motion data tracks.
ProviderStatus
LiveKitProviderDocumented here. Demoed in platform-integrations/livekit-room-demo.
AgoraProviderDocumented in Agora Convo AI Client. API surface mirrors LiveKitProvider; connection config uses appId, channel, optional token, and optional uid.
The same AvatarPlayer surface works across providers — code that talks to the player does not need to change when the provider swaps. Both providers are exported from the package root: 
import { LiveKitProvider, AgoraProvider } from '@spatius/avatarkit-rtc'

​
Native client access

The RTC Adapter creates and owns the low-level RTC client internally. Do not create a separate LiveKit Room or Agora Web SDK client for avatar playback. For advanced platform features, access the owned client through getNativeClient(). 
import type { LiveKitRoom, AgoraClient } from '@spatius/avatarkit-rtc'

const liveKitRoom = liveKitProvider.getNativeClient()  // LiveKitRoom | null
const agoraClient = agoraProvider.getNativeClient()    // AgoraClient | null

const sameLiveKitRoom = liveKitPlayer.getNativeClient() as LiveKitRoom | null
const sameAgoraClient = agoraPlayer.getNativeClient() as AgoraClient | null
Use the provider method when you still have a typed provider reference. Use the AvatarPlayer method when your app plumbing only has the player instance. The value is null until the provider has a native RTC client to return.

​
API

For the full AvatarPlayer API — constructor options, connect, microphone control, custom audio publishing, events, reconnect, and browser compatibility — see LiveKit Agents Integration Client. The signatures are exposed by the same package; only the integration narrative on that page differs. AvatarPlayer also exposes sessionSummary, a read-only diagnostics snapshot for the current player lifetime. Use it to inspect cumulative RTC playback health, such as ordering, loss recovery, skipped playback, and stalled playback behavior. Treat the object shape as SDK-owned diagnostics data rather than application state.

LiveKit Agents Client

Use the RTC Adapter with a LiveKit Agents worker.

Agora Client

Use the RTC Adapter with an Agora Convo AI graph.

Backend Mode with LiveKit

Use the RTC Adapter as the Web transport for a Backend Mode pipeline.