Voice Orb

The face of a voice agent: a sphere of ink dots that waves with the voice, orbits while thinking and ripples while speaking.

Listening
'use client';

import { useEffect, useState } from 'react';
import { DictationButton, MagnetTabs, VoiceOrb } from '@brand-studio/ui';
import type { VoiceOrbShape, VoiceState } from '@brand-studio/ui';

const states: VoiceState[] = ['idle', 'listening', 'thinking', 'speaking'];
const shapes: (VoiceOrbShape | 'state')[] = ['state', 'network', 'meridians', 'ribbon', 'morph'];

export default function VoiceOrbDemo() {
  const [state, setState] = useState<VoiceState>('listening');
  const [shape, setShape] = useState<VoiceOrbShape | 'state'>('state');
  const [mic, setMic] = useState(false);
  const [level, setLevel] = useState(0);
  // Without the microphone, a made-up voice drives the level.
  useEffect(() => {
    if (mic || (state !== 'listening' && state !== 'speaking')) { if (!mic) setLevel(0); return; }
    let frame = 0;
    const tick = (time: number) => { setLevel(Math.max(0, Math.sin(time / 180) * Math.sin(time / 530)) * 0.9); frame = requestAnimationFrame(tick); };
    frame = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(frame);
  }, [mic, state]);
  return (
    <div style={{ width: '100%', display: 'grid', gap: 28, justifyItems: 'center' }}>
      <VoiceOrb state={state} level={level} size={140} shape={shape === 'state' ? undefined : shape} />
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center', justifyContent: 'center' }}>
        <div style={{ maxWidth: '100%', overflowX: 'auto' }}>
          <MagnetTabs items={states.map(value => ({ value, label: value[0].toUpperCase() + value.slice(1) }))} value={state} onValueChange={value => setState(value as VoiceState)} aria-label="Orb state" />
        </div>
        <DictationButton label="Use my microphone" listening={mic} onListeningChange={on => { setMic(on); if (on) setState('listening'); }} onLevel={setLevel} />
      </div>
      <div style={{ maxWidth: '100%', overflowX: 'auto' }}>
        <MagnetTabs items={shapes.map(value => ({ value, label: value === 'state' ? 'State look' : value[0].toUpperCase() + value.slice(1) }))} value={shape} onValueChange={value => setShape(value as VoiceOrbShape | 'state')} aria-label="Orb shape" />
      </div>
    </div>
  );
}

Installation

pnpm add @brand-studio/ui

Usage

import { VoiceOrb } from '@brand-studio/ui';
<VoiceOrb state="listening" level={level} size={140} />
<VoiceOrb state="thinking" shape="network" />

level runs from 0 to 1. Feed it the microphone's loudness while listening (DictationButton's onLevel gives you this) or the agent's voice while speaking. Idle shows a ring that breathes, listening sends a wave through rows of dots, thinking runs dots round tilted orbits and speaking spreads ripples from the orb's face. Pass shape to swap in another look for every state: network joins dots with lines, meridians weaves dots along vertical lines, ribbon rolls a band of strokes round the sphere and morph re-forms a ring of dots into a circle, a triangle and a square. A shape runs at half speed while idle and swells with level. The dots take the ink colour, so the orb follows light and dark themes. Below 64 px it draws fewer, larger dots.

Accessibility

  • The orb is a status that says its state in words: Ready, Listening, Thinking or Speaking. label shows your own words instead.
  • The drawing is hidden from screen readers.
  • With reduced motion the orb holds still but still follows the level. It also stops drawing when it scrolls off screen.

API Reference

PropTypeDefault
state?"idle" | "listening" | "speaking" | "thinking"'idle'
level?number0
size?number120
shape?"meridians" | "morph" | "network" | "ribbon"–
label?string–
className?string''

Still, Deskhand and Hollis are fictional brands. The coffee photographs are original generated artwork. @brand-studio/ui is MIT licensed.