VoiceRun React Integration

A React library for integrating VoiceRun Agent functionality into your applications. Includes a WebSocket-based client for real-time audio communication and pre-built UI components for agent call interfaces.

Features

• Real-time microphone input capture
• High-quality audio playback
• Audio level monitoring and speech detection
• WebSocket-based communication
• React Context integration
• Pre-built UI components (visualizers, controls, state indicators)

Installation

npm install voicerun-react
# or
yarn add voicerun-react

To use the UI components (AgentPanel, AuraVisualizer, BarVisualizer, etc.), also install the optional peer dependencies:

npm install class-variance-authority clsx tailwind-merge motion lucide-react

Quick Start

import { VoiceRunProvider, useVoiceRun } from 'voicerun-react';

// Configure the provider
const config = {
  agentId: 'your-agent-id',
  environment: 'staging',
  logLevel: 'ERROR'
};

// Wrap your app with the provider
function App() {
  return (
    <VoiceRunProvider config={config} autoConnect={true}>
      <YourComponent />
    </VoiceRunProvider>
  );
}

// Use the hook in your components
function YourComponent() {
  const {
    connect,
    disconnect,
    startListening,
    stopListening,
    sendTextEvent,
    isConnected,
    isListening,
    isPlaying,
    audioStats,
    error
  } = useVoiceRun();

  // Your component logic here
}

API Reference

VoiceRunProvider

The main provider component that sets up the WebSocket client and context.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | config | WebSocketClientConfig | Yes | Configuration for the WebSocket client | | autoConnect | boolean | No | Whether to connect automatically on mount | | children | ReactNode | Yes | Child components |

WebSocketClientConfig

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | agentId | string | Yes | - | Your VoiceRun agent ID | | environment | string | Yes | 'production' | Agent environment to use | | functionId | string | No | 'staged' | Agent function id to use (defaults to functionId of "environment") | | logLevel | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | No | 'ERROR' | Logging level |

useVoiceRun Hook

The hook provides access to all VoiceRun functionality.

Returns

| Property | Type | Description | |----------|------|-------------| | connect | () => void | Connect to the WebSocket server | | disconnect | () => void | Disconnect from the WebSocket server | | startListening | () => Promise | Start capturing audio from microphone | | stopListening | () => void | Stop capturing audio from microphone | | sendTextEvent | (text: string) => void | Send a text message to the server | | isConnected | boolean | Connection status | | isListening | boolean | Microphone capture status | | isPlaying | boolean | Audio playback status | | audioStats | AudioStats | null | Current audio statistics | | error | string | null | Error message if any |

AudioStats Interface

interface AudioStats {
  level: number;        // Audio level (0-1)
  isSpeaking: boolean;  // Speech detection status
  isPlayback?: boolean; // Whether stats are for playback
}

UI Components

Pre-built components for building agent call interfaces. Requires Tailwind CSS and the optional peer dependencies listed above.

AgentPanel

Full call UI with aura visualizer, state indicator, and controls. Drop this inside a VoiceRunProvider for a complete agent call experience.

import { VoiceRunProvider, AgentPanel } from 'voicerun-react';

function CallPage() {
  return (
    <VoiceRunProvider config={config}>
      <AgentPanel color="#1FD5F9" onDisconnect={() => console.log('done')} />
    </VoiceRunProvider>
  );
}

AuraVisualizer

WebGL shader-based aura that responds to agent state and audio levels. Uses an arrow-shaped SDF with animated domain warping.

import { AuraVisualizer, deriveAgentState } from 'voicerun-react';

<AuraVisualizer
  state={deriveAgentState({ isConnected, isListening, isPlaying })}
  audioLevel={audioStats?.level ?? 0}
  size="lg"           // "sm" | "md" | "lg" | "xl"
  shapeScale={2.0}    // multiplier for inner shape size
  color="#1FD5F9"
  themeMode="dark"    // "dark" | "light"
/>

BarVisualizer

Animated bar visualizer driven by agent state and audio levels. Bars form an arrow/play-button silhouette.

import { BarVisualizer, deriveAgentState } from 'voicerun-react';

<BarVisualizer
  state={deriveAgentState({ isConnected, isListening, isPlaying })}
  audioLevel={audioStats?.level ?? 0}
  size="md"           // "sm" | "md" | "lg" | "xl"
  color="#22c55e"
/>

AgentControlBar

Mic toggle, disconnect button, inline visualizer, and status text.

import { AgentControlBar } from 'voicerun-react';

<AgentControlBar
  variant="pill"      // "default" | "outline" | "pill"
  onDisconnect={() => router.push('/')}
/>

AgentStateIndicator

Colored animated pill showing the current agent state.

import { AgentStateIndicator, deriveAgentState } from 'voicerun-react';

<AgentStateIndicator
  state={deriveAgentState({ isConnected, isListening, isPlaying })}
/>

Utilities

import { deriveAgentState, cn } from 'voicerun-react';
import type { AgentState } from 'voicerun-react';

// Derive state from hook values
const state: AgentState = deriveAgentState({ isConnected, isListening, isPlaying });
// Returns: "disconnected" | "connecting" | "listening" | "thinking" | "speaking"

// Tailwind class merging utility
const classes = cn("base-class", condition && "conditional-class");

Technical Details

Audio Processing

• Input audio is captured at the system's native sample rate
• Automatically downsampled to 16kHz for transmission
• Converted to μ-law encoding for efficient transfer
• Real-time audio level monitoring and speech detection
• Supports both microphone input and audio playback

WebSocket Communication

• Bi-directional audio streaming
• Automatic reconnection handling
• Session management with unique call and stream IDs
• Support for text events
• Error handling and status monitoring

Example Usage

function VoiceChat() {
  const {
    connect,
    startListening,
    stopListening,
    isConnected,
    isListening,
    audioStats
  } = useVoiceRun();

  useEffect(() => {
    // Connect on component mount
    connect();
    return () => disconnect();
  }, []);

  return (
    <div>
      <button
        onClick={() => isListening ? stopListening() : startListening()}
      >
        {isListening ? 'Stop' : 'Start'} Listening
      </button>

      {audioStats && (
        <div>
          Audio Level: {audioStats.level}
          Speaking: {audioStats.isSpeaking ? 'Yes' : 'No'}
        </div>
      )}
    </div>
  );
}

Publishing

To publish a clean build to npm:

npm run publish:clean

This removes node_modules and package-lock.json, does a fresh npm install, builds the package, and publishes with public access. This ensures the published package is built from a clean dependency tree.

Best Practices

1. Always wrap your application or the relevant component tree with VoiceRunProvider
2. Handle connection errors appropriately
3. Clean up resources by calling disconnect when done
4. Monitor audioStats for audio level visualization
5. Use isConnected status to show connection state
6. Handle microphone permissions appropriately

Browser Support

• Chrome 74+
• Firefox 75+
• Safari 14.1+
• Edge 79+

Requires browser support for:

• WebSocket API
• Web Audio API
• MediaDevices API
• AudioWorklet (with fallback to ScriptProcessorNode)
• WebGL (for AuraVisualizer)

License

MIT License