Skip to main content
@spatius/avatarkit-rtc feeds motion data from a supported RTC room into AvatarKit for local rendering. In its managed path, it also creates the RTC client and plays the remote audio.

Package boundary

The RTC Adapter is part of the Web SDK family. Native Agora clients use AvatarKitRTC on iOS or ai.spatius:avatarkit-rtc on Android.

Install

Install the peer for the provider your application uses.

Package compatibility

@spatius/avatarkit-rtc declares peer dependencies on AvatarKit and the selected RTC client. Install the packages together, and treat peer-dependency warnings as compatibility errors. For exact current ranges, check the package’s published peerDependencies instead of relying on a version copied into this page.

Runtime contract

Initialize AvatarKit in RTC mode before constructing AvatarPlayer.
Create the AvatarView and wait for its onFirstRendering callback before constructing or connecting an AvatarPlayer. AvatarView initializes its renderer asynchronously; the constructor returning is not a readiness signal.
The adapter owns the RTC-to-renderer data flow. Do not feed audio or motion data into AvatarKit yourself while it is active.

Providers

LiveKitProviderOptions

Most applications use new LiveKitProvider() without options. Use these options only when the room publishes motion data under custom track names.

Connection configuration

Use short-lived room credentials returned by your backend. Never put a LiveKit API secret, Agora App Certificate, or Spatius API Key in the browser.

AvatarPlayer

Constructor

AvatarPlayerOptions

Properties

Treat the shape of sessionSummary as diagnostics data, not application state.

Methods

Audio publishing

Use startPublishing() for the microphone or supply any browser audio track with publishAudio().
unpublishAudio() does not stop a host-supplied track. The application that created it must release it.

State and events

The package exports ConnectionState:

Conversation state

The package exports RTCConversationState:
Use it to drive speaking indicators and idle UI. The state follows what is on screen, not what has arrived over the network:
  • It becomes speaking on the first rendered frame of a response, including the transition into speech.
  • It returns to idle once the transition back to idle has finished playing.
  • A stalled stream, a disconnect, or a call to disconnect() or detach() while the Avatar is speaking returns it to idle once.
'conversation-state-changed' fires once per change, never per frame. Read player.conversationState for the current value.
In RTC mode, use RTCConversationState from AvatarPlayer. AvatarKit’s own AvatarController conversation state callback does not fire when @spatius/avatarkit-rtc drives the Avatar.

Host-owned RTC clients

The default connect() path lets the adapter create and own the RTC client. Use attach() only when your application already owns that client.

LiveKit Room

Create the room with singlePeerConnection: false, attach before connecting, and use detach() before your application disconnects the room. In this flow, your application also owns remote audio playback.

Agora client

Attach before joining the channel. The host-owned client must use the H.264 codec and remains responsible for joining, subscribing, audio playback, and leaving.
attach() turns on two Agora Web SDK parameters, ENABLE_VIDEO_SEI and ENABLE_FULL_LINK_AV_SYNC. The avatar needs them. They are set on the AgoraRTC module, so they apply to every Agora client on the page, and detach() does not turn them off. Do not mix connect() with attach() on the same player.

Native client access

For provider-specific features in the managed path, read the client owned by the provider:
player.getNativeClient() returns the same object as unknown; keep the provider reference when you want the provider-specific type.

Browser requirements

The package targets browser applications. AvatarKit’s WebAssembly and rendering requirements still apply; see Web Toolchain Setup. LiveKitProvider additionally requires RTCRtpScriptTransform to receive motion data. Check for the capability at runtime instead of relying on a fixed browser-version table:
Browser autoplay policies can also require a user gesture before remote audio plays or microphone capture begins.

Next steps

LiveKit Agents Client

Agora Convo AI Client