HariWave is a cross-platform audio application built with Flutter, designed for listening to audiobooks, local music, and internet radio — all within a single, polished interface. The application is built for Android with a focus on performance, offline playback, and an intuitive user experience.
- Features
- Architecture
- Tech Stack
- Project Structure
- Getting Started
- Build Instructions
- Configuration
- Permissions
- Contributing
- License
A dedicated audiobook experience with tools tailored for long-form listening.
- Curated Catalogue — 50+ audiobooks spanning self-help, mythology, classic literature, and Hindi fiction, streamed directly from archive.org
- Category Browsing — Browse by genre including Self Help, Philosophy, Mythology, Hindi Literature, and more
- Bookmarks — Save and restore playback positions with optional notes. Bookmarks persist across sessions via local storage
- Offline Downloads — Download audiobooks for offline listening. Downloaded files are stored locally and tracked through the download manager
- Speed Control — Adjust playback from 0.5x to 2.0x in 0.25x increments
- Chapter Navigation — Fast-forward and rewind in 10-second jumps
- Progress Tracking — Automatically saves listening position and resumes from where you left off
Full playback support for music stored on the device.
- Device Scanning — Automatically discovers music files using MediaStore, sorted by title, artist, album, or duration
- Album Art — Displays embedded album artwork from local files
- Liked Songs — Mark songs as favourites with persistent storage
- Playlists — Create, rename, and delete custom playlists. Add or remove songs with batch selection
- Queue Management — Add songs to play next or append to queue. Drag-to-reorder and swipe-to-remove
- Background Playback — Music continues playing when the app is minimized, with lock screen and notification controls
Stream radio stations with live playback indicators.
- Curated Stations — Pre-configured list of streaming radio stations
- Live Indicator — Visual indicator showing active live stream status
- Station Favicons — Network-sourced station artwork with caching
- Mini Player — Persistent bottom bar visible across all tabs. Shows artwork, title, artist, playback type icon, and play/pause controls
- Now Playing Screen — Full-screen player with blurred artwork background, speed control, loop modes, seek bar, and bookmark management
- Media Notifications — Android lock screen controls with play, pause, skip, and seek actions via
audio_service - Audio Focus — Properly handles audio interruptions (calls, notifications) and resumes playback
- Firebase Authentication — Sign in with Google or email/password
- Profile Display — User avatar, name, and email shown in the navigation drawer
- Cloud Sync Ready — Playlist data synced to Firestore for cross-device access
- Theme — Dark, Light, and System-following theme modes with persistent storage
- Default Playback Speed — Configurable default speed (0.5x - 2.0x)
- Skip Duration — Configurable forward/backward skip interval (5s, 10s, 15s, 30s, 60s)
- Notifications — Toggle for playback and download notifications
- Storage Management — View total storage used by downloads and clear all downloads
The application follows a layered architecture with clear separation of concerns:
Presentation ── screens/ ── UI screens (pages)
State ── providers/ ── ChangeNotifier-based state management
Business ── services/ ── Business logic, API calls, data processing
Data ── models/ ── Data structures with Hive persistence
All shared state uses the Provider pattern with ChangeNotifier. Each provider is a singleton or scoped to the widget tree via MultiProvider:
| Provider | Responsibility |
|---|---|
AudioProvider |
Playback state, queue, bookmarks, unified audio metadata |
LibraryProvider |
Audiobook catalogue, categories, loading state |
RadioProvider |
Radio station list and selection |
AuthProvider |
Firebase authentication state |
ThemeProvider |
Theme mode persistence and switching |
User Action --> AudioProvider --> AudioPlayerService --> just_audio
|
HariWaveAudioHandler
(audio_service)
|
Android MediaSession
(Lock Screen / Notification)
- just_audio: Core audio engine handling playback, seeking, and buffering
- audio_service: Bridges the audio player to the Android system for background playback and media notifications
- audio_session: Manages audio focus — pauses for incoming calls, resumes after
- Hive: Primary local database for audiobooks, bookmarks, playlists, playback state, settings, and liked songs
- Firebase Firestore: Cloud backup for user playlists and liked songs
- Hive TypeAdapters: All model classes are registered with Hive for efficient binary serialization
| Category | Technology |
|---|---|
| Framework | Flutter 3.9+ (Dart 3.9+) |
| State Management | Provider (ChangeNotifier) |
| Local Database | Hive + Hive Flutter |
| Audio Playback | just_audio |
| Background Audio | audio_service |
| Audio Focus | audio_session |
| Network | Dio, http |
| Image Caching | cached_network_image |
| Authentication | Firebase Auth, Google Sign-In |
| Cloud Database | Cloud Firestore |
| Local Media | on_audio_query (MediaStore) |
| Sharing | share_plus |
| UI Utilities | shimmer, google_fonts, flutter_spinkit |
lib/
├── main.dart # Application entry point and provider setup
├── models/ # Data models
│ ├── audiobook.dart # Audiobook model (Hive Type 0)
│ ├── bookmark.dart # Bookmark model (Hive Type 1)
│ ├── playback_state.dart # Playback state model (Hive Type 2)
│ ├── song.dart # Song model (Hive Type 3)
│ ├── playlist.dart # Local playlist model (Hive Type 4)
│ ├── radio_station.dart # Radio station model (Hive Type 5)
│ └── models.dart # Barrel export
├── providers/ # State management
│ ├── audio_provider.dart # Audio playback state
│ ├── library_provider.dart # Audiobook catalogue state
│ ├── radio_provider.dart # Radio station state
│ ├── auth_provider.dart # Authentication state
│ ├── theme_provider.dart # Theme state
│ └── providers.dart # Barrel export
├── screens/ # UI screens
│ ├── home_screen.dart # Main screen with tabs
│ ├── now_playing_screen.dart # Full-screen player
│ ├── audiobook_library_screen.dart# Audiobook browsing
│ ├── audiobook_detail_screen.dart # Audiobook details
│ ├── local_music_screen.dart # Local music browser
│ ├── radio_screen.dart # Radio station browser
│ ├── search_screen.dart # Local search
│ ├── category_screen.dart # Category filtered view
│ ├── playlists_screen.dart # Playlist management
│ ├── downloads_screen.dart # Downloaded audiobooks
│ ├── settings_screen.dart # Settings and preferences
│ ├── auth/ # Authentication screens
│ │ ├── login_screen.dart
│ │ └── signup_screen.dart
│ └── screens.dart # Barrel export
├── services/ # Business logic
│ ├── audio_player_service.dart # Audio playback wrapper
│ ├── audio_handler.dart # Media session handler
│ ├── audiobook_service.dart # Audiobook data loading
│ ├── storage_service.dart # Hive persistence
│ ├── download_service.dart # File download management
│ ├── local_music_service.dart # MediaStore query service
│ ├── radio_service.dart # Radio station data
│ ├── auth_service.dart # Firebase auth wrapper
│ ├── user_data_service.dart # Firestore sync
│ └── services.dart # Barrel export
├── widgets/ # Reusable components
│ ├── mini_player.dart # Persistent mini player
│ ├── seek_bar.dart # Playback seek bar
│ ├── playback_controls.dart # Transport controls
│ ├── audiobook_card.dart # Audiobook display cards
│ ├── album_card.dart # Album artwork card
│ ├── song_tile.dart # Song list tile
│ ├── queue_view_sheet.dart # Queue management sheet
│ ├── track_options_sheet.dart # Song context menu
│ ├── app_drawer.dart # Navigation drawer
│ ├── scaffold_with_mini_player.dart
│ └── widgets.dart # Barrel export
└── utils/ # Utilities
├── theme.dart # App theming
├── constants.dart # Constants and helpers
└── utils.dart # Barrel export
- Flutter SDK 3.9.2 or higher
- Android SDK with API 30+ (Android 11)
- Java 17 or higher
- A Firebase project for authentication and cloud sync
# Clone the repository
git clone https://github.com/hariomgupta70427/HariWave.git
cd HariWave
# Install dependencies
flutter pub get
# Generate Hive type adapters (if modifying models)
flutter pub run build_runner build --delete-conflicting-outputs- Create a project at Firebase Console
- Register an Android app with package name
com.hariverse.hariwave - Download
google-services.jsonand place it inandroid/app/ - Ensure SHA-1 fingerprint is added for Google Sign-In (required for OAuth)
HariWave loads its audiobook catalogue from a JSON file containing book metadata and archive.org streaming URLs. By default, the app uses a bundled audiobooks.json asset. To enable automatic updates without recompiling:
- Host your
audiobooks.jsonon a web server or GitHub Pages - Implement the
loadFromUrl()method inAudiobookServiceto fetch from your hosted URL on startup - The app will cache the catalogue locally and fall back to the bundled version if offline
flutter runflutter build apk --releaseOutput: build/app/outputs/flutter-apk/app-release.apk
flutter build apk --split-per-abiProduces three APKs (arm64-v8a, armeabi-v7a, x86_64).
The app declares the following permissions in AndroidManifest.xml:
| Permission | Purpose |
|---|---|
INTERNET |
Network access for streaming and API calls |
READ_MEDIA_AUDIO |
Access local music files on Android 13+ |
FOREGROUND_SERVICE |
Background audio playback |
FOREGROUND_SERVICE_MEDIA_PLAYBACK |
Android 14+ media playback service type |
WAKE_LOCK |
Prevent device sleep during playback |
POST_NOTIFICATIONS |
Media notification display |
Release builds use R8 code shrinking with proguard-rules.pro. The minifyEnabled flag is set to false in the current build configuration to avoid issues with certain dependency classes. This can be enabled after thorough testing.
The application targets Android 11 (API 30) and above, leveraging modern Android APIs for scoped storage and media session controls.
Users are prompted for runtime permissions on first use:
- Music & Audio — Required for scanning and playing local music files
- Notifications — Required for media controls and download notifications
All permissions are optional and can be declined without blocking core app functionality.
Contributions are welcome. Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/description) - Write clean, documented code following Effective Dart guidelines
- Run
flutter analyzeto verify no warnings or errors - Commit with clear messages (
git commit -m "Add feature description") - Push your branch (
git push origin feature/description) - Open a Pull Request with a detailed description of changes
This project is proprietary software developed by Hariom Gupta. Unauthorized distribution or modification is prohibited.
Developer: Hariom Gupta
For questions, bug reports, or collaboration inquiries, please open an issue on the GitHub repository.