A modern Material 3 music player built with Flutter & Rust.
支持 Android、Windows 与 Android TV 的 Material 3 / Apple Music 风格音乐播放器。
MD3Music 是一款基于酷狗音乐 API 的 Flutter 音乐播放器，内置嵌入式 Rust API 服务器，无需外部服务器即可使用。支持手机/平板、Windows 桌面、车机与 Android TV，提供 MD3 与 Apple Music 风格播放页、逐字歌词和多种音频输出能力。本项目仅供学习，请勿用于商业用途，详情见免责声明。
版本说明：V5 之前的所有版本与分支均已废弃并彻底删除，请勿使用过时版本。最新版请前往 GitHub Releases。
公开仓库代码由脚本从上游仓库全量同步（覆盖式）；直接提交到公开仓的改动可能被下次同步覆盖。
投屏功能声明：投屏采用行业标准的通用传输协议（DLNA/AirPlay），仅用于在个人家庭网络内将音乐流转至用户本人合法拥有的播放设备，不涉及对音乐文件的再存储、分发或向公众传播。
请勿用于公共场所播放或多人同步观看场景，否则由此引发的一切法律责任由使用者自行承担。
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 设备
项目配置了 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。
- 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。
git clone https://github.com/zzyoxml/md3Music.git
cd md3Musicflutter pub getlibkugou_server.so 已提交进 Git 仓库，通常无需重新编译。仅当你修改了 kugou_api_server/rust/src/ 下的代码时才需要重建：
# 主机编译验证
cd kugou_api_server/rust
cargo build --release
# 安卓交叉编译（4 个 ABI，需要 NDK）
./build_android.sh# 连接 Android 设备后执行
flutter run公开仓库没有上游仓库的一键入口 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。全功能 flavorfull仅保留手动构建能力，不进入 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 |
- 修改
kugou_api_server/rust/src/目录下的 Rust 源代码 - 主机编译验证：
cd kugou_api_server/rust cargo build --release cargo test # 运行测试 cargo clippy # 静态检查
- 安卓交叉编译（需要 NDK）：
./build_android.sh - 重新编译 App
在 kugou_api_server/rust/src/modules/ 下新建 .rs 文件，实现对应的 API 端点处理函数，然后在 server.rs 中注册路由即可。
若要在本地（不嵌入 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