MeloX-Android

Project Url: lladlam/MeloX-Android
Introduction: A third-party music client based on MeloX, styled after Apple Music and featuring unique functions.
More: Author   ReportBugs   
Tags:

中文

Downloads Release Last Commit QQ Group Telegram License

MeloX Android icon

Native Android port of MeloX, built with Kotlin and Jetpack Compose

Desktop editions

The Windows and Linux editions are in their final verification stage. If you would like to use the Windows edition, please Star both projects:

[!IMPORTANT] MeloX Android is still in development. Core features for the current Android scope have been migrated and continue to follow the MeloX mainline. Third-party APIs, OEM protocols, and OS versions can still change compatibility.

MeloX Android is an unofficial open-source project. It is not affiliated with, partnered with, or authorized by NetEase Cloud Music, Xiaomi, Apple, or their related companies.

Current version: 0.7.1

0.7.1 (versionCode 26, 2026-10-27) fixes third-party HTTP music sources and LX script threading, widens the experimental USB exclusive output to full-speed and high-speed UAC1 with exportable diagnostics, and hardens startup plus optional integrations.

  • Third-party sources now import, request and play over an isolated HTTP channel that supports dynamic domains, redirects and media Range requests without inheriting account cookies. LX script sessions stay on their own QuickJS thread with waits that cover the default HTTP timeout.

  • USB exclusive output accepts full-speed and high-speed UAC1 adaptive/synchronous endpoints with 16–32-bit PCM containers (widened from PCM16; not bit-perfect), schedules packets per USB microframe, keeps the buffer on pause, flushes stale audio on seek, and appends USB descriptors and speed results to exported logs. UAC2 and asynchronous feedback remain unsupported pending real-DAC validation.

  • Startup hardening covers account-encryption migration failures, audio-controller binding and volume broadcasts, external lyric bridges, and optional Xiaomi/超级岛 services; Android 10/EMUI output panels and PiP/service-type version checks are corrected. AutoMix and LAN cast can no longer interrupt or unmute a USB exclusive session.

  • Download and full notes: GitHub Releases

  • Version history: CHANGELOG.md

[!WARNING] Third-party music sources are imported by the user and depend on external services. Sources used for testing before release have failed because of dead endpoints, rate limits, DNS or certificate errors, or unplayable URLs. MeloX cannot guarantee that any third-party source works. If you hit a problem, open Settings → About, scroll to the bottom, export all MeloX logs, and send them to lladlam114@gmail.com. Logs may contain account state, song metadata, request URLs, or other private data. Review them before sending.

About

MeloX Android is a native Android port of the design, interaction, and business logic in MeloX, the iOS / macOS client created by youshen2. The iOS version is not made by the Android maintainer.

The goal is not a WebView wrapper. MeloX is reimplemented with native Android capabilities:

  • Kotlin + Jetpack Compose for the interface;
  • AndroidX Media3 / ExoPlayer for playback, background audio, and the system media session;
  • iOS-only capabilities mapped to Android platform features;
  • optional HyperOS Focus Notification / Super Island support, while remaining usable on stock Android;
  • a MeloX / Apple Music style player, lyrics, library, and transitions;
  • Apple Watch features are outside the Android scope.

Root is not required. Platform extras use standard Android or OEM APIs and degrade when unsupported.

Implemented

Account and NetEase Cloud Music

  • NetEase web login;
  • persistent MUSIC_U cookie session;
  • authenticated search, song details, lyrics, playback URLs, and library requests;
  • playback cache refresh after account entitlement changes.

Search and library

  • Songs, playlists, albums, artists, users, and podcasts;
  • Liked songs;
  • User playlists;
  • Create public or private playlists, add songs, and remove songs from your own playlists;
  • Recently played;
  • Playlist, album, artist, song wiki, and comment details;
  • Charts, home recommendations, daily recommendations, private FM, and heart mode;
  • Podcast home, categories, subscriptions, and episode details;
  • NetEase cloud drive read, search, upload, playback, and delete;
  • Multi-select download, per-download quality, offline lyrics, auto cache, storage repair, and pause / resume;
  • App-private offline copies, optional MediaStore export, and a local library by song, artist, album, and folder;
  • Play directly from the library or search results;
  • Library-wide search across songs, playlists, albums, artists, and recent playback.

Player

  • Mini player;
  • Apple Music and Classic full-screen shells;
  • Queue;
  • Play next, manual queue, and queue ordering;
  • Play, pause, previous, next, and seeking;
  • Background playback;
  • MediaSession and system media controls;
  • Lock-screen metadata;
  • Artwork and dynamic color background;
  • AutoMix dual-player preload, analysis, transition planning, tempo matching, fades, and EQ envelope;
  • 10-band equalizer from 31 Hz to 16 kHz, presets, system or player volume, and a sleep timer;
  • Shared-element player transitions, expand and collapse, and landscape player;
  • Tap the now-playing title for a glass menu to open the artist, album, or current queue;
  • Lyrics picture-in-picture with previous / play-pause / next remote actions.
  • In-app playback device picker for the phone speaker, Bluetooth, wired and USB outputs.
  • Nearby MeloX over LAN: control, cast (MeloX PCM), transfer, and listen together; see docs/MELOX-LAN.md.

Quality

NetEase playback follows the MeloX quality model:

  • Standard: standard
  • Higher: exhigh
  • Lossless: lossless
  • Hi-Res: hires
  • HD surround: jyeffect
  • Immersive surround: sky
  • Master: jymaster

The playable quality depends on the track, account entitlement, region, and the NetEase response. Unavailable targets fall back to an available resource, and the player shows the quality the server actually returned when possible.

Lyrics

  • Line-synced LRC;
  • Official word-synced YRC;
  • Current-line follow and scrolling;
  • Word-level progress;
  • Focus, scale, and color transitions;
  • Ruby layout, translation, interlude countdown, tap-to-seek, and long-press share;
  • Apple Music trailing scroll, bounce, blur, highlight, long-tone, and refresh-rate settings;
  • EVA layouts and 18 TextPV templates;
  • Skyline landscape lyrics;
  • System media lyrics, a dedicated lyric notification, and a draggable floating lyric window;
  • ColorOS lockscreen lyrics (lyricInfo) and SuperLyricApi publishing share the same lyric timeline.

HyperOS

  • Standard Android media notification and MediaSession;
  • Optional HyperOS Focus Notification / Super Island bridge;
  • OEM features live in a separate adapter and are not required on stock Android.

Social, recognition, and settings

  • Listen Together rooms, members, progress, and queue sync;
  • Contacts, conversations, text messages, and in-app sharing;
  • Microphone recording, NetEase audio fingerprinting, and continuous recognition;
  • First-run welcome and account pages, in-app release notes, in-app log viewer, sponsor acknowledgements, clipboard link detection, page ordering, and feature switches;
  • GitHub version check, update prompt, license, and settings reset.

Third-party music sources

  • Third-party sources can be enabled separately in Music Services after reading their agreement. The switch is local and is not cloud-controlled.
  • YouTube Music uses the dual-backend design from lladlam/Square. The InnerTube module is vendored at android/innertube/ from Metrolist and keeps the com.metrolist.innertube package.
  • Spotify follows the Square Spotify backend. Playback uses librespot-java; catalog and OAuth use the Spotify Web API. The user enters a Client ID in the app.
  • Spotify, YouTube Music, NetEase, and the other sources share the provider-neutral download and offline path (MeloXProviderDownloadStore).
  • vivo devices automatically try OriginOS Atomic Island. There is no separate switch. Unsupported devices keep the standard Android media notification. The adapter uses the documented local notification.superx.* extras and does not depend on EMAS push.
  • LX Music compatible JavaScript sources can be imported and resolved in a restricted QuickJS runtime.
  • A personal CHKSZ API key can be configured to resolve NetEase, QQ Music, and Kugou tracks after the current source and the built-in cross-provider fallback both fail. Register at api.chksz.com. Registration currently requires a LinuxDo account.
  • Playback order is: the current source → a strict full-audio match from another built-in source (only when "fetch unavailable resources from other platforms" is on) → configured third-party resolvers (only when that switch and its agreement are on). If every stage fails, the track is reported as unavailable instead of playing a preview.

Platform scope

iOS Live Activity and Dynamic Island map to the Android media notification, lyric notification, and optional HyperOS Focus Notification. iOS picture-in-picture lyrics map to Android's native picture-in-picture window, with the draggable floating lyric window as a fallback. Apple Watch, watchOS, and macOS targets are not part of the Android APK.

Liquid Glass uses Kyant0 AndroidLiquidGlass Backdrop. The result still depends on the Android version, GPU, and OEM compositor.

Stack

Use Android implementation
UI Kotlin + Jetpack Compose
Navigation / lifecycle AndroidX Navigation / Lifecycle
Playback AndroidX Media3 / ExoPlayer
System media controls MediaSession / MediaSessionService
Networking OkHttp
Images Coil 3
Async Kotlin Coroutines
Glass / Backdrop Kyant0 AndroidLiquidGlass / backdrop
Xiaomi extras HyperOS Focus Notification adapter

iOS to Android

MeloX / iOS MeloX Android
SwiftUI Jetpack Compose
NavigationStack Navigation Compose
AVPlayer / AVFoundation Media3 ExoPlayer
MPNowPlayingInfoCenter / Remote Commands MediaSession
Live Activity / Dynamic Island Standard media notification + optional HyperOS Focus Notification / Super Island
SwiftUI Mesh / Flowing Light Compose Canvas / dynamic color background
Apple Liquid Glass AndroidLiquidGlass Backdrop refraction, blur, and fallback

Requirements

  • Android 8.0 (API 26) or newer;
  • Android SDK 37;
  • JDK 17;
  • Gradle 9.5.0;
  • Open the android/ directory in a current Android Studio.

Some RuntimeShader and Backdrop effects need a newer Android version. Older versions use a fallback style.

Build

  1. Clone:

    git clone https://github.com/lladlam/MeloX-Android.git
cd MeloX-Android

  2. Open this directory in Android Studio:

    MeloX-Android/android

  3. Install Android SDK 37 and use JDK 17.

  4. Or build a debug APK with Gradle:

    cd android
./gradlew :app:assembleDebug --no-daemon --max-workers=2 --stacktrace

  5. Output:

     android/app/build/outputs/apk/debug/app-arm64-v8a-debug.apk
 android/app/build/outputs/apk/debug/app-armeabi-v7a-debug.apk

GitHub Actions builds a debug APK when main changes. Rolling development builds are published to the dev-latest prerelease; they are signed with Android's default debug key, so they cannot update an official release install in place. Official releases are signed with the MeloX release key described below.

Experimental CLI

Enable Settings → Experimental features → CLI mode to control playback over ADB:

python3 tools/melox_cli.py --package com.lladlam.melox.android.dev status

Supports playback controls, queue/status queries, seeking, volume, shuffle/repeat, and provider search/play. See CLI documentation for setup and commands.

Release signature

Official APKs on GitHub Releases are signed with the MeloX release certificate. SHA-256 fingerprint:

DF:CC:A9:86:5B:87:A4:02:D3:41:98:5A:48:EB:13:2B:D8:67:9D:FA:6D:9D:50:2F:36:5D:D1:62:10:A5:EB:E9

Verify with Android SDK Build Tools:

apksigner verify --verbose --print-certs MeloX-Android-0.5.3.apk

Layout

.
├── android/
│   ├── app/
│   │   └── src/main/
│   │       ├── kotlin/com/lladlam/melox/
│   │       │   ├── core/          # account, network, quality, lyrics, library
│   │       │   ├── playback/      # Media3 service and source resolution
│   │       │   ├── platform/      # HyperOS and other platform adapters
│   │       │   └── ui/            # Compose screens, player, library, glass
│   │       └── res/
│   ├── build.gradle.kts
│   ├── innertube/                  # vendored Square/Metrolist InnerTube module
│   └── settings.gradle.kts
├── .github/workflows/             # Android CI / Release
├── LICENSE
└── README.md

Credits

MeloX Android comes from the MeloX Android migration and also uses or references the projects below. Each project keeps its own license. The GPLv3 of MeloX Android does not replace those licenses.

Upstream

  • youshen2/MeloX — the original iOS / macOS MeloX, created by youshen2, and the main source of implementation, interface, interaction, and NetEase logic. Mostly GPLv3.

Direct Android dependencies

  • AndroidX / Jetpack Compose — Compose UI, Activity, Lifecycle, and Navigation. Mostly Apache License 2.0.
  • AndroidX Media3 — ExoPlayer, MediaSession, and background playback. Apache License 2.0.
  • Coil — Compose image loading. Apache License 2.0.
  • OkHttp — HTTP client. Apache License 2.0.
  • kotlinx.coroutines — coroutines. Apache License 2.0.
  • librespot-java — Spotify session, playback, and offline cache. Apache License 2.0.
  • NewPipeExtractor — anonymous YouTube Music search and stream URLs. GPL-3.0.
  • Metrolist InnerTube — signed-in YouTube Music catalog, library, and playlists. GPL-3.0, vendored at android/innertube/.
  • ONNX Runtime — on-device AutoSync lyric-alignment inference. MIT.
  • QuickJS Android — isolated runtime for LX Music-compatible source scripts. See the wrapper and QuickJS licenses.
  • ZXing — QR-code generation. Apache License 2.0.
  • Shizuku — optional non-root HyperOS compatibility integration. Apache License 2.0.

Liquid Glass

The Android app depends on the backdrop component from Kyant0/AndroidLiquidGlass. MeloXBackdropComponents.kt adapts the official LiquidButton and LiquidBottomTabs samples while keeping MeloX iOS sizes and layout.

SF Pro / SF Symbols are Apple Inc. system fonts used only for the app's icon glyphs. Normal UI text stays on XiaomiLTPro / MiLanPro. They are not covered by GPLv3; see SF-Pro-NOTICE.md.

The glass effect is still experimental.

API and UI references

Upstream MeloX references

Upstream MeloX also credits these projects. The Android port inherits parts of their lyric and NetEase work through that implementation:

Text PV / PV Tool, BeatNet, and other MeloX features keep their separate licenses and attribution as required upstream.

Contributing

Welcome to MeloX! Contributions are warmly welcome, whether you hand-craft every line or let an AI ride shotgun.

Reporting issues or suggestions

  • Prefer opening an issue on GitHub Issues.
  • If GitHub is unreachable from your network, email lladlam@outlook.com instead. Include a clear subject, a detailed description of the problem or suggestion, and screenshots and logs.

Contributing code

  1. Fork this repository. Note that the target branch is contributor, not main.
  2. Make your changes in your fork and commit them with clear messages.
  3. Open a pull request against the contributor branch.
  4. Attach a screen recording or screenshots of the change running on a real device in the PR comments.
  5. After review we merge into contributor; once it has been verified again there, it is merged into main.

Pull requests opened directly against main are detected automatically and redirected to contributor.

Contribution requirements

Changes are accepted only if they meet all of the following:

  1. No useless features — anything unrelated to music or the listening experience is not accepted.
  2. No illegal content — nothing that violates national laws and regulations, such as providing pirated music services.
  3. No breaking changes.

Disclaimer

This project is for learning, research, and open-source exchange.

  • MeloX Android is not intended to bypass payment, copyright, region locks, or NetEase service limits;
  • Users must follow local law, the NetEase Cloud Music terms, and music copyright;
  • Third-party interfaces can change, and continued availability is not guaranteed;
  • The project is provided without warranty under its license. Use is at your own risk.

License

The MeloX Android code is released under the same GNU General Public License version 3 (GPLv3) as upstream MeloX. See LICENSE.

Copying, modifying, or distributing this project requires compliance with GPLv3, including source availability, copyright notices, change notices, and same-license distribution.

Sponsors

Thank you to the following sponsors for supporting MeloX Android!

Sponsor Contribution
Afdian user_26d40 CNY 50
Afdian user_aec4c CNY 6
Bai CNY 5
中末 CNY 8.88
Afdian user_361ef CNY 20
Afdian user_f8b67 CNY 12.24

Third-party code, libraries, assets, and models keep their own licenses. Contributors retain copyright in their contributions.

Highly Recommended：Google Play 4.7 Star Android Developer Tools, Decompile, View Manifest, Open Debug Options Quickly

Apps
Android Developer Tools
Android Developer Tools Pro
About Me
Tools: TimeShining
GitHub: Trinea
Facebook: Dev Tools
AI Daily Digest
Daily AI News & Insights