🎵 Mp3Player

A modern, high-fidelity Android music player with seamless crossfading, smart weighted shuffle, offline LiteRT voice controls, dynamic 3x3 collage generation, and a custom FastAPI backend.

---

✨ What Makes This Usefull?

Mp3Player is designed for people who want more control over the shuffle algorithms,voice controls, and audio customization in general:

• 🔀 Smart Weighted Shuffle – Tracks you frequently skip are penalized. Tracks you manually skip to, receive a selection bonus. You can also manually adjust each track's likelihood multiplier, giving you full control over your listening probability.
• 🎚️ Seamless Crossfading – Dual ExoPlayer instances with a sinusoidal volume curve create smooth, studio-quality transitions between tracks.
• 🎤 Hands-Free Offline Voice Control – On-device keyword spotting powered by Google LiteRT (TFLite). Features hardware Acoustic Echo Cancellation (AEC) and a 4th-order Butterworth High-Pass Filter ($f_c = 150\text{ Hz}$) to eliminate wind rumble while biking or outdoors. Say "go" (play), "stop" (pause), "right" (skip), or "left" (previous) 100% offline.
• 📊 Chain-Skip Analytics – The app tracks when you skip multiple songs in a row and logs the track you finally stop on as a "Keeper". View your personal Keeper Leaderboard to see which songs you actually enjoy.
• 🎨 Dynamic Hash-Based 3x3 Collages – PlaylistCoverManager continuously sorts and caches 3x3 grid collages showing the 9 most played tracks per playlist. This makes it so each playlist is recognizeable and also looks clean.
• 🖼️ Music Video Detector & Auto-Art – Automatically detects generic YouTube video thumbnails for downloaded tracks and replaces them with high-resolution official album covers.
• 📱 High-Performance Interactive Widgets – Multi-size home screen widgets (4x1, 4x2, Squircle) with Dispatchers.IO off-thread rendering, zero-flicker progress ticks, direct 1-tap play intents, and queue previews.

---

🏗️ Architecture

┌────────────────────────────────────┐         Network         ┌────────────────────────────┐
│        Android Client              │ ──────────────────────> │    FastAPI Backend         │
│  ┌─────────────────────────────┐   │ <────────────────────── │  ┌───────────────────────┐ │
│  │  UI (Jetpack Compose)       │   │                         │  │  YouTube Search API   │ │
│  │  ViewModel (StateFlow)      │   │                         │  │  yt-dlp Integration   │ │
│  │  Room Database (Offline)    │   │                         │  │  MP3 Extraction       │ │
│  │  AudioService (Foreground)  │   │                         │  │  ID3 Tagging          │ │
│  │  Dual ExoPlayer (Crossfade) │   │                         │  │  Artwork Scraping     │ │
│  │  LiteRT (Voice Control)     │   │                         │  └───────────────────────┘ │
│  └─────────────────────────────┘   │                         └────────────────────────────┘
└────────────────────────────────────┘

Android Client

• 100% Kotlin with Jetpack Compose for reactive UI.
• Room SQLite for offline storage (songs, playlists, playback events, song stats).
• Coroutines & Flow for asynchronous state management.
• ExoPlayer with a dual-player engine for gapless crossfading.
• Google LiteRT (TFLite) for offline keyword spotting with 4th-order Butterworth High-Pass filtering and hardware AEC/NoiseSuppressor.
• Foreground Service with MediaSessionCompat, lock-screen transport, and widget integration.

Backend Server

• FastAPI (Python 3.10+) with automatic OpenAPI documentation.
• yt-dlp for YouTube search, streaming, and MP3 extraction.
• ffmpeg for audio conversion and normalization.
• mutagen for ID3 metadata and high-res album art embedding.

---

🚀 Getting Started

Option 1: Download the APK (Easiest)

1. Head to the Releases page on GitHub.
2. Download the latest .apk file directly to your Android device.
3. Install the APK (enable "Install from Unknown Sources" if prompted).
4. (Optional) Set up the backend server for YouTube search & downloads.

Option 2: Build from Source

git clone https://github.com/UlrikTJ/Mp3Player.git
cd Mp3Player
# Open in Android Studio and run ./gradlew assembleDebug

Option 3: Run the Backend Server

Requires Python 3.10+ and ffmpeg installed.

cd server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Then, in the Android app:

• Open Settings.
• Enter your server's IP address (e.g., 192.168.1.100 or your Tailscale IP).
• Start searching, streaming, and downloading!

---

📄 License

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