Installation Guide

SoulSync — Installation Guide

Prerequisites

• Flutter SDK version 3.0.0 or above
• Android Studio (for Android) or Xcode (for iOS) installed
• A Groq API key from console.groq.com (a default key is included for testing)
• Android SDK configured, or Xcode with a valid Apple Developer provisioning profile

Step 1 — Extract and Open the Project

Extract the downloaded ZIP file to your preferred working directory. Open your terminal or command prompt and navigate into the project root folder.

Step 2 — Install Dependencies

Run the following command to fetch all required packages listed in pubspec.yaml:

flutter pub get

Step 3 — Android Setup

Open the file located at android/app/src/main/AndroidManifest.xml and confirm the following permissions are present inside the manifest tag:

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

These permissions are already added in the project. Connect your Android device or start an Android emulator, then run:

flutter run

Step 4 — iOS Setup

Open the file located at ios/Runner/Info.plist and confirm the following keys are present:

<key>NSMicrophoneUsageDescription</key>
<string>SoulSync needs microphone access so you can talk with your AI companion.</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>SoulSync uses speech recognition to understand what you say during voice calls.</string>

Both keys are already configured in the project. Open the ios folder in Xcode, assign your development team under Signing and Capabilities, then run:

flutter run

Step 5 — First Launch and Onboarding

When the app launches, you will be taken through a 3-step onboarding screen. Enter your name and age, select your gender (which determines your AI companion — Cara for male users, Ethan for female users), then choose your personality type, love language, and current mood. All this data is stored locally using SharedPreferences.

Step 6 — Configure Your Groq API Key (Optional)

A default Groq API key is bundled for testing purposes. To use your own key, navigate to Profile and then Settings inside the app and tap Change API Key. Enter your key obtained from console.groq.com.

Step 7 — Start a Conversation or Voice Call

Type a message in the chat input bar to begin a text conversation. Tap the call icon in the chat header to start a voice call. The app will listen to your voice, send it to the Groq API, and respond with synthesized speech automatically in a continuous loop.

Dependencies Reference

flutter_animate: ^4.5.0
google_fonts: ^6.2.1
flutter_spinkit: ^5.2.1
flutter_riverpod: ^2.5.1
http: ^1.2.1
shared_preferences: ^2.2.3
hive_flutter: ^1.1.0
uuid: ^4.4.0
speech_to_text: ^7.0.0
flutter_tts: ^3.8.5

Important Notes

• Test voice features on a physical device; the iOS simulator may not support flutter_tts audio output reliably.
• Microphone permission must be granted at runtime on both Android and iOS when prompted by the system.
• No backend server is required. All API calls are made directly from the Flutter app to the Groq API endpoint.
• The app uses a rolling 20-message conversation history for context in every API call.
• The model used is meta-llama/llama-4-scout-17b-16e-instruct. No changes are needed unless you want to switch models.