HariWave

A Modern Flutter Music Player
Combining local playback, audiobooks, and live radio in one elegant experience.

---

Overview

HariWave is a feature-rich music player application built with Flutter, designed to provide a seamless audio experience across multiple content types. Whether you're listening to your local music library, enjoying audiobooks during commutes, or tuning into live radio stations, HariWave delivers a premium, unified experience.

Key Features

• Local Music Playback – Scan and play music from your device with full metadata support
• Audiobook Support – Dedicated audiobook player with chapter navigation and bookmarks
• Live Radio – Stream radio stations with beautiful station artwork
• Queue Management – Add tracks to queue, reorder, and manage playback
• Mini Player – Persistent mini player visible across all screens
• Recently Played – Quick access to your listening history
• Liked Songs – Save your favorite tracks for easy access
• Playlists – Create and manage custom playlists
• Lyrics Display – View synchronized lyrics while playing
• Media Controls – Lock screen and notification controls
• Beautiful UI – Modern design with smooth animations

---

Architecture

Project Structure

lib/
├── main.dart              # App entry point
├── models/                # Data models (Audiobook, Song, Playlist, etc.)
├── providers/             # State management (Provider pattern)
├── screens/               # UI screens
├── services/              # Business logic services
├── utils/                 # Utility functions and helpers
└── widgets/               # Reusable UI components

Key Components

Layer	Description
Models	Data structures for audiobooks, songs, playlists, radio stations, and Spotify metadata
Providers	State management using ChangeNotifier pattern for audio, playlists, liked songs, and recent plays
Services	Audio playback, storage, authentication, downloads, and external API integrations
Widgets	Mini player, song tiles, seek bar, playback controls, and other reusable components

Audio Architecture

The audio system is built on:

• just_audio – Core audio playback engine
• audio_service – Background playback and media session management
• audio_session – Audio focus handling

---

Tech Stack

Technology	Purpose
Flutter 3.9+	Cross-platform UI framework
Dart	Programming language
Provider	State management
Hive	Local storage and caching
Dio	HTTP networking
Firebase	Authentication and cloud services
MediaSession	Android lock screen controls

Dependencies

See pubspec.yaml for the complete list. Key packages include:

• just_audio – Audio playback
• audio_service – Background audio
• hive_flutter – Local database
• cached_network_image – Image caching
• provider – State management
• firebase_auth – User authentication
• google_sign_in – OAuth integration

---

Getting Started

Prerequisites

• Flutter SDK 3.9.2 or higher
• Dart SDK 3.9.2 or higher
• Android Studio or VS Code with Flutter extensions
• Android SDK (API 21+)
• A physical Android device or emulator

Setup

1. Clone the repository

   git clone https://github.com/hariomgupta70427/HariWave.git
   cd HariWave

2. Install dependencies

   flutter pub get

3. Configure Firebase (required for auth)

   • Create a Firebase project at console.firebase.google.com
   • Add an Android app with package name: com.hariverse.hariwave
   • Download google-services.json to android/app/

4. Configure Spotify API (required for metadata)

   • Create a Spotify Developer app at developer.spotify.com
   • Copy lib/services/spotify_service.dart.example to lib/services/spotify_service.dart
   • Add your Spotify client credentials

5. Run the app

   flutter run

---

Build Instructions

Debug Build

flutter run -d <device_id>

Release APK

flutter build apk --release

The APK will be available at:

build/app/outputs/flutter-apk/app-release.apk

Split APKs (smaller size)

flutter build apk --split-per-abi

---

Folder Structure

HariWave/
├── android/               # Android platform files
├── assets/                # Static assets (icons, JSON configs)
├── ios/                   # iOS platform files (future support)
├── lib/                   # Dart source code
│   ├── main.dart
│   ├── models/
│   ├── providers/
│   ├── screens/
│   ├── services/
│   ├── utils/
│   └── widgets/
├── pubspec.yaml           # Dependencies and metadata
└── README.md

---

Configuration Files

The following files contain sensitive configuration and are git-ignored:

File	Purpose
lib/services/spotify_service.dart	Spotify API credentials
android/app/google-services.json	Firebase configuration
android/local.properties	Local SDK paths
android/key.properties	Release signing key

Note: You must configure these files locally before building.

---

Permissions

HariWave requires the following Android permissions:

• INTERNET – Network access for streaming and metadata
• READ_EXTERNAL_STORAGE – Access local music files
• FOREGROUND_SERVICE – Background audio playback
• WAKE_LOCK – Keep device awake during playback
• RECEIVE_BOOT_COMPLETED – Restore audio session after reboot

---

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow the official Dart Style Guide
• Run flutter analyze before submitting PRs
• Ensure all tests pass with flutter test

---

---

License

This project is proprietary software developed by Hariom Gupta.

---

Contact

Developer: Hariom Gupta

For questions, feedback, or collaboration inquiries, please open an issue on GitHub.

---