Install the Agora voice ring with shadcn

Use this path when you want the Agora voice UI in a Vercel or React app, but you do not need the full agent template.

The registry installs a circular dual-channel voice button plus the Web Audio meter hook. If you want the full Agora realtime runtime, use the agora-realtime-react npm package instead.

What gets installed

The registry item installs two files into the consumer's shadcn aliases:

@ui/voice-ring-button.tsx
@hooks/use-voice-meter.ts

The source of truth in this repository remains:

packages/agora-realtime-react/src/components/voice-ring-button.tsx
packages/agora-realtime-react/src/use-voice-meter.ts

The registry endpoint reads those SDK source files and emits a shadcn registry item at request time.

Requirements

• A React app with shadcn initialized. The normal npm path is:

npx create-next-app@latest my-agora-agent \
  --ts --tailwind --eslint --app --src-dir --import-alias '@/*' \
  --use-npm
cd my-agora-agent
npx shadcn@latest init -d

• The project must have working shadcn aliases for @ui and @hooks; the registry writes files through those aliases.
• The component is UI-only. Use agora-realtime-react and your own server route when you need a live Agora agent session.
• For local Next.js development, open the app through http://localhost:<port>. Using 127.0.0.1 can trigger Next.js dev-origin restrictions unless allowedDevOrigins is configured.
• Microphone previews require HTTPS in production, or http://localhost locally.

Install from the hosted registry

Install the component from the Vercel-hosted registry:

npx shadcn@latest add https://agora-realtime-agent.vercel.app/r/voice-ring-button.json

After the shadcn registry directory accepts the @agora-voice-agents namespace, the short install form will be:

npx shadcn@latest add @agora-voice-agents/voice-ring-button

For local testing:

npm run dev:website
npx shadcn@latest add http://localhost:3001/r/voice-ring-button.json

Rendered preview

The preview above renders the actual component. It uses the microphone as the human input, does not start an agent session, and does not sample agent output. The AI ring is intentionally disabled by passing aiLevels={null}.

Component design

VoiceRingButton is a visual primitive, not an agent runtime. It draws two waveform rings on canvas:

• humanLevels drives the inward warm ring for local microphone activity.
• aiLevels drives the outward cool ring for agent activity. Pass null when there is no agent output.
• state controls the button mood: disconnected, connecting, listening, thinking, or interrupted.
• onClick stays app-owned, so the same component can start a microphone session, play an audio sample, or trigger a custom workflow.

useVoiceMeter is the Web Audio helper that converts a MediaStream into normalized bar levels. The preview above gets that stream from navigator.mediaDevices.getUserMedia(). In a full Agora agent app, you can pass remote RTC audio levels as aiLevels; for a UI-only preview, keep aiLevels as null.

Registry shape

The Vercel website serves:

• GET /r/registry.json for catalog discovery.
• GET /r/voice-ring-button.json for shadcn add.

The source registry manifest is registry/default/voice-ring-button/registry.json. It uses the current shadcn registry item model with target placeholders:

{
  "target": "@ui/voice-ring-button.tsx"
}

and:

{
  "target": "@hooks/use-voice-meter.ts"
}

References

• Agora: https://www.agora.io/en/
• Agora Docs (English): https://docs.agora.io/en/
• Agora realtime voice docs: https://docs.agora.io/en/realtime-media/voice
• shadcn registry guide: https://ui.shadcn.com/docs/registry/getting-started
• shadcn registry item schema: https://ui.shadcn.com/docs/registry/registry-item-json