🎵 SoulSync

Emotion-Driven Music Experience

A sophisticated Flutter-based music application that detects your emotions through facial expressions and voice analysis, then curates personalized playlists to match your mood.

Features • Tech Stack • Getting Started • Architecture • API Integration • Contributing

🌟 Overview

SoulSync is an innovative music streaming application that leverages multimodal emotion detection to create a deeply personalized listening experience. By analyzing both facial expressions and vocal patterns, SoulSync understands your emotional state and generates custom playlists that resonate with your current mood.

Key Highlights

🎭 Multimodal Emotion Detection: Combines facial expression analysis and voice pattern recognition
🎶 Smart Playlist Generation: AI-powered playlist curation based on valence-arousal emotional model
🔐 Secure Authentication: Multiple sign-in options including Google OAuth
🎨 Modern UI/UX: Clean, intuitive interface with smooth animations
📱 Cross-Platform: Supports Android, iOS, Web, Windows, macOS, and Linux

✨ Features

Core Features

🎭 Emotion Detection

Facial Expression Analysis: Real-time emotion detection using camera
Voice Pattern Recognition: Audio-based emotion analysis through microphone
Multimodal Fusion: Combines visual and audio signals for accurate emotion detection
Emotion Meter: Visual representation of detected emotions with valence-arousal scores

🎵 Music Features

Personalized Playlists: Auto-generated playlists based on emotional state
Music Player: Full-featured audio player with playback controls
Search & Discovery: Find songs and artists easily
Library Management: Organize your favorite tracks and playlists
Mini Player: Persistent mini player for seamless navigation
Audio Progress Bar: Visual playback progress with seeking capability

👤 User Features

Authentication: Email/password and Google Sign-In
User Profile: Personalized user profiles
Activity Tracking: Monitor your listening history and patterns
Preferences: Customizable user settings

🎨 User Experience

Dark/Light Theme: Toggle between theme modes
Smooth Animations: Lottie animations for enhanced UX
Responsive Design: Adaptive layouts for all screen sizes
Material Design: Modern Material Design 3 principles

🛠 Tech Stack

Frontend Framework

Flutter SDK: ^3.9.2 - Cross-platform UI framework
Dart: Latest stable version

State Management & Navigation

flutter_riverpod: ^3.2.1 - Reactive state management
go_router: ^17.1.0 - Declarative routing solution

Backend & Cloud Services

Firebase Core: ^4.5.0 - Firebase integration
Firebase Auth: ^6.2.0 - Authentication services
Supabase Flutter: ^2.12.0 - Backend-as-a-Service
Dio: ^5.9.2 - HTTP client for API requests

Authentication

Google Sign-In: ^7.2.0 - Google OAuth integration

Media & Multimedia

Camera: ^0.12.0 - Camera access for facial expression capture
Record: ^6.2.0 - Audio recording for voice analysis
Just Audio: ^0.10.5 - Audio playback engine
Audio Video Progress Bar: ^2.0.3 - Playback progress visualization
Lottie: ^3.3.2 - Animation library

UI & Styling

Google Fonts: ^8.0.2 - Custom typography
Cupertino Icons: ^1.0.8 - iOS-style icons

Utilities & Permissions

Permission Handler: ^12.0.1 - Runtime permissions management
Path Provider: ^2.1.5 - File system path access

Development Tools

Flutter Lints: ^5.0.0 - Recommended linting rules

🏗 Architecture

SoulSync follows Clean Architecture principles with a feature-first folder structure:

lib/
├── core/                    # Core application utilities
│   ├── config/             # App configuration
│   ├── network/            # Network layer & API clients
│   ├── theme/              # Theme configuration & controller
│   └── utils/              # Utility functions & helpers
│
├── features/               # Feature modules
│   ├── auth/              # Authentication flow
│   │   ├── screens/       # Login, signup screens
│   │   ├── services/      # Auth services
│   │   └── providers/     # Auth state providers
│   │
│   ├── emotion/           # Emotion detection
│   │   ├── emotion_screen.dart
│   │   ├── emotion_playlist_screen.dart
│   │   ├── emotion_service.dart
│   │   └── widgets/       # Emotion-specific widgets
│   │
│   ├── home/              # Home dashboard
│   │   ├── home_screen.dart
│   │   └── widgets/
│   │
│   ├── library/           # Music library
│   │   ├── library_screen.dart
│   │   ├── library_service.dart
│   │   └── widgets/
│   │
│   ├── player/            # Music player
│   │   ├── player_screen.dart
│   │   ├── player_service.dart
│   │   └── widgets/       # Player controls, mini player
│   │
│   ├── profile/           # User profile
│   ├── search/            # Search functionality
│   ├── splash/            # Splash screen
│   └── activity/          # User activity tracking
│
├── routes/                # Navigation & routing
│   └── app_router.dart
│
├── firebase_options.dart  # Firebase configuration
└── main.dart             # Application entry point

Design Patterns

Provider Pattern: For state management using Riverpod
Service Pattern: Business logic separation in service classes
Repository Pattern: Data layer abstraction
Feature-First: Modular architecture for scalability

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Flutter SDK: Version 3.9.2 or higher
```
flutter --version
```
Dart SDK: Version 3.9.2 or higher (comes with Flutter)
Android Studio / Xcode / VS Code: For development
Git: For version control
Firebase Account: For authentication services
Supabase Account: For backend services

Installation

Clone the repository

git clone https://github.com/yourusername/soulsync.git
cd soulsync/frontend_flutter

Install dependencies
```
flutter pub get
```
Verify installation
```
flutter doctor
```
Resolve any issues reported by Flutter Doctor.

Configuration

1. Firebase Setup

Create a Firebase project at Firebase Console
Enable Authentication with Email/Password and Google Sign-In
Download configuration files:
- Android: google-services.json → android/app/
- iOS: GoogleService-Info.plist → ios/Runner/
Run FlutterFire CLI to generate Firebase options:
```
flutterfire configure
```

2. Supabase Setup

Create a Supabase project at Supabase Dashboard
Get your project URL and API key
Update Supabase configuration in your app

3. Backend API Configuration

Update the API base URLs in service files:

For Emotion Detection API (lib/features/emotion/emotion_service.dart):

BaseOptions(baseUrl: "http://YOUR_EMOTION_API_HOST:8000")

For Playlist Generation API:

"http://YOUR_PLAYLIST_API_HOST:5000/api/generate-playlist"

4. Platform-Specific Setup

Android (android/app/build.gradle.kts):

Minimum SDK: 21 or higher
Target SDK: Latest stable

iOS (ios/Podfile):

iOS Deployment Target: 12.0 or higher
Run pod install in the ios/ directory

Permissions Configuration:

Android (android/app/src/main/AndroidManifest.xml):

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

iOS (ios/Runner/Info.plist):

<key>NSCameraUsageDescription</key>
<string>SoulSync needs camera access to detect your emotions</string>
<key>NSMicrophoneUsageDescription</key>
<string>SoulSync needs microphone access to analyze your voice</string>

Running the App

# Check available devices
flutter devices

# Run on specific device
flutter run -d <device_id>

# Run in debug mode
flutter run --debug

# Run in release mode
flutter run --release

📁 Project Structure

soulsync_app/
│
├── android/                 # Android platform code
├── ios/                     # iOS platform code
├── linux/                   # Linux platform code
├── macos/                   # macOS platform code
├── web/                     # Web platform code
├── windows/                 # Windows platform code
│
├── lib/                     # Main application code
│   ├── core/               # Core utilities & configuration
│   ├── features/           # Feature modules
│   ├── routes/             # Navigation
│   ├── firebase_options.dart
│   └── main.dart           # Entry point
│
├── test/                    # Unit & widget tests
├── build/                   # Build outputs (gitignored)
│
├── analysis_options.yaml    # Dart analysis configuration
├── pubspec.yaml            # Dependencies & metadata
├── README.md               # This file
└── soulsync_app.iml        # IntelliJ project file

🔌 API Integration

Emotion Detection API

Endpoint: /detect-human-emotion
Method: POST
Content-Type: multipart/form-data

Request:

FormData({
  "image": MultipartFile (captured facial image),
  "audio": MultipartFile (recorded voice audio)
})

Response:

{
  "emotion": "Happy",
  "valence": 0.75,
  "arousal": 0.60,
  "confidence": 0.89
}

Playlist Generation API

Endpoint: /api/generate-playlist
Method: POST
Content-Type: application/json

Request:

{
  "userId": "user123",
  "valence": 0.75,
  "arousal": 0.60
}

Response:

{
  "playlist": [
    {
      "id": "song1",
      "title": "Happy Song",
      "artist": "Artist Name",
      "duration": 180,
      "url": "https://..."
    }
  ]
}

💻 Development

Code Style & Linting

# Analyze code
flutter analyze

# Format code
flutter format lib/

# Check for outdated dependencies
flutter pub outdated

Hot Reload & Restart

Hot Reload: Press r in terminal during debug session
Hot Restart: Press R in terminal during debug session

State Management

The app uses Riverpod for state management:

// Provider example
final themeProvider = StateNotifierProvider<ThemeController, ThemeData>((ref) {
  return ThemeController();
});

// Consuming provider
final theme = ref.watch(themeProvider);

Adding New Features

Create feature folder in lib/features/
Add screens, services, and widgets
Register routes in lib/routes/app_router.dart
Update navigation as needed

📦 Building for Production

Android

# Build APK
flutter build apk --release

# Build App Bundle (for Play Store)
flutter build appbundle --release

# Output: build/app/outputs/

iOS

# Build iOS app
flutter build ios --release

# Archive with Xcode for App Store submission

Web

# Build web app
flutter build web --release

# Output: build/web/

Desktop

# Windows
flutter build windows --release

# macOS
flutter build macos --release

# Linux
flutter build linux --release

🧪 Testing

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/widget_test.dart

Test Structure

Unit Tests: Business logic testing
Widget Tests: UI component testing
Integration Tests: End-to-end testing

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```

Commit your changes

git commit -m 'Add some amazing feature'

Push to the branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Development Guidelines

Follow Flutter style guide
Write meaningful commit messages
Add tests for new features
Update documentation as needed
Ensure code passes linting (flutter analyze)

📄 License

🙏 Acknowledgments

Technologies

Flutter - UI framework
Firebase - Backend services
Supabase - Database & backend
Riverpod - State management

Team

Developers: SoulSync Development Team
Institution: College Project - SEM 4, MFC
Academic Year: 2025-2026

Special Thanks

Flutter community for excellent packages
Open source contributors
Academic advisors and mentors

📞 Support & Contact

For questions, issues, or suggestions:

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@soulsync.app

Made with ❤️ using Flutter

Connecting emotions with music, one song at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
android		android
ios		ios
lib		lib
linux		linux
macos		macos
test		test
web		web
windows		windows
.gitignore		.gitignore
.metadata		.metadata
README.md		README.md
analysis_options.yaml		analysis_options.yaml
firebase.json		firebase.json
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation

🎵 SoulSync

Emotion-Driven Music Experience

📋 Table of Contents

🌟 Overview

Key Highlights

✨ Features

Core Features

🎭 Emotion Detection

🎵 Music Features

👤 User Features

🎨 User Experience

🛠 Tech Stack

Frontend Framework

State Management & Navigation

Backend & Cloud Services

Authentication

Media & Multimedia

UI & Styling

Utilities & Permissions

Development Tools

🏗 Architecture

Design Patterns

🚀 Getting Started

Prerequisites

Installation

Configuration

1. Firebase Setup

2. Supabase Setup

3. Backend API Configuration

4. Platform-Specific Setup

Running the App

📁 Project Structure

🔌 API Integration

Emotion Detection API

Playlist Generation API

💻 Development

Code Style & Linting

Hot Reload & Restart

State Management

Adding New Features

📦 Building for Production

Android

iOS

Web

Desktop

🧪 Testing

Test Structure

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

Technologies

Team

Special Thanks

📞 Support & Contact

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages