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