---

🌟 About the Project

YumaPlayer is an independent, open-source Android music player that unites the libraries and recommendation features of two leading streaming services alongside standalone local playback in Hi-Res quality.

The project evolved as a comprehensive rebuild of ArchiveTune (with foundations from Metrolist and SimpMusic), inspired by PixelPlayer's queue mechanics, Meld's Spotify integration pipeline, and Stash's FLAC architecture. On top of this base, YumaPlayer implements a modular 18-module architecture, the custom YDS 2.1 design system, and hardware-accelerated fluid gesture physics.

No subscriptions. No advertisements. Zero telemetry, crash reporters, or third-party trackers. All credentials live exclusively on your device, encrypted with AES-256-GCM via Google Tink, and the codebase is completely open under the GNU General Public License v3.0.

---

📸 Showcase

---

✨ Key Features

🔄 Dual Mode (Spotify + YouTube Music)

• Spotify Home: Personalized recommendation feeds, Daily Mixes, Discover Weekly, favorite artist shelves, and direct import of your Spotify playlists and liked songs.
• YouTube Music Home: Full-catalog search across YouTube Music, charts, mood & genre categories, radio stations, and fast channel switching.

🎧 Audiophile Playback & Lossless FLAC

• Lossless FLAC: Stream and download true lossless FLAC tracks (via Qobuz / QBDLX backbone integration) using your own credentials or open community resolvers.
• Seamless Fallback: If a track is unavailable in lossless catalogs, playback instantly and silently routes through YouTube Music's high-bitrate stream (Opus / AAC).
• Local Audio Engine: Built-in player for standalone files stored on your device (FLAC, MP3, AAC, OGG, WAV).
• Offline & Caching: Automatic caching of played YouTube Music tracks for offline listening without recurring data usage (FLAC offline caching in active development).
• Audio Tuning: Built-in 5-band equalizer with system audio effects support, EBU R128 loudness normalization, smooth crossfading, tempo and pitch adjustment, and a sleep timer.

🎤 Synchronized Lyrics & AI Translation

• 3-Tier Synchronized Display: Simultaneous live display of original lyrics (Kanji / Hangul), pronunciation guide (Romaji), and translated lines.
• Live Karaoke Scrolling: Word-by-word and line-by-line sync pulled from 6+ providers (LRCLIB, Kugou, BetterLyrics, SimpMusic, Unison, YouLyPlus).
• On-the-Fly AI Translation: Instant translation of lyrics into your preferred language right inside the player.
• Lyrics Card Sharing: Export and share formatted lyrics quote cards as clean images.

🎨 Yuma Design System (YDS 2.1) & Fluid Motion

• Real Glassmorphism: Translucent glass cards (GlassScaffold, 0.5dp hairline borders, composite 22dp / 5dp corner geometry).
• Dual-Sheet Gesture Engine: Independent, conflict-free player sheets (swipe up on the left for Lyrics, swipe up on the right for Queue).
• Telegram-Style Morphing Header: Smooth, scroll-linked transformation of artist posters into a status-bar drop using custom 3-point lerp3 without image distortion.
• Smart Freeze & Pre-warming: Instant sheet expansion with 0-frame startup latency, while off-screen physics loops and background tasks suspend automatically (snapshotFlow) to preserve battery life and keep the device cool.
• Dynamic Monet Theming: Adaptive palette extraction powered by the currently playing track's artwork, tuned for strict WCAG contrast compliance.

🌐 Integrations & Convenience

• Spotify Canvas & Apple Motion: Looping video backgrounds during playback (In development).
• Music Recognition (Shazam): Acoustic fingerprint search for songs playing around you (In development).
• Together (Listen Together): Synchronized playback with friends over WebSockets.
• Scrobbling: Native Last.fm and ListenBrainz integration.
• Discord Rich Presence: Real-time presence status showing your current track and album art on Discord.
• Android Auto & Widgets: In-car playback support and home screen Glance widgets.

---

🌍 Globalization & Localization

YumaPlayer is localized into multiple languages thanks to our amazing community translators. The localization pipeline is continuously synchronized with the codebase via Hosted Weblate.

Want to help translate Yuma? No coding or Git knowledge required. Just open our Weblate translation dashboard, choose your language, and start contributing directly through your browser.

---

🏛️ Architecture & Tech Stack

YumaPlayer is built as a multi-module Android project following Clean Architecture and Unidirectional Data Flow (UDF) principles:

• UI & Design: Jetpack Compose, YDS 2.1 design tokens, Hardware-accelerated Haze overlays, fluid gesture physics.
• Audio Engine: Media3 (ExoPlayer), standalone local audio pipeline, Qobuz/FLAC resolver backbone.
• Data & Storage: Room ORM, encrypted secure preferences (AES-256-GCM via Google Tink).
• Network & Ingestion: Ktor/Retrofit, InnerTube (YouTube Music engine), custom multi-source lyrics scrapers.

📖 Detailed Developer Documentation:

• Architecture Overview & Module Graph
• Architectural Decision Records (ADRs)
• Yuma Design System Specification (YDS 2.1)
• Coding Standards & Rules

---

📥 Download & Installation

Building from Source

git clone https://github.com/MuwMx/YumaPlayer.git
cd YumaPlayer
./gradlew assembleRelease
# Built APK will be located at: app/build/outputs/apk/release/

Prerequisites: A recent Android Studio version with AGP 9.x support, JDK 21, Android SDK 37 (compileSdk/targetSdk 37, minSdk 26).

---

⚙️ Account Setup

YumaPlayer is fully functional out of the box without signing in. Logging in is optional and only required to sync personal playlists, likes, and recommendations:

🎵 Connecting Spotify

1. Open Settings → Account → Spotify → Tap Log In.
2. Sign in with your standard Spotify credentials in the secure in-app browser window.
3. Your session cookie (sp_dc) will be automatically captured and encrypted on your device.

📺 Connecting YouTube Music

Two convenient login methods are supported:

• Method 1 (Google Account): Open Settings → Account → YouTube → Sign in using the secure in-app authentication sheet.
• Method 2 (Token / Cookie Input): If you use two-factor authentication or prefer manual setup, navigate to Settings → Account → Token Editor and paste your session cookies directly.

---

☕ Support the Project

YumaPlayer is free, open source, and has no ads or subscriptions. If you enjoy using the player and wish to support ongoing development:

---

📈 Star History

---

💡 Contributing

Contributions make open-source projects thrive! Whether you are fixing bugs, proposing new features, or improving docs:

• Read our Contribution Guidelines before submitting code or PRs.
• Want to translate? Head over to our Hosted Weblate — no coding required.

👥 Contributors

---

🤝 Acknowledgments (Open-Source Credits)

YumaPlayer is built on the shoulders of the open-source community:

• ArchiveTune — for the solid playback foundations, rich settings base, and core architecture.
• Meld — for the conceptual breakthrough and implementation of the Spotify hybrid integration.
• Stash — for inspiration in organizing lossless FLAC streaming and download pipelines.
• Metrolist & SimpMusic — for early lyrics parsing and interface inspirations.
• PixelPlayer — for swipe kinematics ideas and queue structure.
• QBDLX — for the lossless audio streaming infrastructure.
• LRCLIB & BetterLyrics — for the open synchronized lyrics databases.

---

⚖️ License & Legal Disclaimer

License

YumaPlayer is free software licensed under the GNU General Public License v3.0 (GPLv3).
You may freely copy, modify, and redistribute the source code provided you preserve copyright notices and distribute derivative works under the same GPL-3.0 license.

Disclaimer

YumaPlayer is an independent third-party client. It is not affiliated with, endorsed by, or sponsored by Google LLC, YouTube Music, or Spotify AB. The application is provided for personal use only as a tool for managing your own library.

---

Crafted with ❤️ and attention to every frame. Enjoy the music! 🎵