unotelos-rn-voice-sdk

A React Native SDK for real-time AI voice conversations with Ultravox integration.

Features

• 🎤 Real-time voice conversations with AI assistants
• 📱 Cross-platform support (iOS & Android)
• 🎛️ Audio controls (mute/unmute)
• 📡 Session management
• 🌍 Multi-language support (English, Pidgin, Igbo, Hausa, Yoruba)
• 🔧 Built with Kotlin for Android and Objective-C for iOS
• ⚛️ TypeScript support

Installation

npm install unotelos-rn-voice-sdk

iOS Setup

The iOS native module compiles the Ultravox SDK and all its Swift dependencies (LiveKit, SwiftProtobuf, Logging) from source. This means it works with any Xcode version — no Swift compiler version mismatches. Only LiveKitWebRTC.xcframework (a C++/ObjC binary) is vendored as a pre-built framework.

Requirements:

• iOS 13.4+
• Xcode with Swift 5.9+
• CocoaPods

Steps:

1. Install pods:

cd ios && pod install

2. Add microphone permissions to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice conversations</string>

3. Open the .xcworkspace (not .xcodeproj) and build.

Troubleshooting:

• Module not found errors: Run pod deintegrate && pod install to do a clean install.
• Slow first build: The first build compiles ~270 Swift source files from the vendored dependencies. Subsequent builds use Xcode's incremental compilation cache.

Android Setup

1. Add microphone permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

2. The native module will be automatically linked via React Native auto-linking.

Usage

Basic Example

import { VoiceSDK, VoiceSessionState } from 'unotelos-rn-voice-sdk';

// Initialize the SDK
const sdk = VoiceSDK.getInstance({
  baseUrl: 'https://your-backend-url.com/v1/api', // Optional: defaults to https://voice.scalercm.ai
  debug: __DEV__,
});

// Set up event listeners
sdk.setEventCallbacks({
  onStateChange: (state) => {
    console.log('Session state changed:', state);
  },
  onAudioStateChange: (audioState) => {
    console.log('Audio state changed:', audioState);
  },
  onError: (error) => {
    console.error('SDK Error:', error);
  },
});

// Start a voice session
await sdk.startSession({
  customerId: 'customer-123',
  customerName: 'John Doe',
  // ... other config
});

// Audio controls
await sdk.mute();
await sdk.unmute();

// End session
await sdk.endSession();

Using the VoiceSupportComponent

import React from 'react';
import { VoiceSupportComponent } from '@unotelos/rn-voice-sdk';

export default function App() {
  return (
    <VoiceSupportComponent
      customerData={{
        id: 'customer-123',
        name: 'John Doe',
        phone: '+1234567890',
        accountType: 'premium',
      }}
      backendUrl="https://your-backend-url.com"
      debug={__DEV__}
    />
  );
}

API Reference

VoiceSDK

Methods

• getInstance(config: VoiceSDKConfig): VoiceSDK - Get singleton instance
• setEventCallbacks(callbacks: VoiceSessionEvents): void - Set event callbacks
• startSession(config: VoiceSessionConfig): Promise<void> - Start voice session
• endSession(): Promise<void> - End current session
• mute(): Promise<void> - Mute microphone
• unmute(): Promise<void> - Unmute microphone
• getSessionState(): VoiceSessionState - Get current session state
• getAudioState(): AudioState - Get current audio state

Types

interface VoiceSDKConfig {
  backendUrl: string;
  debug?: boolean;
}

interface VoiceSessionConfig {
  customerId: string;
  customerName: string;
  customerPhone?: string;
  accountType?: string;
  metadata?: Record<string, any>;
}

enum VoiceSessionState {
  IDLE = 'idle',
  INITIALIZING = 'initializing',
  CONNECTED = 'connected',
  ENDING = 'ending',
  ERROR = 'error',
}

enum AudioState {
  MUTED = 'muted',
  UNMUTED = 'unmuted',
}

Development

Ultravox Integration

The Ultravox SDK and its Swift dependencies (LiveKit, SwiftProtobuf, swift-log) are vendored as source code in ios/Vendor/. Only LiveKitWebRTC.xcframework (C++/ObjC) is a pre-built binary in ios/Frameworks/. Everything Swift compiles from source on the consumer's machine, eliminating cross-Xcode-version compatibility issues.

For Android, the Ultravox SDK is resolved via Gradle from the native module's dependencies.

Building the SDK

npm run clean
npm run prepare

Linting

npm run lint

Type Checking

npm run typecheck

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT © Unotelos