Skip to main content
Install orb-ui from npm:
Provider adapters also need their provider SDK installed in your app:
OpenAI Realtime uses browser WebRTC and does not require an additional client SDK. Standard OpenAI and Gemini API keys stay on your server. See the adapter overview for a concise comparison of what each provider setup requires.

Controlled mode

Controlled mode is the universal fallback. Use it when your app already owns the voice session and can provide a conversation state plus normalized volume.
The state can be one of:
  • idle
  • connecting
  • listening
  • thinking
  • speaking
  • error
Volume should be a number from 0 to 1. Use signal when your app has separate user input and assistant output levels:

Vapi

ElevenLabs

LiveKit

While the agent is listening, the adapter emits local microphone activity as inputVolume. While the agent is speaking, it emits the attached remote audio level as outputVolume. The adapter owns the LiveKit room, token source, audio analysis, and a fresh room name for each start.

Pipecat

See the Pipecat adapter guide for Pipecat Cloud and Daily.

OpenAI Realtime

The endpoint must mint short-lived credentials with your server-only API key. See the OpenAI Realtime adapter guide.

Gemini Live

See the Gemini Live adapter guide for ephemeral token creation and the matching server-side activity-detection config.

External session controls

Set interactive={false} when the orb should only display adapter state. Use the adapter’s public lifecycle methods from controls placed elsewhere in your interface.

Themes

Start with:
  • radial for a four-lobe call surface with different input and output reactions.
  • cloud for a soft atmospheric sphere with distinct listening and speaking motion.
  • circle for a primary assistant orb.
  • bars for waveform-like audio activity.
  • debug while verifying state and volume changes.
Visual themes include keyboard-accessible buttons when you provide an adapter or onStart/onStop handler. Add an aria-label if the surrounding UI does not already label the control, or pass interactive={false} when a separate control owns the session lifecycle. Use the voice states guide when you are deciding how each state should appear in your product.
Last modified on July 16, 2026