RTC Adapter

@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

Package	Role
`@spatius/avatarkit`	Web avatar rendering SDK.
`@spatius/avatarkit-rtc`	Web 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

Scenario	Use RTC Adapter?
Direct Mode	No. Use `@spatius/avatarkit` directly.
Backend Mode with your own WebSocket	Usually no. Your client manually calls `yieldAudioData()` / `yieldFramesData()`.
Backend Mode with LiveKit / Agora egress transport	Yes. The Web client uses the RTC Adapter.
LiveKit Agents Integration	Yes. The Web client uses the RTC Adapter with `LiveKitProvider`.
Agora Convo AI Integration	Yes 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
npm
yarn

pnpm add @spatius/avatarkit-rtc @spatius/avatarkit

npm install @spatius/avatarkit-rtc @spatius/avatarkit

yarn 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.

Initialize the underlying SDK with DrivingServiceMode.rtc. Constructing an AvatarPlayer throws if the SDK was initialized with another mode, or before initialize() was called.

import { AvatarSDK, DrivingServiceMode } from '@spatius/avatarkit'

await AvatarSDK.initialize(appId, {
  drivingServiceMode: DrivingServiceMode.rtc,
})

How it works

The RTC Adapter is a thin layer on top of @spatius/avatarkit:

It runs on top of the underlying SDK initialized with DrivingServiceMode.rtc, so the avatar accepts externally driven motion data.
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.
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.
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)

Option	Type	Description
`animationTrackName`	`string`	Exact LiveKit publication track name to treat as the motion data track.
`animationTrackNamePattern`	`RegExp`	Pattern for LiveKit publication track names to treat as motion data tracks.

Provider	Status
`LiveKitProvider`	Documented here. Demoed in `platform-integrations/livekit-room-demo`.
`AgoraProvider`	Documented 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.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Codes

What it is

When to use the RTC Adapter

Install

How it works

Provider abstraction

LiveKitProviderOptions

Native client access

API

LiveKit Agents Client

Agora Client

Backend Mode with LiveKit

​What it is

​When to use the RTC Adapter

​Install

​How it works

​Provider abstraction

​LiveKitProviderOptions

​Native client access

​API

​Related guides

LiveKit Agents Client

Agora Client

Backend Mode with LiveKit

What it is

When to use the RTC Adapter

Install

How it works

Provider abstraction

LiveKitProviderOptions

Native client access

API

Related guides