A native Android music player built around YouTube Music, with synced lyrics, offline downloads, a powerful audio engine and a highly customisable player.
Hi, I'm ItzFallenMe. I build Android apps, web projects and practical tools — KatMusic is my home for the music-player ideas I want to use every day.
Download v2.6.0 · Project website · Changelog
Kotlin · Jetpack Compose · Material 3 · C++ · Oboe
KatMusic brings streaming, your personal library and advanced playback controls into one Android app. It combines a Compose interface with a native audio engine, so everyday listening and deeper audio controls live in the same place.
Some integrations require you to sign in or provide your own service credentials. Optional AI features use the endpoint and API key you configure.
- Features
- Player styles
- Screenshots
- Desktop
- Download and install
- Build from source
- Project structure
- Privacy and security
- Contributing
- Credits
- License
- Disclaimer
- Browse and play songs, albums, artists, playlists, mixes and podcasts from the YouTube Music catalogue.
- Background playback with media notifications, lock-screen controls, queue management, shuffle, repeat and autoplay.
- Browse and control your library through Android Auto.
- Playback speed, sleep timer, loudness processing and audio-quality options.
- Listen Together creates an online room with a code, co-hosts, collaborative playback, shared queue and chat; playback stays in sync across devices.
- Native audio processing built around C++ and Oboe.
- Parametric equaliser, graphic EQ, presets and AutoEQ headphone profiles.
- Automix with crossfade planning, BPM/phase analysis and WSOLA time stretching.
- USB exclusive output and direct-output paths on supported devices and audio hardware.
Output modes, supported codecs and bit-perfect behaviour depend on the Android device, DAC and audio route. The app cannot override hardware or operating-system limitations.
- Line-synced and word/syllable-synced karaoke lyrics.
- Multiple lyric sources with provider selection and fallback handling.
- Translation, romanisation, text-size controls and timing offset.
- Shareable lyric cards.
- Home feed, search suggestions, Explore, new releases, genres and listening statistics.
- Liked songs, playlists, listening history, downloads and local music.
- Genre discovery and Smart Mix recommendations.
- Optional AI music picks using an OpenAI-compatible endpoint that you configure.
- Podcast and video-podcast support.
- A visible download queue with progress, cancel and retry.
- Wi-Fi-only downloads that pause on mobile data and resume when Wi-Fi returns.
- Saved artwork, lyrics and audio metadata where the source and format support them.
- Downloads are organised under
Music/KatMusic.
- Spotify Canvas artwork.
- Last.fm scrobbling and listening activity.
- Discord Rich Presence.
- YouTube Music account support for personalised features and library access.
- Material 3 interface with light, dark and pure-black themes.
- Wallpaper- and artwork-derived colour palettes.
- Floating navigation dock, expressive transitions and a home-screen widget.
- Player layout selection, lyric appearance controls and additional playback settings.
Choose the expanded player layout in Settings → Playback & UI → Player Style.
| Style | What it does |
|---|---|
| Classic | KatMusic's full player with its tabs, queue and advanced controls. |
| Poster | Large circular artwork with expressive track text and synced lyric context. |
| Timeline | A progress-led layout with a colour split and oversized timestamps. |
| Lyrics | An expressive lyrics-focused view with timed syllable highlighting. |
| Artwork | Large album artwork with focused playback controls. |
| Canvas | An immersive player background using available Canvas artwork. |
The Poster, Timeline and expressive Lyrics concepts are adapted from Mochy Music. The original source files and their GPL-3.0 licence are preserved in third_party/Mochy-Music.
KatMusic Desktop is a Flutter app for Windows, Linux and macOS. It is not a web wrapper: it uses the same YouTube Music and lossless streaming sources, Last.fm taste and scrobbling, synced lyrics, downloads, group Jam rooms and local playback as the Android app, with native desktop window, tray and media controls.
The desktop UI is its own interpretation of KatMusic: midnight-navy surfaces, KatMusic blue, Figtree type, and shader-backed Liquid Glass navigation chrome. It is built with Flutter 3.47+ and the liquid_glass_widgets package; turn the effect off in Settings → Surface & motion if you prefer an opaque shell.
Install Flutter 3.47 or newer, then:
cd desktop
flutter pub get
dart tool/obfuscate_secrets.dart # creates the gitignored secrets file
flutter run -d windows # or: linux, macosCreate desktop/.env from desktop/.env.example before the secrets step if you
have an addon key. The app runs without one; keyed addon calls fail closed.
cd desktop
flutter build windows --release # build/windows/x64/runner/Release
flutter build linux --release # build/linux/x64/release/bundle
flutter build macos --release # build/macos/Build/Products/ReleaseLinux deb/rpm packaging uses desktop/linux/packaging/nfpm.yaml; Windows
installer source is desktop/windows/installer.iss. Tagged v* builds and
manual runs are produced by .github/workflows/desktop.yml.
See desktop/README.md for platform dependencies, architecture and troubleshooting.
Latest stable release: KatMusic 2.6.0
Choose the package that matches your device:
| Package | Android version | Recommended for |
|---|---|---|
| Universal APK | Android 10+ | Most devices. Recommended for normal installation. |
| ARM64 APK | Android 10+ | 64-bit ARM phones and tablets. |
| Legacy APK | Android 7–9 | Older supported devices. Some visual effects and media controls use legacy alternatives. |
| Uncompressed universal APK | Android 10+ | Larger, uncompressed package for troubleshooting and testing. |
- Download the APK that matches your device.
- Open the downloaded file and approve installation when Android asks.
- Launch KatMusic and configure account access or optional integrations from Settings.
You can also download the SHA-256 checksums to verify a package, or browse all releases.
- JDK 17
- Android SDK with platform 37
- Android NDK
- CMake 3.22.1 (used by the native audio engine)
git clone https://github.com/Arct-Development/KatMusic.git
cd KatMusic
# Build a debug APK
./gradlew :app:assembleDebug
# Run local unit tests
./gradlew :app:testDebugUnitTest
# Build a signed release APK
./gradlew :app:assembleReleaseThe debug APK is generated at:
app/build/outputs/apk/debug/app-debug.apk
Release builds require your own signing key. KatMusic deliberately refuses to create a release APK with a temporary debug key, because an incorrectly signed update would not install over the existing app.
For a local build, copy .env.example to .env and set the signing values:
RELEASE_STORE_FILE=path/to/release.keystore
RELEASE_STORE_PASSWORD=your_keystore_password
RELEASE_KEY_ALIAS=your_key_alias
RELEASE_KEY_PASSWORD=your_key_passwordA base64-encoded keystore can also be supplied with SIGNING_KEY and the matching password/alias environment variables. Keep .env, keystore files, passwords and API keys private. Never commit signing credentials or personal tokens.
For the CI build and contribution workflow, see CONTRIBUTING.md.
| Path | Purpose |
|---|---|
app/src/main/java/.../data/ |
Catalogue, accounts, lyrics, downloads, library and settings data. |
app/src/main/java/.../playback/ |
Player state, playback coordination and audio features. |
app/src/main/java/.../ui/ |
Compose screens, components, player and theming. |
app/src/main/cpp/ |
Native audio engine and DSP implementation. |
audio/ |
Native audio support modules. |
website/ |
KatMusic project website. |
third_party/ |
Third-party source and licence notices. |
tools/ |
Build and development utilities. |
- Kotlin and Jetpack Compose for the Android application.
- Material 3 for the interface and theming.
- Media3 / ExoPlayer for media playback and media-session integration.
- Hilt, StateFlow, DataStore and Room for app state and persistence.
- C++ and Oboe for native audio processing and output.
- KatMusic does not bundle an analytics or advertising-tracking SDK.
- Network requests go to the catalogue, lyric and integration services needed for the features you use.
- Account sessions and locally configured credentials are stored on-device; do not include them in bug reports or commits.
- Optional integrations such as Last.fm, Discord and AI recommendations are controlled by your settings. AI requests are sent to the endpoint you configure.
For security issues, please follow SECURITY.md rather than posting sensitive details in a public issue.
Contributions, bug reports and thoughtful feature requests are welcome.
- Read the contribution guide before opening a pull request.
- For bugs, include reproduction steps, Android version, device details and relevant logs.
- For larger features, open an issue first so the approach can be discussed.
- Keep credentials, tokens, keystores and personal data out of commits.
Please also read the Code of Conduct.
KatMusic builds on the work of many open-source projects and services:
- Mochy Music by InlitX — source and design inspiration for the Poster, Timeline and expressive Lyrics player styles. Original files and GPL-3.0 licence: third_party/Mochy-Music.
- SimpMusic — lyrics-provider and integration reference.
- RiMusic — InnerTube and YouTube Music integration reference.
- Monochrome Music — FLAC and lossless-streaming reference.
- NewPipe Extractor — stream extraction.
- Coil — image loading.
- Oboe — low-latency native audio.
- AndroidX, Jetpack Compose, Material 3 and Media3 — application UI and media foundations.
Lyrics may be supplied by LRCLIB, Apple Music, YouTube Music and other providers available in the app. Service names and trademarks belong to their respective owners.
KatMusic is licensed under the GNU General Public License v3.0. See LICENSE.
Third-party code remains subject to its own notices and licence terms. In particular, Mochy Music's preserved source is covered by the GPL-3.0 licence included at third_party/Mochy-Music/LICENSE.
KatMusic is an independent, third-party project. It is not affiliated with, endorsed by or officially connected to Google or YouTube. YouTube and YouTube Music are trademarks of Google LLC.
Built by ItzFallenMe · Arct Development