# VoiceOrbs

> Animated, audio-reactive orbs for AI voice assistants: 14 copy-paste React components sharing one small props contract, distributed as source code and AI prompts instead of an npm package.

VoiceOrbs is a gallery of animated orb components for React / Next.js voice interfaces. Every orb is a client component that visualizes the assistant lifecycle through a `state` prop and reacts to live audio through a `levelRef` without re-renders. Integration is copy-paste: grab the component files plus a small shared lib from the site or the repo, or copy a ready-made AI prompt (with provider wiring for Vapi, ElevenLabs, LiveKit and OpenAI Realtime) and let a coding agent do it.

## Props contract

All orbs accept the same props (`OrbProps` in `src/registry/lib/orb-state.ts`):

- `state` (`'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking' | 'error' | 'disabled'`, default: 'idle'): Assistant lifecycle state driving the animation. error and disabled are optional extensions.
- `size` (`number`, default: 160-184 (per orb)): Diameter of the orb in pixels, also exposed as the --orb-size CSS variable.
- `speed` (`number`, default: 1): Animation speed multiplier, also exposed as the --orb-speed CSS variable.
- `colorFrom` (`string`, default: per-orb gradient start): Gradient start color (any CSS color), exposed as --orb-color-from.
- `colorTo` (`string`, default: per-orb gradient end): Gradient end color (any CSS color), exposed as --orb-color-to.
- `levelRef` (`RefObject<number>`, default: undefined): Live audio amplitude in 0..1 read every frame without re-render; a negative value falls back to the procedural animation.
- `label` (`string`, default: 'Assistant orb'): Accessible name announced by screen readers via aria-label.
- `className` (`string`, default: undefined): Extra class names merged onto the root element.
- `ref` (`Ref<HTMLDivElement>`, default: undefined): React 19 ref to the root element for measuring, animating or scrolling into view.

States: idle, connecting, listening, thinking, speaking form the core lifecycle; `error` and `disabled` are optional extensions implemented by every orb. Each orb also exposes the CSS variables `--orb-size`, `--orb-speed`, `--orb-color-from`, `--orb-color-to` and `--orb-level` for theming and animation from CSS.

## Orbs

- [Plasma Orb](https://voiceorbs.vercel.app/orbs/plasma-orb): Shader (canvas). Shader mesh gradient on canvas, no Three.js. Organic distortion.
- [Equalizer Orb](https://voiceorbs.vercel.app/orbs/equalizer-orb): Pure CSS. Equalizer bars inside a disc that react to the audio level.
- [Halo Orb](https://voiceorbs.vercel.app/orbs/halo-orb): Pure CSS. A conic halo with orbital rings and a bright core that pulses.
- [Particles Orb](https://voiceorbs.vercel.app/orbs/particles-orb): Canvas. Hundreds of particles form a rotating 3D sphere that breathes with your voice and scatters into a ring while connecting.
- [Pulse Orb](https://voiceorbs.vercel.app/orbs/pulse-orb): Pure CSS. Core with expanding rings and a loading arc. Minimal and SSR-safe.
- [Glass Orb](https://voiceorbs.vercel.app/orbs/glass-orb): Pure CSS. Iridescent glassmorphism with a spinning conic aura and specular highlight.
- [Aurora Orb](https://voiceorbs.vercel.app/orbs/aurora-orb): Pure CSS. Northern-lights veils that swirl and blur across a night sky.
- [Gooey Orb](https://voiceorbs.vercel.app/orbs/gooey-orb): SVG filters. Liquid blob whose edges “boil” with SVG noise and displacement.
- [Galaxy Orb](https://voiceorbs.vercel.app/orbs/galaxy-orb): Canvas. A glassy bubble holding a drifting starfield and nebula, with a specular glare and an iridescent, chromatic rim.
- [Nebula Orb](https://voiceorbs.vercel.app/orbs/nebula-orb): WebGL (R3F + GLSL). 3D sphere with simplex-noise displacement and fresnel. The “voice mode”.
- [Waveform Ring](https://voiceorbs.vercel.app/orbs/waveform-ring): Canvas. A ring whose radius traces the live waveform: time-domain audio drawn in polar coordinates.
- [Edge Glow](https://voiceorbs.vercel.app/orbs/edge-glow): Pure CSS. Siri-style ambient frame: a masked conic-gradient glow that wraps your own content instead of sitting in the middle.
- [Iridescent Flow](https://voiceorbs.vercel.app/orbs/iridescent-flow): Shader (canvas). Single-pass fragment shader with flowing iridescent hues. Raw WebGL, zero dependencies.
- [Mercury Orb](https://voiceorbs.vercel.app/orbs/mercury-orb): Shader (canvas). Paper liquid-metal shader: chrome ripples flowing around a molten core.

## Optional

- [GitHub repository](https://github.com/amunozdev/voiceorbs): full source, MIT licensed
- [Full source dump](https://voiceorbs.vercel.app/llms-full.txt): every orb plus the shared lib and an integration guide in one file