AvatarLayer — pluggable SDK for realtime conversational avatars

AtlasRenderer connects to North Model Labs Atlas for realtime lip-synced video avatars. Unlike LemonSlice, Atlas manages its own LiveKit room — you only need an Atlas API key (no separate LiveKit credentials).

Installation

npm install livekit-client

Usage

import { AtlasRenderer } from "avatarlayer";

const renderer = new AtlasRenderer({
  createSession: async () => {
    const resp = await fetch("/api/atlas", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        atlasApiKey: "...",
        faceUrl: "https://...",  // optional face image
      }),
    });
    return resp.json();
  },
  deleteSession: async (sessionId) => {
    await fetch(`/api/atlas/${sessionId}`, {
      method: "DELETE",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ atlasApiKey: "..." }),
    });
  },
  onVideoStream: (stream) => console.log("Video:", stream),
  onStateChange: (state) => console.log("State:", state),
});

Constructor options

Option	Type	Description
`createSession`	`() => Promise<AtlasSession>`	Required. Returns LiveKit connection info from Atlas.
`deleteSession`	`(sessionId: string) => Promise<void>`	Recommended. Tears down the session to stop billing.
`onVideoStream`	`(stream: MediaStream \| null) => void`	Called when video track is received/lost
`onAudioStream`	`(stream: MediaStream \| null) => void`	Called when audio track is received/lost
`onStateChange`	`(state: string) => void`	Called on connection state changes

AtlasSession shape

interface AtlasSession {
  sessionId: string | null;
  livekitUrl: string;
  token: string;
  room: string;
  mode: string | null;
}

How it works (passthrough mode)

Atlas uses passthrough mode — your TTS audio drives the avatar:

mount() calls createSession to get LiveKit credentials from Atlas
Connects to the LiveKit room
Creates a WebAudio pipeline: AudioContext → MediaStreamAudioDestinationNode
Publishes the destination stream as a LiveKit audio track
When speak(audio) is called, the audio blob is decoded and played through the WebAudio pipeline
Atlas receives the audio track and renders lip-synced video in realtime

Session lifecycle

Always delete sessions

Atlas sessions are billed while active. Always call deleteSession when done, or let unmount() handle it automatically.

When unmount() is called, the renderer:

Stops any current audio playback
Disconnects from the LiveKit room
Closes the AudioContext
Calls deleteSession if a session ID exists