guohuiyuan /go-music-dl
一个基于 Go 语言的全网音乐搜索与下载工具。支持 CLI 命令行与 Web 服务双模式,内置网易云、QQ、酷狗、Bilibili、汽水音乐等 10+ 个主流平台,支持多源并发搜索与无损音质解析。music-dl交流群:755087923
★ 6,549⑂ 622👁 22⑃ 21● 94▤ 43
TA的项目
6,549
stars
622
forks
22
watchers
21
prs
94
issues
43
releases
README
Go Music DL
⭐ 如果这个项目对你有帮助,欢迎点一个 Star。
Go Music DL 是一个多平台音乐搜索与下载工具,支持 Web、TUI 和桌面端,覆盖单曲、歌单、专辑、排行榜与本地音乐。它同时暴露了一套 AI 可调用的接口——AI 可以直接操控你正开着的网页播放器,点歌、切歌、暂停、调音量都不用你动手,详见 AI / Agent 调用。
下载安装
推荐优先下载与操作系统和 CPU 架构匹配的桌面版。Rust 桌面版与 Go 桌面版均可使用,不确定时优先选择 Rust 桌面版。所有下载项也可在
GitHub Releases 查看和选择。
| 平台 | 推荐下载 | 其它版本 |
| --- | --- | --- |
| Windows x64 | Rust 桌面版 | Go 桌面版 · Rust ARM64 · Rust 32 位 · CLI x64 |
| macOS Apple Silicon | DMG 安装包 | PKG 安装包 · Go 桌面版 · CLI |
| macOS Intel | DMG 安装包 | PKG 安装包 · Go 桌面版 · CLI |
| Linux x64 | AppImage | DEB · RPM · Go 桌面版 · CLI |
| Android ARM64 | 推荐 APK | 全 ABI 兼容 APK · x86_64 模拟器 APK |
| iOS | 未签名 IPA | SHA-256 校验文件 |
Android 用户优先选择 arm64-v8a APK,只有分片 APK 无法安装时再使用全 ABI 兼容包。
iOS 的 unsigned IPA 不能直接安装,需要使用 SideStore、AltStore 或自己的开发者证书重签。
🚀 快速开始
桌面端 / 移动端
- Windows / Linux / macOS:从 Releases 下载 music-dl-desktop-rust 或 music-dl-desktop-go 对应平台包,解压后直接运行。
- Android:优先下载 music-dl_arm64-v8a.apk,已内置 FFmpeg,无需额外安装。
- iOS:使用 music-dl-ios-unsigned.ipa 自行签名。
Web / TUI
bash
Web,默认访问 http://localhost:8080/music
./music-dl web
挂载到反向代理二级目录
./music-dl web --base-path /dl
终端搜索
./music-dl -k "周杰伦"
Web 的搜索、试听、下载和歌单浏览无需登录;修改设置或 Cookie 时才需要管理员账号。首次配置时,启动日志会打印 Web setup token,用它创建管理员账号即可。TUI 常用键:↑/↓ 移动、空格 选择、a 全选、r 换源、Enter 下载、w 每日推荐、q 退出。
Docker
bash
docker compose up -d --pull always --remove-orphans
访问 http://localhost:8080。首次启动会自动创建 ./data 并配置好容器写权限;Compose 不依赖仓库里的 Dockerfile 或其他文件,只需 docker-compose.yml 和镜像即可启动。修改源码后可使用 docker compose -f docker-compose.dev.yml up -d --build 本地构建。
AI / Agent 调用
Web 服务提供 AI 能力索引和播放器控制接口。搜索、歌单、专辑、排行榜、歌单分类、换源、歌词、下载和本地音乐等能力全部复用现有的 /music/ 接口,不再维护第二套 AI 包装路由。
bash
搜索歌曲,只请求 QQ 和网易云
curl "http://localhost:8080/music/search?q=周杰伦&type=song&sources=qq&sources=netease"
API 索引:http://localhost:8080/music/api/ai/index,精简说明:http://localhost:8080/music/llms.txt。索引会列出可直接复用的现有搜索、详情、排行榜、歌单分类、换源、下载和本地音乐接口,以及新增的播放器控制接口。
AI 可以直接操控网页播放器
只要浏览器里开着本站页面,AI 就能远程操作这个页面:点歌、切歌、暂停、调音量、拖动进度,全部靠一条 HTTP 请求完成。不需要浏览器自动化、不需要模拟点击、也不需要接管你的鼠标键盘。
原理是页面自己维持着一条 SSE 长连接(GET /music/api/ai/player/events):AI 把命令 POST 到服务端,服务端推给在线的页面,页面执行后把播放状态回传。所以 AI 看到的 playing、position、current 都是页面的真实状态,而不是猜测。
典型对话:“帮我放一首 ClariS 的歌” → AI 调 /music/search 找歌 → 调 /api/ai/player/play 点播 → 轮询 /api/ai/player/state 确认已经在放。
bash
1. 看看当前有哪些播放器在线、在放什么
curl "http://localhost:8080/music/api/ai/player/state"
2. 直接点播(用 id + source,或只给 query 让服务端自己搜第一首)
curl -X POST "http://localhost:8080/music/api/ai/player/play" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"id":"1958384591","source":"netease","name":"ALIVE","artist":"ClariS"}'
3. 传输控制
curl -X POST "http://localhost:8080/music/api/ai/player/command" \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"action":"pause"}'
/api/ai/player/command 支持 play、pause、toggle、stop、next、previous、seek、volume 和 rate。没有已打开的播放器时会返回 409 player_not_connected。
多客户端:各控各的
每个打开的页面(标签页、桌面端、另一台设备)都是独立客户端,状态互不覆盖,命令互不串台:
连Top issues
#4新功能征集45 comments · 2026-02-05#240小细节还需调整14 comments · 2026-09-15#205可以增加码率过滤吗7 comments · 2026-06-09#247Mac桌面端求尽快安排一下5 comments · 2026-10-03#241bug, 下载路径和文件名对不上3 comments · 2026-09-16#263建议增加本地歌曲导入歌词2 comments · 2026-11-05#249macOS双击打开app闪退2 comments · 2026-10-08#267功能建议:外观自定义(主题三态、主色/歌词颜色自选、字体优化)1 comments · 2026-11-14
Latest release
v1.1.7 v1.1.7 2026-11-16Changelog 056b10a6fc5f0be8aca207ec2d319bba51efbd51 为第240号问题新增测试并实现相关功能 - 为视频生成弹窗、外观预览、播放列表空状态以及下载记录新增了UI测试。 - 修改弹窗关闭逻辑,改用独立的关闭处理函数。 - 优化歌曲列表模板,可根据播放列表状态进行条件渲染。 - 改进视频生成弹窗内的音量控件,保证宽度稳定,并增加收藏与下载操作按钮。 - 重构外观设置相关的JavaScript代码,支持无需保存即可预览效果。 - 更新CSS样式,统一各组件样式,包含播放速度控件和下载记录模块。 3c1f265b88e5d439f58dc43434d493f2a32b8f4d 优化收藏和下载功能,增加错误提示,调整模态框样式 2153b85f09b5f305469c0b82d58cc99909e63d58 优化设置模态框的行为,确保用户选择的设置标签在配置请求完成前保持不变 a796e6115040df153748ba6b952c974429083f88 优化音源顺序,新增音质设置功能,更新相关测试和前端逻辑 a4741b44952bbd8ea6d5cc1466a6e3ce5697840e 修复依赖版本,更新音乐库至 v1.1.2 6dc08cd8ae62de78caf21d242883887d24ca6923 功能:新增下载记录