@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.- LiveKit
- Agora
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 constructingAvatarPlayer.
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.
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
AvatarPlayer
Constructor
AvatarPlayerOptions
Properties
Treat the shape of
sessionSummary as diagnostics data, not application state.
Methods
Audio publishing
UsestartPublishing() 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 exportsConnectionState:
Conversation state
The package exportsRTCConversationState:
- It becomes
speakingon the first rendered frame of a response, including the transition into speech. - It returns to
idleonce the transition back to idle has finished playing. - A stalled stream, a disconnect, or a call to
disconnect()ordetach()while the Avatar is speaking returns it toidleonce.
'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 defaultconnect() 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 withsinglePeerConnection: 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:

