YumaPlayer

---

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 20-module architecture, a dedicated low-level audio DSP engine, 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

🎛️ Audio Engine & Smart Automix

• Dual-Deck Continuous Crossfade: True gapless and overlapping playback using two independent, synchronized audio deck controllers with atomic role swapping. Zero silence between tracks.
• DJ Transition Intelligence: Automated outro/intro cue detection, energy cliff analysis, BPM matching, and complementary bass-swap filters (0.45–0.55 window).
• Audiophile Codec Pipeline: Dedicated 24-bit packed PCM processing, Kopus-first Opus decoding with MediaCodec fallback, and native FLAC length resolution.
• Smart Stall Recovery: Automatic degradation to hard cut on buffer underruns, automated stream revival upon network reconnection, and strict source-scoped cache identities.
• N+1 Prefetching: Seamless background caching of upcoming tracks into the local download cache.

🔄 Dual Mode (Spotify + YouTube Music)

• Spotify Catalog: In-app browsing of Spotify albums, Daily Mixes, Discover Weekly, and playlists with cross-script deduplication and locale-aware metadata.
• YouTube Music Catalog: Full-catalog search across YouTube Music, charts, mood & genre categories, radio stations, and fast channel switching.
• SponsorBlock Integration: Configurable in-app segment skipping for sponsor messages, music hooks, fillers, and subscription reminders.

🎧 Lossless Playback & Local Audio

• 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 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).
• Audio Tuning: Built-in 5-band equalizer, EBU R128 loudness normalization, tempo and pitch adjustment, and a sleep timer.

🎨 Yuma Design System (YDS) & Fluid Motion

• Draggable Navigation Island: Compact floating navigation dock inspired by Telegram specifications, featuring dynamic corner morphing, scroll-hide sync, and local haptic feedback.
• Unified Player Sheet V2: Re-engineered gesture physics with GPU-accelerated backdrop blur (Haze), isolated drag layers, and independent artwork scaling.
• Canvas Video Backdrops: Hardware-accelerated background video loops supporting up to 4K resolution with an isolated cache.
• Spoiler Veil: Interactive Telegram-grade particle engine to obscure tokens and sensitive settings.
• Dynamic Monet Theming: Adaptive palette extraction powered by the currently playing track's artwork, tuned for strict WCAG contrast compliance.

🎤 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) with bounded memory allocation to prevent OOM.
• 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.

---

📥 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: Android Studio with AGP 9.x support, JDK 21, Android SDK 37 (compileSdk/targetSdk 37, minSdk 26).

---

🏛️ Architecture & Tech Stack

YumaPlayer is organized as a 20-module Clean Architecture project following Unidirectional Data Flow (UDF):

• UI & Presentation: Jetpack Compose, YDS 2.1 design tokens, GPU-accelerated Haze overlays, fluid gesture physics.
• Audio Engine: Media3 (ExoPlayer), :core:audio-dsp (Smart Automix, dual-deck continuous crossfader, DJ filter cascade).
• Network & Ingestion: :core:innertube (YouTube Music engine), Ktor/Retrofit, SOCKS5 proxy support with JVM Authenticator.
• Storage & Security: Room ORM, hardware-backed secure preferences (AES-256-GCM via Google Tink).

📖 Detailed Developer Documentation:

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

---

🌍 Globalization & Localization

YumaPlayer is localized into multiple languages thanks to our 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.

---

⚙️ 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 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:

• Solana (SOL, USDT, USDC):
  DT3ckdbNuiQMR1mrCpBXCMrhLB19GckVv3YfxsLLiF8z
• PayPal / Email Transfer:
  muwmix.coffee@gmail.com

---

📈 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.

---