YumaPlayer (Yuma)

A hybrid music client for Android focused on usability, clean aesthetics, and audiophile-grade sound.
Spotify UI + Discovery Algorithms + YouTube Music Library + Hi-Res Lossless (FLAC).

Showcase • Features • Architecture • Download • Support

--- ## 🌟 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 13-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

_{Main Player (FLAC & Glass)}	_{3-Tier Synced Lyrics}	_{Queue (Dual-Sheet & Haptic)}
_{Immersive Artist Poster}	_{Telegram-Style Morphing}	_{Home (Quick Picks & YDS)}
_{Spotify Feed & Recommendations}	_{Spotify Radio & Mixes}	_{Spotify Daily Mixes}

--- ## ✨ 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 7+ providers (LRCLIB, Kugou, Paxsenix, 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 community contributions (Thanks Archivetune!).

> If you would like to contribute translations or improve existing language strings, join the discussion in our [Telegram Community](https://t.me/yumaplayer). --- ## 🏛️ Architecture & Documentation YumaPlayer is structured into **13 independent Gradle modules** following Clean Architecture and Unidirectional Data Flow (UDF) principles: ``` ┌─────────────────────────────────────────────────────────────┐ │ :app (Composition Root) │ └──────────────────────────────┬──────────────────────────────┘ │ ┌───────────────────────┼──────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │ :feature:* │ │ :service:* │ │ :lyrics:* │ :spotifycore│ │ (Compose UI) │ │ (Playback) │ │ :canvas │ :shazamkit │ └──────┬───────┘ └──────┬───────┘ └─────────────┬─────────────┘ │ │ │ └──────────────────────┼───────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ :core:* (Domain, Data, Model) │ └──────────────────────────────┬──────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Low-Level Media Extraction │ └─────────────────────────────────────────────────────────────┘ ``` 📖 **Detailed Developer Documentation:** * [Architecture Overview](docs/architecture/ARCHITECTURE.md) * [Modules Directory & Dependency Graph](docs/architecture/MODULES.md) * [Architectural Decision Records (ADRs)](docs/architecture/DECISIONS.md) * [Yuma Design System Specification (YDS 2.1)](docs/design/YDS.md) | [Russian Version](docs/design/YDS_ru.md) * [Coding Standards & Rules (Yuma Rules)](docs/development/YUMA_RULES.md) --- ## 📥 Download & Installation

GitHub Releases	Telegram Channel	Obtainium

### Building from Source ```bash 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 Ladybug (2024.2.1+) or newer, JDK 21, Android SDK 35+. --- ## ⚙️ 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:

Solana (SOL, USDT, USDC):
DT3ckdbNuiQMR1mrCpBXCMrhLB19GckVv3YfxsLLiF8z

PayPal / Email Transfer:
muwmix.coffee@gmail.com

--- ## 🤝 Acknowledgments (Open-Source Credits) YumaPlayer is built on the shoulders of the open-source community: * **[ArchiveTune](https://github.com/rukamori/ArchiveTune)** — for the solid playback foundations, rich settings base, and core architecture. * **[Meld](https://github.com/FrancescoGrazioso/Meld)** — for the conceptual breakthrough and implementation of the Spotify hybrid integration. * **[Stash](https://github.com/rawnaldclark/Stash)** — for inspiration in organizing lossless FLAC streaming and download pipelines. * **[Metrolist](https://github.com/mostafaalagamy/Metrolist)** & **[SimpMusic](https://github.com/maxrave-dev/SimpMusic)** — for early lyrics parsing and interface inspirations. * **[PixelPlayer](https://github.com/theovilardo/PixelPlayer)** — for swipe kinematics ideas and queue structure. * **[QBDLX](https://github.com/ImAiiR/QobuzDownloaderX)** — for the lossless audio streaming infrastructure. * **[LRCLIB](https://lrclib.net/)** & **[BetterLyrics](https://better-lyrics.boidu.dev/)** — 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! 🎵