LiveKit Voice UI for React

LiveKit Agents handles the realtime media and agent session layer. orb-ui handles the browser Room, microphone and agent audio, normalized conversation state, and the visible React UI. The token-endpoint example below is the intended application setup. The dedicated LiveKit entrypoint imports the official SDK only for LiveKit users and hides its mechanical constructors and audio analyser setup. Existing-room, raw credential, and custom fetcher modes remain advanced alternatives.

Install

Install orb-ui and the LiveKit client package used by your app:

npm install orb-ui livekit-client

Use a token endpoint

In the recommended setup, your app exposes a token endpoint and the adapter fetches fresh LiveKit connection details when the orb starts. Use LiveKit’s TokenSource endpoint contract: the JSON response includes { server_url, participant_token }. The adapter generates a unique orb-<uuid> room name for every start.

import { Orb } from 'orb-ui'
import { createLiveKitAdapter } from 'orb-ui/adapters/livekit'

const adapter = createLiveKitAdapter({
  tokenEndpoint: '/api/livekit-token',
  agentName: 'your-agent-name',
})

export function LiveKitVoiceUI() {
  return <Orb adapter={adapter} theme="circle" aria-label="Start LiveKit assistant" />
}

agentName is optional when your token endpoint already decides which agent to dispatch. Override roomName only when your app needs a specific room:

const adapter = createLiveKitAdapter({
  tokenEndpoint: '/api/livekit-token',
  agentName: 'your-agent-name',
  roomName: () => `support-${customerId}-${crypto.randomUUID()}`,
})

Use a LiveKit Cloud sandbox

For local and preview testing, LiveKit’s sandbox token server can generate connection details without your own backend. Do not use this mode in production.

import { Orb } from 'orb-ui'
import { createLiveKitAdapter } from 'orb-ui/adapters/livekit'

const adapter = createLiveKitAdapter({
  sandboxId: 'token-server-abc123',
  agentName: 'your-agent-name',
})

export function LiveKitVoiceUI() {
  return <Orb adapter={adapter} theme="circle" aria-label="Start LiveKit assistant" />
}

Advanced connection ownership

Import from orb-ui/adapters when your application already owns the connection fetcher, Room, token source, or runtime helpers. For example, a custom connection fetcher can inspect your own application state:

import { Room, createAudioAnalyser } from 'livekit-client'
import { createLiveKitAdapter } from 'orb-ui/adapters'

const adapter = createLiveKitAdapter({
  getConnectionDetails: async ({ agentName, roomName }) => {
    const response = await fetch('/api/livekit-token', {
      method: 'POST',
      body: JSON.stringify({ agentName, roomName }),
    })

    return response.json()
  },
  tokenOptions: {
    agentName: 'your-agent-name',
    roomName: () => `orb-${crypto.randomUUID()}`,
  },
  createAudioAnalyser,
  RoomClass: Room,
})

Use an existing room

Use an existing room when your app already owns the LiveKit lifecycle. The adapter subscribes to room state but does not expose start or stop.

import { createAudioAnalyser } from 'livekit-client'
import { Orb } from 'orb-ui'
import { createLiveKitAdapter } from 'orb-ui/adapters'

const adapter = createLiveKitAdapter({
  room,
  createAudioAnalyser,
})

export function LiveKitVoiceUI() {
  return <Orb adapter={adapter} theme="circle" aria-label="LiveKit assistant status" />
}

Use raw connection details

Raw credentials are supported as an advanced escape hatch. Generate participant tokens on your server, keep them short-lived, and avoid hard-coding them in browser bundles.

const adapter = createLiveKitAdapter({
  serverUrl: 'wss://your-project.livekit.cloud',
  participantToken: 'short-lived-participant-token',
  createAudioAnalyser,
  RoomClass: Room,
})

State mapping

The adapter reads the agent participant’s lk.agent.state attribute and maps LiveKit state into orb-ui state:

speaking -> speaking
thinking -> thinking
listening and idle -> listening
connecting, pre-connect-buffering, and initializing -> connecting
disconnected -> idle
failed -> error

LiveKit remote agent audio is attached when available. The recommended browser entrypoint creates the SDK audio analysers automatically: the local microphone emits normalized inputVolume while the agent is listening, and remote agent audio emits normalized outputVolume while the agent is speaking. The adapter supplies a speech-oriented decibel range to LiveKit’s analyser instead of using its narrow defaults, then maps each direction into the standard orb-ui speech envelope.

Directional calibration

LiveKit ships with separate microphone and agent-output profiles. Most applications should use the defaults. For an unusual audio path, pass partial inputVolumeCalibration or outputVolumeCalibration overrides, or a getter when a generated profile should update during a live session:

const adapter = createLiveKitAdapter({
  tokenEndpoint: '/api/livekit-token',
  agentName: 'your-agent-name',
  outputVolumeCalibration: {
    amplitude: { speechReference: 0.14 },
    envelope: { fallTimeMs: 550 },
  },
  onOutputVolumeSample: ({ raw, mapped, normalized }) => {
    console.debug({ raw, mapped, normalized })
  },
})

See volume calibration for anchor semantics, input/output overrides, and the guided profile generator.

Token handling

Do not create LiveKit access tokens in the browser. Point tokenEndpoint at a server-backed route that generates short-lived participant tokens. TokenSource and getConnectionDetails remain available through the advanced entrypoint when your application needs to own that behavior.

Controlled mode

If your app already normalizes LiveKit state and volume, pass those values directly as a signal.

<Orb signal={{ state: voiceState, inputVolume, outputVolume }} theme="circle" />

Start

Reference

Adapters

Recipes

Guides

LiveKit Voice UI for React

Install

Use a token endpoint

Use a LiveKit Cloud sandbox

Advanced connection ownership

Use an existing room

Use raw connection details

State mapping

Directional calibration

Token handling

Controlled mode

​Install

​Use a token endpoint

​Use a LiveKit Cloud sandbox

​Advanced connection ownership

​Use an existing room

​Use raw connection details

​State mapping

​Directional calibration

​Token handling

​Controlled mode

​Related

Install

Use a token endpoint

Use a LiveKit Cloud sandbox

Advanced connection ownership

Use an existing room

Use raw connection details

State mapping

Directional calibration

Token handling

Controlled mode

Related