SDK

Flutter SDK

Official Flutter/Dart client library for Nur's Voice AI platform. Build cross-platform voice apps for iOS, Android, and Web.

GitHub pub.dev

Installation

Requires Flutter 3.0+ and Dart 3.0+. Add to your pubspec.yaml:

dependencies:
  nur_ai: ^0.1.0

Quick Start

Create a client and generate your first speech with async/await:

import 'package:nur_ai/nur_ai.dart';
void main() async {
  // Initialize client (uses NUR_API_KEY env var)
  final client = NurClient();
  try {
    // Generate speech from text
    final audio = await client.tts.generate(
      text: 'Hello from Flutter! This is Nur\'s voice AI.',
      voiceId: 'rachel_v2',
      language: 'en',
    );
    // Save to file
    await audio.save('output.mp3');
    print('Generated ${audio.duration.toStringAsFixed(2)}s of audio');
  } catch (e) {
    print('Error: $e');
  }
}

Authentication

Configure your API key during client initialization:

import 'package:nur_ai/nur_ai.dart';
// Option 1: Use environment variable
final client = NurClient();
// Option 2: Explicit API key
final client = NurClient(apiKey: 'nur_your_api_key_here');
// Option 3: Custom configuration
final config = NurClientConfig(
  apiKey: 'nur_your_api_key_here',
  baseUrl: 'https://api.nur.ai',
  timeout: Duration(seconds: 60),
  maxRetries: 3,
);
final client = NurClient.withConfig(config);

Text to Speech

Generate natural-sounding speech with Flutter's audio players:

import 'package:nur_ai/nur_ai.dart';
import 'package:audioplayers/audioplayers.dart';
// Basic generation
final audio = await client.tts.generate(
  text: 'Converting text to natural speech.',
  voiceId: 'rachel_v2',
);
// With advanced options
final audio = await client.tts.generate(
  text: 'Converting text to natural speech.',
  voiceId: 'rachel_v2',
  language: 'en',
  speed: 1.0,
  pitch: 1.0,
  outputFormat: OutputFormat.mp3,
  sampleRate: 24000,
  enableSSML: true,
);
// Save audio
await audio.save('output.mp3');
// Get audio bytes
final bytes = audio.bytes;
// Play audio directly
final player = AudioPlayer();
await player.play(BytesSource(audio.bytes));
// Streaming generation
await for (final chunk in client.tts.stream(
  text: 'Streaming long-form content...',
  voiceId: 'rachel_v2',
)) {
  print('Received ${chunk.length} bytes');
  // Process or play chunk in real-time
}
// Widget integration
class TTSWidget extends StatefulWidget {
  @override
  _TTSWidgetState createState() => _TTSWidgetState();
}
class _TTSWidgetState extends State<TTSWidget> {
  final client = NurClient();
  bool isLoading = false;
  Future<void> generateSpeech(String text) async {
    setState(() => isLoading = true);
    try {
      final audio = await client.tts.generate(
        text: text,
        voiceId: 'rachel_v2',
      );
      final player = AudioPlayer();
      await player.play(BytesSource(audio.bytes));
    } finally {
      setState(() => isLoading = false);
    }
  }
  @override
  Widget build(BuildContext context) {
    // Your UI here
  }
}

Speech to Text

High-accuracy transcription with microphone integration:

import 'package:nur_ai/nur_ai.dart';
import 'dart:io';
// Basic transcription from file
final transcript = await client.stt.transcribe(
  file: File('audio.mp3'),
);
print(transcript.text);
// With speaker diarization and timestamps
final transcript = await client.stt.transcribe(
  file: File('meeting.mp3'),
  language: 'en',
  speakerDiarization: true,
  timestamps: true,
  punctuationEnabled: true,
  filterProfanity: true,
);
// Access segments with speaker info
for (final segment in transcript.segments) {
  print('[Speaker ${segment.speaker}] ${segment.text}');
  print('  Time: ${segment.start}s - ${segment.end}s');
}
// Real-time streaming transcription
final stream = await client.stt.streamTranscribe(
  language: 'en',
  timestamps: true,
);
// Send audio chunks from microphone
// (Using record package for microphone access)
import 'package:record/record.dart';
final recorder = Record();
await recorder.start();
// Stream audio data
recorder.onStateChanged().listen((state) async {
  if (state == RecordState.record) {
    final audioData = await recorder.getAudioData();
    await stream.send(audioData);
  }
});
// Receive transcripts
await for (final result in stream.receive()) {
  print('Transcription: ${result.text} (final: ${result.isFinal})');
}
// Widget integration
class STTWidget extends StatefulWidget {
  @override
  _STTWidgetState createState() => _STTWidgetState();
}
class _STTWidgetState extends State<STTWidget> {
  final client = NurClient();
  final recorder = Record();
  String transcription = '';
  Future<void> startRecording() async {
    final stream = await client.stt.streamTranscribe();
    await recorder.start();
    await for (final result in stream.receive()) {
      setState(() {
        transcription = result.text;
      });
    }
  }
  @override
  Widget build(BuildContext context) {
    // Your UI here
  }
}

Voice Agents

Build real-time conversational AI with Flutter widgets:

import 'package:nur_ai/nur_ai.dart';
// Create a voice agent session
final session = await client.voiceAgent.createSession(
  voiceId: 'rachel_v2',
  language: 'en',
  systemPrompt: 'You are a helpful assistant.',
  temperature: 0.7,
  maxTokens: 150,
);
// Setup microphone recording
final recorder = Record();
await recorder.start();
// Send audio from microphone
recorder.onStateChanged().listen((state) async {
  if (state == RecordState.record) {
    final audioData = await recorder.getAudioData();
    await session.sendAudio(audioData);
  }
});
// Receive agent responses
await for (final response in session.receive()) {
  switch (response.type) {
    case ResponseType.transcript:
      print('User: ${response.transcript.text}');
      break;
    case ResponseType.agentText:
      print('Agent: ${response.agentText}');
      break;
    case ResponseType.audio:
      // Play audio chunk
      final player = AudioPlayer();
      await player.play(BytesSource(response.audio));
      break;
  }
}
// Complete voice agent widget
class VoiceAgentWidget extends StatefulWidget {
  @override
  _VoiceAgentWidgetState createState() => _VoiceAgentWidgetState();
}
class _VoiceAgentWidgetState extends State<VoiceAgentWidget> {
  final client = NurClient();
  final recorder = Record();
  final player = AudioPlayer();
  VoiceAgentSession? session;
  List<String> messages = [];
  bool isActive = false;
  Future<void> startConversation() async {
    setState(() => isActive = true);
    session = await client.voiceAgent.createSession(
      voiceId: 'rachel_v2',
      systemPrompt: 'You are a helpful assistant.',
    );
    // Start recording
    await recorder.start();
    // Handle responses
    await for (final response in session!.receive()) {
      if (response.type == ResponseType.agentText) {
        setState(() {
          messages.add('Agent: ${response.agentText}');
        });
      } else if (response.type == ResponseType.audio) {
        await player.play(BytesSource(response.audio));
      }
    }
  }
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Expanded(
          child: ListView.builder(
            itemCount: messages.length,
            itemBuilder: (context, index) {
              return ListTile(title: Text(messages[index]));
            },
          ),
        ),
        ElevatedButton(
          onPressed: isActive ? null : startConversation,
          child: Text(isActive ? 'Active' : 'Start'),
        ),
      ],
    );
  }
}

Configuration Options

All available client configuration options:

Property	Type	Default	Description
apiKey	String	NUR_API_KEY	Your API key
baseUrl	String	https://api.nur.ai	API base URL
timeout	Duration	30s	Request timeout
maxRetries	int	3	Maximum retry attempts
retryDelay	Duration	1s	Delay between retries
httpClient	http.Client	Default	Custom HTTP client

Error Handling

The SDK provides typed exceptions with proper error handling:

import 'package:nur_ai/nur_ai.dart';
try {
  final audio = await client.tts.generate(
    text: 'Hello world',
    voiceId: 'rachel_v2',
  );
} on RateLimitException catch (e) {
  print('Rate limited. Retry after ${e.retryAfter} seconds');
  await Future.delayed(Duration(seconds: e.retryAfter));
  // Retry request...
} on AuthenticationException {
  print('Authentication failed: check your API key');
} on NurApiException catch (e) {
  print('API error [${e.statusCode}]: ${e.message}');
} on TimeoutException {
  print('Request timed out');
} catch (e) {
  print('Unexpected error: $e');
}
// Using timeout with Future
try {
  final audio = await client.tts.generate(
    text: 'Long text...',
    voiceId: 'rachel_v2',
  ).timeout(Duration(seconds: 10));
} on TimeoutException {
  print('Request timed out after 10 seconds');
}