# MD3Music: a Flutter and Rust Kugou client that runs its own API server on the phone

> MD3Music is an Android music player built on the Kugou API, with a Flutter interface and an embedded Rust server that answers requests on 127.0.0.1. It is aimed at people who want Kugou catalogue features without standing up a separate API server, and it is licensed AGPL-3.0.

**zzyoxml/md3Music** — 酷狗概念版 第三方音乐播放器 Flutter + Rust   

- Repository: https://github.com/zzyoxml/md3Music
- Stars: 729 · Forks: 31
- Language: Dart
- License: AGPL-3.0
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/zzyoxml-md3music

## A Kugou client that carries its own backend

The usual pattern for a third-party music client is a thin app plus a separate API server that the user has to host somewhere. MD3Music removes that second piece. The README describes an embedded Rust API server that starts with the app and listens on 127.0.0.1, so all Kugou API requests are handled inside the process on the device. The stated motivation is explicit: users should not have to set up an API server themselves.

The audience is narrow and clear. This is an Android application. The README's platform badge says Android, the build instructions target Android NDK 28, and the release APKs are split per ABI. There is no iOS or desktop target in the README. Feature coverage is broad: online search, daily recommendations, charts, personal FM, playlists, albums, artists, comments, MV, cloud drive, audiobooks, scene music, channels, and a vertical video feed, plus local folder browsing with embedded covers and lyrics. If you want a Kugou front end with that surface area, this is the kind of project you are looking for. If you want a general-purpose local player, the Kugou dependency is dead weight.

## Flutter UI, Rust server, and a JNI bridge between them

The architecture diagram in the README is a two-box picture. On one side sits the Flutter UI written in Dart. On the other sits the embedded Rust API server bound to 127.0.0.1. The two talk over JNI or FFI, and both sit above a shared local data and cache layer.

The mechanism is worth spelling out. The native library is named libkugou_server.so, and the README says the app starts a local tiny_http server through it at launch, using JNI or MethodChannel. Kugou API calls are then processed locally rather than forwarded to a remote host. The README compares this to the project's earlier Node.js approach and states that the Rust implementation uses less memory and starts faster. Those are the project's own claims about its own rewrite; no benchmark numbers are published, so treat the comparison as a design intent rather than a measured result.

There is a second server in the picture. For casting, the project embeds a LAN HTTP server that supports Range requests, which is what lets local music be sent to DLNA devices. So the app can run two listeners: the loopback API server and a LAN-facing media server. The four supported ABIs are armeabi-v7a, arm64-v8a, x86, and x86_64, with x86_64 covering emulators.

## Building MD3Music from source and running it on a device

The README gives a full build path. Prerequisites are Flutter SDK 3.12.0 or later, Rust 1.70+ if you rebuild the server, Android Studio or VS Code, and Android NDK 28 for Rust cross-compilation. Clone the repository and fetch the Dart dependencies first.

```bash
git clone https://github.com/zzyoxml/md3Music.git
cd md3Music
flutter pub get
```

Rebuilding the Rust server is optional. The README states that libkugou_server.so is already committed to the Git repository, so the normal path is to skip this step entirely. Only changes under kugou_api_server/rust/src/ require a rebuild. If you do need one, the same directory offers a host build for validation and a script for the Android cross-compile across four ABIs.

```bash
cd kugou_api_server/rust
cargo build --release
./build_android.sh
```

With a device connected, flutter run starts the debug build. For a release build the README uses split-per-abi, which produces three APKs in build/app/outputs/flutter-apk/: app-armeabi-v7a-release.apk for 32-bit, app-arm64-v8a-release.apk for 64-bit, and app-x86_64-release.apk for emulators.

```bash
flutter build apk --release --split-per-abi
```

One caveat about the source itself: the README says the public repository is overwritten by a script that pushes code from a private repository, and that the public code is now pushed in full to the rust-local-force branch. If you clone the default branch and the tree looks different from the releases, that note explains why.

## Where MD3Music breaks down

The dependency on Kugou's API is the first limitation, and it is not a small one. Every online feature, from search to daily recommendations to comments, is served through that API. If Kugou changes an endpoint or a signing scheme, the app's online half stops working until the embedded Rust server is updated. The README does not document any fallback, offline mode for online content, or endpoint health check. The local music side is unaffected by this, but the local side is not why most people would pick this app.

The second limitation is the platform. Android is the only target described. Flutter supports other platforms, but nothing in the README, the build commands, or the release artifacts suggests an iOS, Windows, macOS, or Linux build exists.

The third is the build chain. Rust 1.70+, Flutter 3.12.0+, and Android NDK 28 are three separate toolchains, and the README does not document version pinning beyond those minimums. The README also does not describe rollback, migration, or what happens to local data when you move between versions. The disclaimer is blunt about scope: the project is stated to be for study, not for commercial use, and the casting note puts responsibility for public playback on the user.

## How it differs from a plain local player

The obvious comparison is with a local-only player such as a simple folder-based Android music app. That kind of player reads your files, shows embedded tags and covers, and stops there. MD3Music also does local folder browsing with embedded covers, lyrics, quality labels, and multi-dimensional sorting, so the local feature set overlaps. The difference is everything above it: the Kugou catalogue, account features such as dual VIP check-in and listening rank, and the lyric pipeline.

That lyric pipeline is where the project spends visible effort. It handles KRC and LRC, renders Apple Music style word-by-word lyrics with translation and romanization, and adds glow, blur, and dynamic color. It also pushes lyrics to desktop, lock screen, Bluetooth, and SuperLyric. A local-only player typically renders plain LRC and stops. If word-level timing and translation are what you care about, this project targets that directly.

The second comparison is with the older generation of third-party Kugou clients that required a self-hosted API server. Those shift the operational burden to the user: you run a server, you keep it updated, you expose it on your network. MD3Music inverts that by embedding the server in the app and binding it to loopback. The trade-off is that you can no longer update the API layer independently of the app. When Kugou changes something, you wait for a new APK rather than patching your own server.

## Maintenance, releases, and the AGPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-17, the same day as the v5.6.5 release. Releases are frequent: v5.5.0 on 2026-09-05, v5.6.0 on 2026-09-15, and v5.6.5 on 2026-09-17. The README also describes GitHub Actions automation where pushing a v* tag builds three APK architectures, creates a GitHub Release, increments versionCode, and generates a changelog that prefers the matching entry in CHANGELOG.md.

The README carries a version warning worth taking literally: all versions and branches before V5 are described as abandoned and deleted, and users are told to get the latest from GitHub Releases. That means old tutorials, old forks, and old APKs are not just stale, they are unsupported by the project's own statement.

On licensing, the repository is AGPL-3.0. The network copyleft clause matters here because the app runs an HTTP server, even if it is bound to 127.0.0.1. Anyone who modifies and distributes this code, or runs a modified version as a network service, should read the licence text and DISCLAIMER.md rather than assume the AGPL behaves like a permissive licence. This is not legal advice; the licence file and the disclaimer are the authoritative sources.

## Conclusion

MD3Music fits Android users who want a Kugou client with Material Design 3 and Apple Music style lyrics, and who are comfortable building a Flutter app from source or installing a release APK. It does not fit anyone who needs iOS, a desktop build, or a player that does not depend on Kugou's API. Before adopting it, check the rust-local-force branch for the current code, confirm whether the committed libkugou_server.so matches the Rust sources under kugou_api_server/rust/src/, and read DISCLAIMER.md, because the repository states the project is for study and not for commercial use.

## FAQ

### Does MD3Music need a separate API server?

No. The README states that the app starts an embedded Rust server on 127.0.0.1 through libkugou_server.so, so Kugou API requests are handled locally and the user does not have to set up an external server.

### Which platforms does MD3Music support?

The README lists Android as the platform and describes builds for armeabi-v7a, arm64-v8a, x86, and x86_64, with the x86_64 build aimed at emulators. No iOS or desktop target appears in the README.

### Do I need to compile the Rust server to run MD3Music?

Usually not. The README says libkugou_server.so is already committed to the Git repository, and rebuilding is only needed if you change code under kugou_api_server/rust/src/.

### What licence is MD3Music released under?

The repository is licensed AGPL-3.0. The README also states the project is for study and asks that it not be used commercially, with details in DISCLAIMER.md.

## Sources

- [Issues](https://github.com/zzyoxml/md3Music/issues)
- [License: AGPL-3.0](https://github.com/zzyoxml/md3Music/blob/rust-local-force/LICENSE)
- [README](https://github.com/zzyoxml/md3Music/blob/rust-local-force/README.md)
- [Releases](https://github.com/zzyoxml/md3Music/releases)
- [zzyoxml/md3Music on GitHub](https://github.com/zzyoxml/md3Music)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zzyoxml-md3music