> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RTC Adapter

> Use @spatius/avatarkit-rtc as the Web transport adapter for LiveKit and Agora RTC providers.

`@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](/agora-convoai/client), not this npm package.

<Note>
  **Web only.** The RTC Adapter currently targets browser apps.
</Note>

## 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`](https://github.com/spatius-ai/spatius-avatar-demo/tree/main/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](/agora-convoai/client).

## Install

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @spatius/avatarkit-rtc @spatius/avatarkit
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @spatius/avatarkit-rtc @spatius/avatarkit
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @spatius/avatarkit-rtc @spatius/avatarkit
    ```
  </Tab>
</Tabs>

<Warning>
  **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.

  ```json title="package.json" theme={null}
  {
    "dependencies": {
      "livekit-client": "2.16.1"
    }
  }
  ```
</Warning>

<Note>
  `@spatius/avatarkit-rtc@1.1.0` requires `@spatius/avatarkit@1.2.0` or newer.
</Note>

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

<Warning>
  **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.
</Warning>

## Provider abstraction

```typescript theme={null}
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.

```typescript theme={null}
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`](https://github.com/spatius-ai/spatius-avatar-demo/tree/main/platform-integrations/livekit-room-demo).          |
| `AgoraProvider`   | Documented in [Agora Convo AI Client](/agora-convoai/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:

```typescript theme={null}
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()`.

```typescript theme={null}
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](/livekit-agents/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.

## Related guides

<CardGroup cols={3}>
  <Card title="LiveKit Agents Client" icon="bolt" href="/livekit-agents/client">
    Use the RTC Adapter with a LiveKit Agents worker.
  </Card>

  <Card title="Agora Client" icon="tower-broadcast" href="/agora-convoai/client">
    Use the RTC Adapter with an Agora Convo AI graph.
  </Card>

  <Card title="Backend Mode with LiveKit" icon="route" href="/backend-mode/with-livekit">
    Use the RTC Adapter as the Web transport for a Backend Mode pipeline.
  </Card>
</CardGroup>