MeloX Android（弥乐）

中文

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

[!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.6.5

0.6.5 adds a signed hot-update channel: UI text overrides and sandboxed QuickJS behaviour hooks delivered inside the already-signed remote config, so copy and small logic fixes no longer need an APK. Everything falls back to the built-in text and logic when consent is off, the config is unverified, or a hook fails or times out.

• 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 lladlam/MeloX.

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, and storage repair;
• 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.

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.

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.

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 guide, 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 first. Register at api.chksz.com. Registration currently requires a LinuxDo account.
• If third-party resolution fails, playback falls back to the platform's native player. Lyrics still use MeloX's own lyric path.

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 the Android floating lyric window. 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

iOS to Android

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-debug.apk

GitHub Actions builds a debug APK when main changes. Development APKs published to users are signed with the project release key and attached to the matching GitHub Release.

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

• lladlam/MeloX — upstream MeloX 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/.
• Miuix — current Backdrop / Blur experiment uses miuix-blur. 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.

The glass effect is still experimental.

API and UI references

• NEORUAA/MeiloX — Mei-based Apple Music style NetEase client used as a UI reference.
• thlucas1/SpotifyWebApiPython — Spotify Web API reference.
• bromothymolb/bilibili-api-zoku — Bilibili API reference.

Upstream MeloX references

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

• jayfunc/BetterLyrics — word-synced lyric rendering, glow, and motion;
• WXRIW/Lyricify-Lyrics-Helper — NetEase YRC parsing;
• qier222/YesPlayMusic — NetEase API and player reference.

If a later Android version migrates PV Tool, BeatNet, or other MeloX features, their separate licenses and attribution will be kept 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.

Links

• LINUX DO

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