Skip to main content
FaceMode turns your application’s audio into a real-time, lip-synced avatar video track published into your LiveKit or Daily room. There are two ways to integrate.

​
Two integration paths

​
Agent framework plugins

If you build on LiveKit Agents or Pipecat, install the FaceMode plugin for your framework. Each plugin creates the FaceMode session, opens the ingestion WebSocket, speaks the canonical audio protocol, reconnects on transport drops, and surfaces the avatar’s media in your room. You keep writing agent code; the plugin handles the avatar plumbing.

​
Direct API

For any other stack, your backend calls the FaceMode REST API to create a session, opens a WebSocket to the session’s ingestion endpoint, and streams PCM audio itself. Your frontend joins the room with the LiveKit or Daily client SDK exactly as it does today. This path gives you full control over the wire protocol and works from any language that can open a WebSocket.

​
Which path should I use?

The published plugins support LiveKit rooms today. For Daily rooms, use the direct API.

​
Prerequisites

Every integration path needs the same three things:
1

A FaceMode API key

Your backend authenticates REST calls with the x-api-key header set to <FACEMODE_API_KEY>. Keys are created and managed from the FaceMode dashboard. See Authentication.
2

An avatar ID

The avatar ID selects which talking-head avatar renders your audio. Pass it as avatarId on session creation (or avatar_id / avatarId in the plugin constructors).
3

A room and a publish token

FaceMode joins a room you own as a publishing participant. You supply a server-side room object with the room URL and a token that grants FaceMode permission to join, publish, and subscribe. For LiveKit that means room_join, can_publish, and can_subscribe grants on the exact room name. FaceMode does not create or replace your room.
Keep every credential on your server. The room token, FaceMode API key, and WebSocket token must never appear in browser code or client logs. Browser clients join the room with their own, separately issued token.

​
How a session flows

All paths share the same lifecycle:
  1. POST /api/sessions creates a session and returns ingestion.ready, the ingestion WebSocket url, and a one-time wsToken.
  2. Your backend connects to url with the facemode.<wsToken> subprotocol, sends start, and waits for started.
  3. Your audio flows as binary pcm_s16le frames; FaceMode publishes the avatar video and audio tracks into your room.
  4. end_session closes the session; FaceMode acknowledges with ended.
The plugins perform all of this for you. The direct API path is documented step by step in Direct API integration, with the full message set in the WebSocket protocol reference.

​
Integration guides

LiveKit Agents (Python)

Install livekit-plugins-facemode and attach an AvatarSession to your AgentSession.

LiveKit Agents (JS / TS)

Install @facemode/agents-plugin-facemode for the LiveKit Agents JavaScript framework.

Pipecat

Drop FaceModeVideoService into your pipeline between TTS and the output transport.

Direct API

Drive the REST API and canonical WebSocket protocol from any backend.