Hasab AI Flutter SDK

A comprehensive Flutter SDK for Hasab AI - providing speech-to-text, text-to-speech, translation, and chat capabilities for Ethiopian languages.

🌟 Features

• Speech-to-Text: Convert voice recordings to text with support for Amharic, Oromo, Tigrinya, and English
• Text-to-Speech: Generate natural-sounding speech from text in multiple Ethiopian languages
• Translation: Translate between supported languages with high accuracy
• Chat: Interact with Hasab AI's conversational AI
• Prebuilt Widgets: Ready-to-use Flutter widgets for common tasks
• Streaming Support: Real-time transcription and chat responses (where supported)
• Null-Safe: Fully null-safe Dart code

🚀 Supported Languages

• 🇪🇹 Amharic (አማርኛ)
• 🇪🇹 Oromo (Oromoo)
• 🇪🇹 Tigrinya (ትግርኛ)
• 🇬🇧 English

📦 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  hasab_ai_flutter: ^1.0.0

Then run:

flutter pub get

🔑 Getting Started

1. Get Your API Key

Sign up at hasab.co to get your API key.

2. Environment Setup (Recommended)

For security, we recommend using environment variables instead of hardcoding API keys:

1. Copy .env.example to .env:

   cp .env.example .env

2. Edit .env and add your API key:

   HASAB_API_KEY=your_actual_api_key_here

3. Initialize the SDK using environment variables:

   import 'package:hasab_ai_flutter/hasab_ai_flutter.dart';
   
   // Initialize using environment variables (recommended)
   final hasab = HasabAI.fromEnvironment();

3. Direct Initialization (Alternative)

You can also initialize directly with your API key:

import 'package:hasab_ai_flutter/hasab_ai_flutter.dart';

// Initialize with API key directly
final hasab = HasabAI(apiKey: 'your-api-key-here');

3. Start Using!

// Speech to Text
final audioFile = File('path/to/audio.mp3');
final transcription = await hasab.speechToText.transcribe(audioFile);
print('Transcribed: ${transcription.text}');

// Text to Speech
final audio = await hasab.textToSpeech.synthesize(
  'ሰላም ፤ እንደምን ነህ?',
  HasabLanguage.amharic,
);
print('Audio saved at: ${audio.audioFilePath}');

// Translation
final translation = await hasab.translation.translate(
  'Hello, how are you?',
  HasabLanguage.english,
  HasabLanguage.amharic,
);
print('Translation: ${translation.translatedText}');

// Chat
final response = await hasab.chat.sendMessage('Tell me about Ethiopia');
print('AI: ${response.message}');

📱 Platform Setup

Android

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

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

iOS

Add these to your ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice recording</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access</string>

🎨 Prebuilt Widgets

VoiceInputField

A text field with voice recording and automatic transcription:

VoiceInputField(
  speechToTextService: hasab.speechToText,
  onTranscriptionComplete: (text) {
    print('User said: $text');
  },
  decoration: InputDecoration(
    labelText: 'Speak or type...',
    border: OutlineInputBorder(),
  ),
)

TranslateButton

A button that translates text with a single tap:

TranslateButton(
  translationService: hasab.translation,
  text: 'Hello World',
  fromLanguage: HasabLanguage.english,
  toLanguage: HasabLanguage.amharic,
  onTranslationComplete: (translatedText) {
    print('Translated: $translatedText');
  },
)

ChatWidget

A full-featured chat interface:

ChatWidget(
  chatService: hasab.chat,
  showTimestamps: true,
  onMessageSent: (message) {
    print('Sent: $message');
  },
  onResponseReceived: (response) {
    print('AI: ${response.message}');
  },
)

📚 Detailed Usage

Speech-to-Text

// Basic transcription
final result = await hasab.speechToText.transcribe(audioFile);

// With language hint
final result = await hasab.speechToText.transcribe(
  audioFile,
  language: HasabLanguage.amharic,
);

// Detect language
final language = await hasab.speechToText.detectLanguage(audioFile);
print('Detected language: ${language.displayName}');

// Get supported formats
final formats = await hasab.speechToText.getSupportedFormats();
print('Supported: $formats');

Text-to-Speech

// Basic synthesis
final audio = await hasab.textToSpeech.synthesize(
  'ሰላም',
  HasabLanguage.amharic,
);

// With custom settings
final audio = await hasab.textToSpeech.synthesize(
  'Hello',
  HasabLanguage.english,
  speed: 1.2,
  outputPath: '/custom/path/audio.mp3',
);

// Get available voices
final voices = await hasab.textToSpeech.getAvailableVoices(
  HasabLanguage.amharic,
);

// Get audio as bytes
final bytes = await hasab.textToSpeech.synthesizeToBytes(
  'Hello',
  HasabLanguage.english,
);

Translation

// Basic translation
final result = await hasab.translation.translate(
  'Hello',
  HasabLanguage.english,
  HasabLanguage.amharic,
);

// Auto-detect source language
final result = await hasab.translation.translateWithAutoDetect(
  'ሰላም',
  HasabLanguage.english,
);

// Detect language
final language = await hasab.translation.detectLanguage('ሰላም');

// Batch translation
final results = await hasab.translation.translateBatch(
  ['Hello', 'Goodbye', 'Thank you'],
  HasabLanguage.english,
  HasabLanguage.amharic,
);

Chat

// Send a message
final response = await hasab.chat.sendMessage('Hello!');

// Continue a conversation
final response = await hasab.chat.sendMessage(
  'Tell me more',
  conversationId: previousResponse.conversationId,
);

// Get chat history
final history = await hasab.chat.getHistory(
  conversationId: conversationId,
);

// Start a new conversation
final conversationId = await hasab.chat.startConversation(
  initialMessage: 'Hi there!',
);

// Get all conversations
final conversations = await hasab.chat.getConversations();

// Delete a conversation
await hasab.chat.deleteConversation(conversationId);

🎙️ Audio Utilities

AudioRecorder

final recorder = AudioRecorder();
await recorder.initialize();

// Start recording
final path = await recorder.startRecording();

// Stop recording
final recordingPath = await recorder.stopRecording();

// Pause/Resume
await recorder.pauseRecording();
await recorder.resumeRecording();

// Cleanup
await recorder.dispose();

AudioPlayerHelper

final player = AudioPlayerHelper();

// Play from file
await player.playFromFile('/path/to/audio.mp3');

// Play from URL
await player.playFromUrl('https://example.com/audio.mp3');

// Control playback
await player.pause();
await player.play();
await player.stop();
await player.seek(Duration(seconds: 10));

// Set speed and volume
await player.setSpeed(1.5);
await player.setVolume(0.8);

// Listen to state
player.playerStateStream.listen((state) {
  print('Player state: $state');
});

// Cleanup
await player.dispose();

🔒 Error Handling

try {
  final result = await hasab.speechToText.transcribe(audioFile);
  print('Success: ${result.text}');
} on HasabAuthenticationException catch (e) {
  print('Authentication failed: $e');
} on HasabNetworkException catch (e) {
  print('Network error: $e');
} on HasabFileException catch (e) {
  print('File error: $e');
} on HasabValidationException catch (e) {
  print('Validation error: $e');
} on HasabException catch (e) {
  print('Hasab error: $e');
}

🏗️ Project Structure

lib/
  hasab_ai_flutter.dart       # Main export file
  src/
    hasab_ai.dart              # Main SDK class
    hasab_api_client.dart      # HTTP client
    services/
      speech_to_text.dart
      text_to_speech.dart
      translation.dart
      chat.dart
    models/
      language.dart
      request_models.dart
      response_models.dart
      hasab_exception.dart
    utils/
      audio_recorder.dart
      audio_player.dart
    widgets/
      voice_input_field.dart
      translate_button.dart
      chat_widget.dart

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Hasab AI Website
• API Documentation
• GitHub Repository

💬 Support

For support, email [email protected] or join our community on LinkedIn.

🙏 Acknowledgments

Built with ❤️ for the Ethiopian developer community.

---

Made with 🇪🇹 by the Hasab AI Team