MD3Music

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

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

公开仓库代码由脚本从上游仓库全量同步（覆盖式）；直接提交到公开仓的改动可能被下次同步覆盖。

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

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

---

🏆 Trendshift Achievements

📈 GitHub Star 趋势

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

---

✨ 功能特性

• 在线音乐 — 搜索、每日推荐、排行榜、新碟上架、听歌识曲、私人 FM、歌单/专辑/歌手/评论/MV、云盘、听书、场景音乐、频道、刷刷短视频、一起听、刷歌推荐
• 本地音乐 — 文件夹浏览、内嵌封面与歌词、本地收藏、音质标签、多维度排序、在线歌曲元数据智能匹配；Android 支持扫描系统授权目录中的 U 盘等外部存储音乐
• 播放体验 — 多音质选择（标准/高质/无损/Hi-Res）、USB 独占输出、均衡器、AutoMix 无缝过渡、响度均衡、DLNA 投屏、睡眠定时、倍速、进度记忆、画中画
• 视觉效果 — 动态封面、3D 景深封面（全功能版）、流动背景，歌曲/MV 弹幕支持透明度、速度与颜色设置
• 歌词显示 — Apple Music 风格逐字歌词（KRC/LRC），支持翻译/罗马音、辉光、模糊、动态取色，以及桌面/锁屏/蓝牙歌词与 lyricinfo lyricon词幕 SuperLyric flyme歌词 推送协议
• 用户中心 — VIP 三签到、多账号管理、听歌等级/排行/识曲、收藏与播放历史、桌面小组件
• 个性化 — MD3E/AM 双风格、主题色与动态取色、深色模式、自定义壁纸与字体；全局文字及两种播放页歌词颜色独立设置，支持双栏开关（左右各 50%）、悬浮迷你播放器与主页 Tab 管理
• 设置管理 — 设置项搜索、一键还原默认设置并保留登录状态
• Windows 桌面 — 便携版、系统托盘、SMTC 系统媒体控制、桌面歌词、全屏/沉浸式播放页，以及版本检查、镜像下载与便携版更新
• 车机模式 — 自适应播放面板、左右停靠与底部 dock 避让
• 电视端 — 遥控器焦点导航、播放/歌词/评论交互及播放队列操作
• AI 代理 — 内置 MCP 接入，支持搜索、播放控制与歌词查询，提供只读模式及写操作确认；默认关闭，支持 HTTP / stdio 桥接

---

🏗️ 架构说明

本地架构

┌────────────────────────────────────────────────────────────────┐
│                       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* 标签会自动构建并创建 GitHub Release。当前发布包共 5 个文件：4 个 APK + 1 个 Windows 便携版 ZIP：

• MD3Music-<版本>-standard-arm64-v8a.apk：Android 标准版（64 位）
• MD3Music-<版本>-apple-music-arm64-v8a.apk：Vivo 原子随身听兼容版（64 位）
• MD3Music-<版本>-tv-arm64-v8a.apk：Android TV（64 位）
• MD3Music-<版本>-tv-armeabi-v7a.apk：Android TV（32 位）
• md3music-windows-<版本>.zip：Windows 便携版

例如 v6.0.5 的以上 5 个产物可在最新 Release下载。注意：一键入口 scripts/md3.ps1 不在公开树；公开树仅保留 scripts/tasks/android.ps1、scripts/tasks/windows.ps1 和 scripts/tools/mcp_stdio_bridge.py。

---

📷 更多界面预览

手机 · 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

公开仓库没有上游仓库的一键入口 scripts/md3.ps1。在 Windows PowerShell 中直接运行公开树提供的独立构建脚本：

powershell -ExecutionPolicy Bypass -File .\scripts\tasks\android.ps1

该脚本默认构建标准版（内部 flavor lite，arm64-v8a、armeabi-v7a、x86_64）及随身听兼容版（arm64-v8a），共 4 个本地 APK，输出到 build\app\outputs\flutter-apk\；默认不构建 3D 封面和端侧分离版本。

正式发布 CI 固定提供 4 个 Android APK（标准版、随身听兼容版、TV 版 64/32 位）和 1 个 Windows ZIP，共 5 个下载文件，文件名保持本页「下载」列表中的格式。请前往 GitHub Releases 获取正式发布版本。

标准版使用内部 flavor lite，发布文件名仍为 MD3Music-<版本>-standard-arm64-v8a.apk。全功能 flavor full 仅保留手动构建能力，不进入 CI 默认构建和正式发布产物。

公开仓库仅包含 scripts/tasks/android.ps1、scripts/tasks/windows.ps1、scripts/tools/mcp_stdio_bridge.py 三个脚本文件；构建 Windows 便携版请使用 scripts/tasks/windows.ps1，而不是上游仓库的 scripts/md3.ps1。

---

📁 项目结构

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 配置

---

🛠️ 技术栈

类别	技术
UI 框架	Flutter 3.47.0+
状态管理	Provider
动效	m3e_core（M3 Expressive Motion）
音频播放	just_audio + just_audio_background
音频焦点	audio_session
网络请求	Dio
本地存储	SharedPreferences + SQLite
图片缓存	cached_network_image
嵌入式服务器	Rust（tiny_http + ureq）
加密	rsa / aes / md-5 / sha1 / sha2
DLNA 投屏	dlna_dart
MV 播放	video_player + chewie
USB 独占输出	原生 JNI + CMake C++（usbdevfs）
取色	palette_generator + dynamic_color + material_color_utilities
桌面歌词	Lyricon Provider
状态栏歌词	Flyme 状态栏 ticker（魅族私有 flag）
听歌识曲	record（录音）+ Rust PCM 预处理
原生通知	fluttertoast（Toast）
文件/权限	permission_handler + path_provider
桌面快捷方式	quick_actions
音频均衡器	just_audio 平台均衡器
音乐源	酷狗音乐 API

---

⚙️ 配置说明

嵌入式服务器

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

音质设置

音质	格式	比特率
标准	MP3	128 kbps
高质	MP3	320 kbps
无损	FLAC	~1000 kbps
Hi-Res	FLAC/MKV	~2000+ kbps

---

🛠️ 开发说明

修改嵌入式服务器代码

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: 有。可以直接从 GitHub Releases 下载 Windows 便携版 ZIP；也可以从公开源码自行构建。前置要求：

• Windows 10/11 x64 + Flutter（stable）+ Rust（stable，cargo ≥ 1.85）
• Visual Studio Build Tools 2022：勾选「使用 C++ 的桌面开发」工作负载，并额外勾选 C++ ATL 组件（flutter_secure_storage_windows 需要 atlstr.h）
• 构建期间可访问 NuGet（permission_handler_windows 需要下载相关构建依赖）

公开仓库不含 scripts/md3.ps1，请从仓库根目录直接运行独立脚本：

powershell -ExecutionPolicy Bypass -File .\scripts\tasks\windows.ps1

脚本会构建 Rust 桌面版 kugou_server.dll、Flutter Windows 应用并打包 VC++ 运行库，产物为 build\windows\md3music-windows-<版本>.zip。解压后运行 md3music.exe 即可。Android 专属功能（如 USB 独占输出、主屏小组件）在 Windows 上不可用，属预期。默认产物不含 3D 封面（kDepthCoverAvailable 为 false）；需要时加 -With3D，脚本会按固定版本下载 ONNX Runtime 运行时并把深度模型一起打进包里。

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 机型上出现（由设备能力探测决定），其他品牌不显示。

Q: 切歌提示只能看MV A: 登录过期或者没有登录

🤝 致谢

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

---

👥 贡献者

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

---

📄 许可证

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

---

Made with ❤️ by zzyoxml