MD3Music

MD3Music 是一款基于酷狗音乐 API 的 Flutter 音乐播放器，内置嵌入式 Rust API 服务器，无需外部服务器即可使用。支持手机/平板自适应、MD3 与 Apple Music 风格播放页、逐字歌词和多种音频输出能力。本项目仅供学习，请勿用于商业用途，详情见免责声明。

版本说明：V5 之前的所有版本与分支均已废弃并彻底删除，请勿使用过时版本。最新版请前往 GitHub Releases。

由于私有库开发同步会覆盖公开库代码，公开库代码现由脚本全量推送至公开库 rust-local-force 分支。

投屏功能声明：投屏采用行业标准的通用传输协议（DLNA/AirPlay），仅用于在个人家庭网络内将音乐流转至用户本人合法拥有的播放设备，不涉及对音乐文件的再存储、分发或向公众传播。

请勿用于公共场所播放或多人同步观看场景，否则由此引发的一切法律责任由使用者自行承担。

---

📈 GitHub Star 趋势

README 中展示的是静态趋势预览。点击图表打开开源榜交互页面后，可将鼠标悬停在曲线上查看对应日期、Stars 和单日增长。数据由 GitHub Actions 定时读取 GitHub API，并保存为仓库内的每日历史快照。

---

✨ 功能特性

• 在线音乐 — 搜索、每日推荐、排行榜、私人 FM、歌单/专辑/歌手/评论/MV、云盘、听书、场景音乐、频道、刷刷短视频
• 本地音乐 — 文件夹浏览、内嵌封面与歌词、本地收藏、音质标签、多维度排序
• 播放体验 — 多音质选择（标准/高质/无损/Hi-Res）、USB 独占输出、均衡器、DLNA 投屏、睡眠定时、倍速、进度记忆、画中画
• 歌词 — Apple Music 风格逐字歌词（KRC/LRC），支持翻译/罗马音、辉光、模糊、动态取色，以及桌面/锁屏/蓝牙歌词与 SuperLyric 推送
• 状态栏歌词 — 魅族 Flyme 机型可将当前歌词显示在状态栏，支持提前量微调
• 用户中心 — VIP 双签到、多账号管理、听歌等级/排行/识曲、收藏与播放历史、桌面小组件
• 个性化 — MD3/AM 双风格、主题色与动态取色、深色模式、全局背景图、桌面歌词、主页 Tab 自定义、设置搜索

---

🏗️ 架构说明

本地架构

┌───────────────────────────────────────────────────────────────┐
│                       MD3Music App                             │
│   ┌───────────────────────┐      ┌─────────────────────────┐    │
│   │    Flutter UI (Dart)  │      │  嵌入式 Rust API 服务器 │    │
│   │                       │      │     (127.0.0.1)         │    │
│   └───────────┬───────────┘      └───────────┬─────────────┘    │
│               │              JNI / FFI       │                  │
│               └─────────────────┬────────────┘                  │
│                                 ▼                               │
│              ┌──────────────────────────────────┐               │
│              │         本地数据 / 缓存            │               │
│              └──────────────────────────────────┘               │
└───────────────────────────────────────────────────────────────┘

核心特点

• 嵌入式 Rust 服务器 — App 启动时通过 libkugou_server.so（JNI/MethodChannel）启动本地 tiny_http 服务器（127.0.0.1），所有酷狗 API 请求在本地处理
• 高性能低资源 — Rust 实现取代旧 Node.js 方案，内存占用更低，启动更快
• 无需外部服务器 — 用户无需自行搭建 API 服务器
• 多架构支持 — 支持 armeabi-v7a（32 位）、arm64-v8a（64 位）、x86、x86_64（模拟器）
• 本地投屏支持 — 内置局域网 HTTP 服务器（支持 Range 请求），本地音乐也能投屏到 DLNA 设备

---

🔄 CI/CD

项目已配置 GitHub Actions 自动构建，推送 v* 标签即可触发：

• 自动构建 3 个架构的 APK（arm64-v8a、armeabi-v7a、x86_64）
• 自动创建 GitHub Release 并上传产物
• 自动递增 versionCode 并生成 Changelog（优先使用 CHANGELOG.md 中对应版本说明）

---

📷 更多界面预览

手机 · Apple Music 风格

手机 · 更多界面(夜间和横屏)

平板 · Material Design 3

平板 · Apple Music 风格(横屏 和 zen沉浸模式)

Flyme 状态栏歌词

🚀 快速开始

前置要求

• Flutter SDK 3.47.0 或更高版本
• Dart SDK 3.12.0 或更高版本
• Rust 1.70+（用于构建嵌入式 API 服务器，若使用已提交的 .so 可跳过）
• Android Studio / VS Code
• Android NDK 28（用于 Rust 交叉编译）

已验证构建环境：Flutter 3.47.5、Dart 3.12.x、Android NDK 28。

1. 克隆项目

git clone https://github.com/zzyoxml/md3Music.git
cd md3Music

2. 安装 Flutter 依赖

flutter pub get

3. 构建 Rust 服务器（可选）

libkugou_server.so 已提交进 Git 仓库，通常无需重新编译。仅当你修改了 kugou_api_server/rust/src/ 下的代码时才需要重建：

# 主机编译验证
cd kugou_api_server/rust
cargo build --release

# 安卓交叉编译（4 个 ABI，需要 NDK）
./build_android.sh

4. 运行应用（调试模式）

# 连接 Android 设备后执行
flutter run

5. 构建发布版 APK

# 一键打包（Rust 交叉编译按需 + Flutter 分包；默认 release / 两个 flavor / 全部 ABI）
.\scripts\md3.ps1 android

# 输出位置（产物已按中文命名，便于区分；<版本> 取自 pubspec.yaml，如 5.7.0）：
# build/app/outputs/flutter-apk/（推荐）MD3音乐-<版本>-标准版-64位.apk  (arm64-v8a，推荐默认下载项)
# build/app/outputs/flutter-apk/MD3音乐-<版本>-标准版-32位.apk      (armeabi-v7a，较旧设备)
# build/app/outputs/flutter-apk/MD3音乐-<版本>-标准版-模拟器.apk    (x86_64)
# build/app/outputs/flutter-apk/MD3音乐-<版本>-3D封面版-64位.apk    (内置 3D 深度封面)
# build/app/outputs/flutter-apk/MD3音乐-<版本>-随身听兼容版-64位.apk (Vivo 原子随身听；包名 com.apple.android.music)

中文名由打包脚本在构建完成后重命名（Flutter/Gradle 内部仍用 app-<abi>-<flavor>-<type>.apk）。 直接调用 flutter build apk --release --flavor standard --split-per-abi 得到的仍是英文原生名。

---

📁 项目结构

md3Music/
├── lib/                        # Flutter 应用代码
│   ├── main.dart               # 应用入口
│   ├── app.dart                # 主应用组件
│   ├── core/                   # 核心模块
│   │   ├── layout/             # 响应式布局
│   │   ├── services/           # 平台服务（音频/USB 独占/均衡器/DLNA 投屏/频谱/桌面歌词/词幕/小组件）
│   │   ├── theme/              # 主题配置
│   │   └── utils/              # 工具类
│   ├── data/                   # 数据层
│   │   ├── models/             # 数据模型
│   │   └── repositories/       # 数据仓库（设置/收藏/历史）
│   ├── modules/                # 功能模块
│   │   ├── home/               # 主页（每日推荐等）
│   │   ├── launchpad/          # LaunchPad 导航
│   │   ├── discover/           # 发现页
│   │   ├── charts/             # 排行榜
│   │   ├── coverflow/          # 封面流（CoverFlow 3D）
│   │   ├── player/             # 播放器（含评论视图/MV 播放）
│   │   ├── playlist/           # 歌单详情
│   │   ├── search/             # 搜索
│   │   ├── album/              # 专辑详情
│   │   ├── artist/             # 歌手详情
│   │   ├── personal_fm/        # 私人 FM
│   │   ├── ip/                 # 编辑精选
│   │   ├── audiobook/          # 听书
│   │   ├── scene/              # 场景音乐
│   │   ├── channel/            # 频道
│   │   ├── brush/              # 刷刷（竖屏视频流）
│   │   ├── user/               # 用户中心（签到/收藏/历史/听歌排行）
│   │   ├── library/            # 音乐库（本地音乐/云盘）
│   │   ├── settings/           # 设置（含均衡器）
│   │   ├── login/              # 登录
│   │   ├── onboarding/         # 新手引导
│   │   └── recognition/        # 听歌识曲
│   ├── providers/              # 状态管理
│   ├── services/               # 服务层（本地 API 客户端 / 服务器启动）
│   └── widgets/                # 公共组件
│       └── apple_lyrics/       # Apple Music 风格歌词
├── kugou_api_server/           # 嵌入式 Rust API 服务器
│   ├── rust/                   # Rust crate（tiny_http + ureq）
│   │   ├── src/
│   │   │   ├── lib.rs          # FFI/JNI 导出符号
│   │   │   ├── server.rs       # HTTP 服务器：路由分发、CORS、缓存
│   │   │   ├── modules/        # 160+ 个 API 模块
│   │   │   ├── crypto.rs       # MD5/SHA1/AES/RSA 加密
│   │   │   ├── request.rs      # 上游转发（ureq）
│   │   │   └── device.rs       # 设备信息持久化
│   │   ├── tests/smoke.rs      # 本地冒烟测试
│   │   ├── build_android.sh    # 一键交叉编译脚本
│   │   └── Cargo.toml
│   └── module/                 # 旧 JS 模块（已废弃，仅供参考）
├── img/                        # 界面预览截图（README 用）
│   ├── phone/                  # 手机：md3 / applemusic / other
│   └── pad/                    # 平板：md3 / applemusic / other
├── assets/                     # 资源文件
│   ├── images/                 # 图片资源
│   └── fonts/                  # 字体文件
├── android/                    # Android 平台配置
│   └── app/src/main/
│       ├── cpp/                # USB 独占输出 C++ 驱动（CMake）
│       ├── kotlin/             # KugouApiService（启动本地服务器）/ MainActivity
│       └── jniLibs/            # libkugou_server.so（四个架构）
└── pubspec.yaml                # Flutter 配置

---

🛠️ 技术栈

---

⚙️ 配置说明

嵌入式服务器

应用启动时自动启动本地 Rust 服务器（libkugou_server.so），监听 127.0.0.1 的随机端口（10000~60000，被占用自动更换），实际端口由服务器启动后回传给应用，无需任何配置。

音质设置

---

🛠️ 开发说明

修改嵌入式服务器代码

1. 修改 kugou_api_server/rust/src/ 目录下的 Rust 源代码
2. 主机编译验证：

   cd kugou_api_server/rust
   cargo build --release
   cargo test        # 运行测试
   cargo clippy      # 静态检查
   

3. 安卓交叉编译（需要 NDK）：./build_android.sh
4. 重新编译 App

添加新 API 模块

在 kugou_api_server/rust/src/modules/ 下新建 .rs 文件，实现对应的 API 端点处理函数，然后在 server.rs 中注册路由即可。

调试 API 服务器

若要在本地（不嵌入 App）调试 API 服务器：

cd kugou_api_server/rust
cargo test          # 本地测试

---

🔧 常见问题

**Q: 有没有Windows版本？ A: 有，由于主要开发Android版本 ，没有那么多精力再多维护windows ,不过我们在https://github.com/zzyoxml/md3Music/blob/rust-local-force/scripts/tasks/windows.ps1 提供了构建打包脚本 ，可以自行打包 ，大部分功能可用 ，少部分 失效。

Q: 应用启动后无法搜索或播放音乐？

A: 检查日志确认 Rust 服务器是否成功启动。在 Android Studio Logcat 中搜索 KugouApiService 查看启动日志。

Q: 登录功能无法使用？

A: 登录/注册/验证码已全部本地化：由嵌入式 Rust 服务器直连酷狗官方接口处理，不再依赖第三方云端。请确保设备可正常联网，并在 Logcat 中搜索 KugouApiService 确认本地服务器已成功启动。

Q: 如何修改 API 服务器代码？

A: 修改 kugou_api_server/rust/src/ 下的 Rust 代码，运行 cargo build --release 编译验证，安卓侧执行 ./build_android.sh 交叉编译，再重新编译 App。

Q: 为什么 Rust 服务器需要 NDK？

A: Rust 的 TLS 依赖（ring crate）需要交叉编译为 Android 平台的 .so 文件。NDK 提供了 aarch64-linux-android-clang 等交叉编译工具链。

Q: 设置里找不到「状态栏歌词」开关？

A: 该开关仅在魅族 Flyme 机型上出现（由设备能力探测决定），其他品牌不显示。

---

🤝 致谢

• EchoMusic — UI 设计和架构参考
• apple-music-like-lyrics — Apple Music 风格逐字歌词渲染参考
• Lyricon — 桌面歌词 Provider（词幕 / 悬浮歌词）
• SuperLyric — 系统级实时歌词（Lyricon/SuperLyric 协议）
• LyricInfo — 蓝牙歌词（AVRCP/LyricInfo 歌词推送参考）
• Lyrico — 本地音乐标签编辑 / Lyrico 外部编辑协作
• ColorOS-Live-Lyrics-Bridge — ColorOS 息屏歌词桥接（lyricInfo 开放协议参考）
• m3e_core — MD3E UI核心库
• AM-Lyrics-for-Flyme / FlymeLyricBridge — 魅族 Flyme 状态栏歌词的独立实现，用于机制交叉验证
• MaterialKolor — 莫奈取色 / Material Design 3 动态配色
• KuGouMusicApi — API 代理服务
• tiny_http — Rust HTTP 服务器
• ureq — Rust HTTP 客户端
• JAudioTagger — 音频元数据读写
• decent-player — USB 独占音频输出（DAC 独占驱动 C++/Kotlin 移植自其 decent-usb-audio-driver）
• infplayer — 自动混音（AutoMix）无缝过渡参考（BPM 自相关检测、拍点吸附、保音高变速对拍、等功率淡化曲线）
• Depth-Anything-ONNX — 深度估计模型 ONNX 导出与推理参考
• ShengChao — 3D景深封面实现参考
• MI-GAN — 3D景深封面补全模型

---

👥 贡献者

感谢所有为 MD3Music 做出贡献的朋友：

---

📄 许可证

本项目采用 GNU AGPL-3.0 许可证。

---

Made with ❤️ by zzyoxml