🎵 Mp3Player

A modern, high-fidelity Android music player featuring AI song structure segmentation, smart weighted shuffle, seamless crossfading, offline LiteRT voice controls, dynamic 3x3 playlist collages, and automated CI/CD releases.

---

✨ Highlights & Key Features

Mp3Player gives you complete control over how music is analyzed, segmented, scheduled, and played:

✂️ AI Song Structure Segmentation ("Customize Song Parts")

• Harmonized Beat-Synchronous Laplacian Clustering: Uses ISMIR 2014 Beat-Synchronous Laplacian Spectral Clustering + Eigengap heuristic as authoritative ground truth for song macro-structure across all tiers.
• Dual Analysis Tiers:
  • 🔵 Tier 1 (CPU Spectral AI): Beat tracking, chroma recurrence, and spectral novelty peak-picking on CPU (runs in 1-2s per track).
  • 🟣 Tier 2 (GPU Neural AI): CUDA-accelerated Demucs HDEMUCS v4 source separation for isolated vocal tracks + SpeechBrain ECAPA-TDNN 192-dimensional biometric speaker voiceprints to detect singer transitions.
• Multi-Artist & Singer Isolation:
  • Automatically distinguishes between different vocalists (e.g. duet or featured artists).
  • Clean two-row preset selector:
    • Row 1 (Song Parts): [ All Parts ], [ Vocals Only ], [ No Intro/Outro ].
    • Row 2 (Singers): Dedicated filter chips for each detected vocalist ([ 👤 Artist 1 ], [ 👤 Artist 2 ]).
• Non-Destructive Playback Control: Skip unwanted intros/outros, isolate specific verses or choruses, or loop single sections in real time without modifying original audio files.
• Preservation of User Cuts: Tracks with existing AI segmentations are never forcibly overwritten. Clickable version badges ([ ⚡ Update v2 ], [ ⚡ Upgrade GPU ]) let you voluntarily upgrade tracks on demand.

🔀 Smart Weighted Shuffle & Chain-Skip Analytics

• Adaptive Track Weighting: Tracks you skip are automatically penalized in future shuffles, while tracks you manually jump to receive an immediate probability boost.
• Manual Likelihood Multipliers: Adjust any song's selection weight from 0.1x to 5.0x directly from the playlist menu.
• Keeper Leaderboard: Detects chain-skipping behavior and logs the song you ultimately settle on as a "Keeper," building a personalized leaderboard of tracks you truly enjoy.

🎚️ Dual-Player Seamless Crossfading & Audio DSP Engine

• Sinusoidal Crossfade: Dual ExoPlayer instances calculate smooth volume ramps for gapless, studio-quality track transitions.
• Smart Playback Safety: Automatic short-track duration clamping, corrupted file detection and auto-advance, and repeat-one loop isolation.
• Hardware Equalizer: Built-in 5-band EQ with Bass Boost and virtualizer effect management.

🎤 Hands-Free Offline Voice Control

• On-Device Keyword Spotting: Powered by Google LiteRT (TFLite) running local models 100% offline.
• Biking & Wind Filter: 4th-order Butterworth High-Pass Filter ($f_c = 150\text{ Hz}$) and hardware Acoustic Echo Cancellation (AEC) eliminate wind noise and road rumble.
• Supported Commands: "go" (play/resume), "stop" (pause), "right" (next track), "left" (previous track).

🔒 Lock Screen & Notification Shuffle / Loop Controls

• Direct Lock Screen Toggles: Custom MediaSessionCompat actions and system transport controls let you toggle shuffle and loop modes directly from the lock screen and notification shade without unlocking your phone.
• Dynamic Active State: Notification icons reflect current shuffle and repeat states in real time.

🎨 Dynamic 3x3 Collages & Official Album Art

• Automated Playlist Collages: PlaylistCoverManager sorts tracks by play frequency and synthesizes high-contrast 3x3 grid collages featuring the 9 most-played tracks.
• Music Video Detector: Detects generic YouTube thumbnails on downloaded tracks and automatically fetches official high-resolution album artwork.

🔍 Studio Audio Engine & Artist Discography Explorer

• Pure Studio Audio Filtering: Integrates YouTube Music's official track catalog (filter="songs") to deliver official studio album masters. Eliminates music video intro skits, cinematic sound effects, and talking.
• Artist Discography Explorer: Search any music artist to view their complete official discography—top tracks, full studio albums, and singles/EPs.
• 1-Tap Album Downloader: Browse numbered album tracklists and batch download full albums with one tap, automatically tagging album names and high-resolution cover art.
• Modern Tabbed Search UX: Fluid switching between [ Songs (Studio Audio) ] and [ Artists & Albums ], real-time auto-complete suggestions, and quick-discover popular artist chips.

📱 Interactive Home Screen Widgets (4x2, 4x1, Squircle)

• 1-Tap Instant Play: Tapping an upcoming thumbnail plays that track immediately while preserving your existing queue.
• Clickable Covers: Tapping the widget's playlist collage cover opens that playlist directly.
• Larger Touch Targets: Enlarged 32x32dp shuffle and loop buttons with a compact progress bar.

⚡ Rock-Solid Virtualization & Zero-Stutter Performance

• Compose List Virtualization: LazyColumn uses explicit contentType definitions to reuse item compositions during fast fling scrolling.
• Zero-Overhead Reordering: Physics animations are short-circuited when not actively dragging items, eliminating unnecessary 60/120Hz frame calculations.
• Downscaled Image Decoding: ID3 album art is decoded at target thumbnail resolutions (150x150) without native-resolution decoding, eliminating Davey frame drops and MediaCodec resource exhaustion.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Android Client (Kotlin)                  │
│                                                             │
│  ┌─────────────────────────┐   ┌─────────────────────────┐  │
│  │   UI (Jetpack Compose)  │   │   AudioService (Media3) │  │
│  │   - Playlist Virtualizer│   │   - Dual ExoPlayer      │  │
│  │   - Song Part Selector  │   │   - MediaSessionCompat  │  │
│  │   - Full & Mini Player  │   │   - Hardware Equalizer  │  │
│  └────────────┬────────────┘   └────────────┬────────────┘  │
│               │                             │               │
│  ┌────────────▼────────────┐   ┌────────────▼────────────┐  │
│  │ MusicViewModel (Flow)   │   │ LiteRT Voice Engine     │  │
│  │ Room Database (v6)      │   │ - 4th-Order Butterworth │  │
│  │ - SongSectionEntity     │   │ - Hardware AEC Filter   │  │
│  └────────────┬────────────┘   └─────────────────────────┘  │
└───────────────┼─────────────────────────────────────────────┘
                │ HTTP REST (Retrofit / OkHttp)
                ▼
┌─────────────────────────────────────────────────────────────┐
│                 FastAPI Backend Service                     │
│                                                             │
│  ┌─────────────────────────┐   ┌─────────────────────────┐  │
│  │  Tier 1 (CPU Spectral)  │   │   Tier 2 (GPU Neural)   │  │
│  │  - Laplacian ISMIR 2014 │   │   - CUDA Acceleration   │  │
│  │  - Eigengap Heuristic   │   │   - Demucs HDEMUCS v4   │  │
│  │  - Librosa & Scipy      │   │   - ECAPA-TDNN Voiceprint│ │
│  └─────────────────────────┘   └─────────────────────────┘  │
│  ┌─────────────────────────┐   ┌─────────────────────────┐  │
│  │ yt-dlp & ffmpeg engine  │   │ Mutagen ID3 & Art Tag   │  │
│  └─────────────────────────┘   └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

---

🔄 CI/CD & Automated GitHub Releases

This repository includes a GitHub Actions automated release pipeline in .github/workflows/release.yml:

• On Every Push to main:
  1. Runs the test suite (./gradlew testDebugUnitTest).
  2. Compiles both Debug and Release APKs (Mp3Player-Debug.apk and Mp3Player-Release.apk).
  3. Uploads the build artifacts to the workflow run.
  4. Automatically publishes / updates the "Latest Continuous Build" pre-release in the Releases tab so you can immediately download the newest APK to your phone.
• On Version Tag Push (git tag v1.x.x && git push origin v1.x.x):
  • Automatically compiles and publishes an official release with attached APKs and auto-generated release notes.
• Manual Dispatch:
  • Run the build and publish workflow manually anytime from the GitHub Actions web interface.

---

🚀 Getting Started

1. Download Pre-Built APK

1. Visit the Releases page.
2. Download Mp3Player-Release.apk (or Mp3Player-Debug.apk) directly on your Android phone.
3. Tap the file to install (enable "Install Unknown Apps" if prompted).

2. Build Locally

git clone https://github.com/UlrikTJ/Mp3Player.git
cd Mp3Player

# Run unit tests
./gradlew testDebugUnitTest

# Build Debug and Release APKs
./gradlew assembleDebug assembleRelease

Compiled APKs will be located at:

• app/build/outputs/apk/debug/Mp3Player-Debug.apk
• app/build/outputs/apk/release/Mp3Player-Release.apk

3. Backend Server Setup

For music search, YouTube downloading, and Tier 1/Tier 2 AI song segmentation:

cd server
chmod +x setup_ubuntu.sh
./setup_ubuntu.sh

Or start manually with Uvicorn:

cd server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

To run as a 24/7 background service on Ubuntu, see the instructions in server/README.md.

---

📄 License

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