SDK

React Native SDK

Official React Native client library for Nur's Voice AI platform. Build native iOS and Android voice apps with React.

GitHub npm

Installation

Requires React Native 0.70+ and React 18+. Install via npm or yarn:

1npm install @nur/react-native

For iOS, run pod install:

1cd ios && pod install && cd ..

Quick Start

Create a client and generate your first speech with hooks:

import React from 'react';
import { View, Button, Text } from 'react-native';
import { NurProvider, useNur } from '@nur/react-native';
function VoiceApp() {
  const { tts } = useNur();
  const [status, setStatus] = React.useState('');
  const generateSpeech = async () => {
    try {
      setStatus('Generating...');
      // Generate speech from text
      const audio = await tts.generate({
        text: 'Hello from React Native! This is Nur\'s voice AI.',
        voiceId: 'rachel_v2',
        language: 'en',
      });
      // Audio plays automatically on mobile
      setStatus(`Generated ${audio.duration.toFixed(2)}s of audio`);
    } catch (error) {
      setStatus(`Error: ${error.message}`);
    }
  };
  return (
    <View style={{ padding: 20 }}>
      <Button title="Generate Speech" onPress={generateSpeech} />
      <Text>{status}</Text>
    </View>
  );
}
export default function App() {
  return (
    <NurProvider apiKey="nur_your_api_key_here">
      <VoiceApp />
    </NurProvider>
  );
}

Authentication

Configure your API key via the NurProvider or environment variables:

import { NurProvider, NurClient } from '@nur/react-native';
// Option 1: Using NurProvider (recommended for React components)
export default function App() {
  return (
    <NurProvider
      apiKey="nur_your_api_key_here"
      config={{
        baseUrl: 'https://api.nur.ai',
        timeout: 60000,
        maxRetries: 3,
      }}
    >
      <YourApp />
    </NurProvider>
  );
}
// Option 2: Direct client instantiation
const client = new NurClient({
  apiKey: 'nur_your_api_key_here',
  baseUrl: 'https://api.nur.ai',
  timeout: 60000,
  maxRetries: 3,
});
// Option 3: Using environment variables (.env)
// NUR_API_KEY=nur_your_api_key_here
const client = new NurClient(); // Reads from env

Text to Speech

Generate natural-sounding speech with React hooks and native audio:

import React from 'react';
import { View, TextInput, Button, ActivityIndicator } from 'react-native';
import { useNur } from '@nur/react-native';
function TTSComponent() {
  const { tts } = useNur();
  const [text, setText] = React.useState('');
  const [loading, setLoading] = React.useState(false);
  // Basic generation
  const generateBasic = async () => {
    setLoading(true);
    try {
      const audio = await tts.generate({
        text,
        voiceId: 'rachel_v2',
      });
      // Audio plays automatically
    } finally {
      setLoading(false);
    }
  };
  // With advanced options
  const generateAdvanced = async () => {
    const audio = await tts.generate({
      text,
      voiceId: 'rachel_v2',
      language: 'en',
      speed: 1.0,
      pitch: 1.0,
      outputFormat: 'mp3',
      sampleRate: 24000,
      enableSSML: true,
    });
  };
  // Streaming generation
  const streamAudio = async () => {
    const stream = tts.stream({
      text: 'Streaming long-form content...',
      voiceId: 'rachel_v2',
    });
    for await (const chunk of stream) {
      console.log(`Received ${chunk.length} bytes`);
      // Chunks play automatically as they arrive
    }
  };
  return (
    <View style={{ padding: 20 }}>
      <TextInput
        value={text}
        onChangeText={setText}
        placeholder="Enter text to speak..."
        multiline
        style={{
          borderWidth: 1,
          padding: 10,
          marginBottom: 10,
          minHeight: 100
        }}
      />
      <Button
        title={loading ? 'Generating...' : 'Generate Speech'}
        onPress={generateBasic}
        disabled={loading || !text}
      />
      {loading && <ActivityIndicator style={{ marginTop: 10 }} />}
    </View>
  );
}
// Using hooks for audio control
import { useAudio } from '@nur/react-native';
function AudioPlayer() {
  const { play, pause, stop, isPlaying } = useAudio();
  const handleGenerate = async () => {
    const audio = await tts.generate({
      text: 'Hello world',
      voiceId: 'rachel_v2',
      autoPlay: false, // Don't play automatically
    });
    // Manual control
    await play(audio);
  };
  return (
    <View>
      <Button title={isPlaying ? 'Pause' : 'Play'}
              onPress={isPlaying ? pause : handleGenerate} />
      <Button title="Stop" onPress={stop} />
    </View>
  );
}

Speech to Text

High-accuracy transcription with microphone hooks:

import React from 'react';
import { View, Button, Text, PermissionsAndroid, Platform } from 'react-native';
import { useNur, useMicrophone } from '@nur/react-native';
function STTComponent() {
  const { stt } = useNur();
  const [transcript, setTranscript] = React.useState('');
  // Request microphone permission
  const requestPermission = async () => {
    if (Platform.OS === 'android') {
      await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.RECORD_AUDIO
      );
    }
  };
  React.useEffect(() => {
    requestPermission();
  }, []);
  // Real-time transcription with microphone hook
  const {
    startRecording,
    stopRecording,
    isRecording,
    transcript: liveTranscript,
  } = useMicrophone({
    language: 'en',
    timestamps: true,
    onResult: (result) => {
      if (result.isFinal) {
        setTranscript((prev) => prev + ' ' + result.text);
      }
    },
  });
  // File transcription
  const transcribeFile = async () => {
    const result = await stt.transcribe({
      file: 'path/to/audio.mp3',
      language: 'en',
      speakerDiarization: true,
      timestamps: true,
    });
    console.log(result.text);
    // Access segments
    result.segments.forEach((segment) => {
      console.log(`[Speaker ${segment.speaker}] ${segment.text}`);
      console.log(`  Time: ${segment.start}s - ${segment.end}s`);
    });
  };
  return (
    <View style={{ padding: 20 }}>
      <Button
        title={isRecording ? 'Stop Recording' : 'Start Recording'}
        onPress={isRecording ? stopRecording : startRecording}
        color={isRecording ? 'red' : 'blue'}
      />
      <Text style={{ marginTop: 20, fontSize: 16 }}>
        Live: {liveTranscript}
      </Text>
      <Text style={{ marginTop: 10, fontSize: 14, color: '#666' }}>
        Final: {transcript}
      </Text>
      <Button
        title="Transcribe File"
        onPress={transcribeFile}
        style={{ marginTop: 20 }}
      />
    </View>
  );
}

Voice Agents

Build real-time conversational AI with React hooks:

import React from 'react';
import { View, Button, FlatList, Text } from 'react-native';
import { useVoiceAgent } from '@nur/react-native';
function VoiceAgentComponent() {
  const [messages, setMessages] = React.useState([]);
  const {
    startSession,
    endSession,
    isActive,
    isSpeaking,
  } = useVoiceAgent({
    voiceId: 'rachel_v2',
    language: 'en',
    systemPrompt: 'You are a helpful assistant.',
    temperature: 0.7,
    maxTokens: 150,
    onTranscript: (text) => {
      setMessages((prev) => [...prev, { role: 'user', text }]);
    },
    onAgentResponse: (text) => {
      setMessages((prev) => [...prev, { role: 'agent', text }]);
    },
    onError: (error) => {
      console.error('Voice agent error:', error);
    },
  });
  return (
    <View style={{ flex: 1, padding: 20 }}>
      <FlatList
        data={messages}
        keyExtractor={(item, index) => index.toString()}
        renderItem={({ item }) => (
          <View
            style={{
              padding: 10,
              marginVertical: 5,
              backgroundColor: item.role === 'user' ? '#E3F2FD' : '#F1F8E9',
              borderRadius: 8,
            }}
          >
            <Text style={{ fontWeight: 'bold' }}>
              {item.role === 'user' ? 'You' : 'Agent'}
            </Text>
            <Text>{item.text}</Text>
          </View>
        )}
      />
      <View style={{ marginTop: 20 }}>
        <Button
          title={isActive ? 'End Conversation' : 'Start Conversation'}
          onPress={isActive ? endSession : startSession}
          color={isActive ? 'red' : 'green'}
        />
        {isSpeaking && (
          <Text style={{ textAlign: 'center', marginTop: 10 }}>
            Agent is speaking...
          </Text>
        )}
      </View>
    </View>
  );
}
// Advanced usage with manual control
function AdvancedVoiceAgent() {
  const { voiceAgent } = useNur();
  const [session, setSession] = React.useState(null);
  const createSession = async () => {
    const newSession = await voiceAgent.createSession({
      voiceId: 'rachel_v2',
      systemPrompt: 'You are a helpful assistant.',
    });
    setSession(newSession);
    // Handle responses
    for await (const response of newSession.receive()) {
      switch (response.type) {
        case 'transcript':
          console.log('User:', response.transcript.text);
          break;
        case 'agentText':
          console.log('Agent:', response.agentText);
          break;
        case 'audio':
          // Audio plays automatically
          break;
      }
    }
  };
  return (
    <View>
      <Button
        title="Create Session"
        onPress={createSession}
      />
    </View>
  );
}

Configuration Options

All available client configuration options:

Option	Type	Default	Description
apiKey	string	NUR_API_KEY	Your API key
baseUrl	string	https://api.nur.ai	API base URL
timeout	number	30000	Request timeout (ms)
maxRetries	number	3	Maximum retry attempts
retryDelay	number	1000	Delay between retries (ms)
autoPlay	boolean	true	Auto-play generated audio

Error Handling

The SDK provides typed errors and error boundaries:

import {
  NurError,
  RateLimitError,
  AuthenticationError,
  NurErrorBoundary
} from '@nur/react-native';
// Try-catch error handling
async function generateSpeech() {
  try {
    const audio = await tts.generate({
      text: 'Hello world',
      voiceId: 'rachel_v2',
    });
  } catch (error) {
    if (error instanceof RateLimitError) {
      console.log(`Rate limited. Retry after ${error.retryAfter}s`);
      setTimeout(() => {
        // Retry request...
      }, error.retryAfter * 1000);
    } else if (error instanceof AuthenticationError) {
      console.error('Authentication failed: check your API key');
    } else if (error instanceof NurError) {
      console.error(`API error [${error.statusCode}]: ${error.message}`);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}
// Using error boundary
function App() {
  return (
    <NurErrorBoundary
      fallback={(error) => (
        <View style={{ padding: 20 }}>
          <Text style={{ color: 'red' }}>Error: {error.message}</Text>
          <Button title="Retry" onPress={() => window.location.reload()} />
        </View>
      )}
    >
      <YourApp />
    </NurErrorBoundary>
  );
}
// Hook-based error handling
import { useError } from '@nur/react-native';
function Component() {
  const { error, clearError } = useError();
  if (error) {
    return (
      <View>
        <Text>Error: {error.message}</Text>
        <Button title="Dismiss" onPress={clearError} />
      </View>
    );
  }
  return <YourComponent />;
}