realtime-voice-ai

🎙️ React Voice Chat Assistant

A powerful, fully configurable React component that provides instant voice chat functionality powered by OpenAI's Realtime API. Instead of building voice chat from scratch, simply import and configure this component to add natural, human-like voice conversations to your application.

🚀 Why Choose This Package?

• 🎯 Instant Integration: Add voice chat to your app in minutes, not days
• 🔧 Fully Configurable: Customize every aspect of the voice chat experience
• 🎭 Natural Conversations: Built-in emotional expressions and human-like speech patterns
• 🎨 Multiple UI Variants: Choose from 4 pre-built UI designs or create your own
• ⚡ Real-time Communication: Powered by OpenAI's latest Realtime API
• 🛡️ Production Ready: Comprehensive error handling and fallback mechanisms

📦 Installation

npm install realtime-voice-ai

yarn add realtime-voice-ai

🎬 Quick Start

import React from 'react';
import { VoiceChatTrigger } from 'realtime-voice-ai';

function App() {
  const config = {
    instructions: "You are a helpful assistant that speaks naturally with emotions.",
    voice: 'verse',
    temperature: 0.8
  };

  return (
    <VoiceChatTrigger
      name="John"
      botType="rvc"
      uiVersion="v2"
      apikey="your-openai-api-key"
      config={config}
    />
  );
}

📚 Complete API Reference

Component Props

Prop	Type	Required	Default	Description
name	string	No	undefined	User's name for personalized greetings and responses
botType	string	Yes	-	Type of voice chat: 'rvc' (RealTimeVoiceChat) or 'va' (VoiceAssistant)
uiVersion	string	No	'v1'	UI variant: 'v1', 'v2', 'v3', 'v4', or 'custom'
customUI	object	No	undefined	Custom UI configuration when uiVersion='custom'
apikey	string	Yes	-	Your OpenAI API key
isDisabled	boolean	No	false	Whether the voice chat is disabled
config	object	No	{}	Session configuration object (see below)

Configuration Object (config)

Model & Basic Settings

Property	Type	Default	Allowed Values	Description
model	string	'gpt-4o-realtime-preview-2024-12-17'	'gpt-4o-realtime-preview-2024-12-17'	OpenAI Realtime model
modalities	array	['audio', 'text']	['audio'], ['text'], ['audio', 'text']	Supported interaction modes
instructions	string	Natural conversation prompt	Any string	AI personality and behavior instructions

Voice & Response Settings

Property	Type	Default	Allowed Values	Description
voice	string	'alloy'	'alloy', 'ash', 'ballad', 'coral', 'echo', 'sage', 'shimmer', 'verse'	Voice personality
temperature	number	0.8	0.6 - 1.2	Response creativity and randomness
max_response_output_tokens	string|number	'inf'	'inf' or 1 - 4096	Maximum response length

Audio Configuration

Property	Type	Default	Allowed Values	Description
input_audio_format	string	'pcm16'	'pcm16', 'g711_ulaw', 'g711_alaw'	Input audio format
output_audio_format	string	'pcm16'	'pcm16', 'g711_ulaw', 'g711_alaw'	Output audio format
input_audio_transcription	object	{ model: 'whisper-1' }	{ model: 'whisper-1' }	Transcription settings

Turn Detection Settings

Property	Type	Default	Range/Values	Description
turn_detection.type	string	'server_vad'	'server_vad', 'none'	Voice activity detection type
turn_detection.threshold	number	0.5	0.0 - 1.0	Voice detection sensitivity
turn_detection.prefix_padding_ms	number	200	0 - 5000	Audio padding before speech (ms)
turn_detection.silence_duration_ms	number	400	0 - 20000	Silence duration to trigger response (ms)
turn_detection.create_response	boolean	true	true, false	Auto-generate responses

🎨 UI Versions

Choose from multiple pre-built UI designs:

v1 - Classic Animated Blob

Classic animated blob with pulse effects

v2 - Modern Gradient Blob

Modern gradient blob with smooth animations

v3 - Geometric Animated Shapes

Geometric animated shapes with color transitions

v4 - Advanced Particle System

Advanced particle system with dynamic effects

v5 - Advanced Wave Particle System

Advanced particle system with dynamic effects

This one is the best in my opionion 😁

custom - Your Own Design

Use your own UI component by passing it to the customUI prop

🎵 Voice Personalities

Voice	Characteristics	Best For
alloy	Neutral, balanced	General purpose, professional
ash	Smooth, sophisticated	Business presentations, formal conversations
ballad	Melodic, expressive	Storytelling, creative content
coral	Warm, friendly	Customer service, casual conversations
echo	Clear, crisp	Technical support, education
sage	Wise, calm	Healthcare, therapy, guidance
shimmer	Soft, gentle	Children's content, soothing interactions
verse	Rhythmic, engaging	Entertainment, dynamic conversations

📖 Usage Examples

Basic Configuration

import { VoiceChatTrigger } from 'realtime-voice-ai';

const BasicExample = () => {
  const basicConfig = {
    instructions: "You are a helpful customer service representative.",
    voice: "coral",
    temperature: 0.7
  };

  return (
    <VoiceChatTrigger
      name="Sarah"
      botType="rvc"
      uiVersion="v2"
      apikey={process.env.REACT_APP_OPENAI_API_KEY}
      config={basicConfig}
    />
  );
};

Advanced Configuration

const AdvancedExample = () => {
  const advancedConfig = {
    model: 'gpt-4o-realtime-preview-2024-12-17',
    modalities: ['audio', 'text'],
    instructions: `You are an enthusiastic fitness coach. Use natural expressions like "Oh wow!", "That's amazing!", and "Let's go!" to motivate users. Be encouraging and energetic.`,
    voice: 'nova',
    temperature: 0.9,
    max_response_output_tokens: 2048,
    turn_detection: {
      type: 'server_vad',
      threshold: 0.6,
      prefix_padding_ms: 300,
      silence_duration_ms: 500,
      create_response: true
    }
  };

  return (
    <VoiceChatTrigger
      name="Alex"
      botType="rvc"
      uiVersion="v4"
      apikey={process.env.REACT_APP_OPENAI_API_KEY}
      config={advancedConfig}
    />
  );
};

🔧 Environment Variables

For security, store your API key in environment variables:

# .env
REACT_APP_OPENAI_API_KEY=your_openai_api_key_here

// Use in your component
apikey={import.meta.env.REACT_APP_OPENAI_API_KEY}

🎯 Turn Detection Tuning Guide

Fine-tune when the AI responds by adjusting these parameters:

Sensitivity Settings

• High Sensitivity (threshold: 0.2-0.4): Responds to quieter speech, may pick up background noise
• Medium Sensitivity (threshold: 0.4-0.6): Balanced detection, good for most environments
• Low Sensitivity (threshold: 0.6-0.8): Requires clearer speech, filters out background noise

Response Timing

• Fast Response (silence_duration_ms: 200-400): Quick interactions, may interrupt user
• Normal Response (silence_duration_ms: 400-600): Standard conversation timing
• Thoughtful Response (silence_duration_ms: 600-1000): Allows for pauses, better for complex topics

🚨 Troubleshooting

Common Issues

Issue	Solution
No audio playback	Check browser microphone permissions
Voice cuts out	Adjust threshold value (try 0.6-0.7)
AI interrupts user	Increase silence_duration_ms (try 600-800)
Delayed responses	Decrease silence_duration_ms (try 300-400)
Connection fails	Verify OpenAI API key and internet connection

Browser Compatibility

• ✅ Chrome 88+
• ✅ Firefox 84+
• ✅ Safari 14.1+
• ✅ Edge 88+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions:

• 🐛 Open an issue on our GitHub repository
• 📧 Contact directly: [e-mail]

Made with ❤️ for developers who want to add natural voice conversations to their applications.