guohuiyuan /go-music-dl

一个基于 Go 语言的全网音乐搜索与下载工具。支持 CLI 命令行与 Web 服务双模式,内置网易云、QQ、酷狗、Bilibili、汽水音乐等 10+ 个主流平台,支持多源并发搜索与无损音质解析。music-dl交流群:755087923

★ 6,549⑂ 622👁 22⑃ 21● 94▤ 43
GoAGPL-3.0Created 2026-01-18music.zkkp.nyc.mn
More from this author
Download: v1.1.7v1.1.7 ↓1.1.72026-11-16
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

Latest release

v1.1.7 v1.1.7 2026-11-16
Changelog
 056b10a6fc5f0be8aca207ec2d319bba51efbd51 为第240号问题新增测试并实现相关功能 - 为视频生成弹窗、外观预览、播放列表空状态以及下载记录新增了UI测试。 - 修改弹窗关闭逻辑,改用独立的关闭处理函数。 - 优化歌曲列表模板,可根据播放列表状态进行条件渲染。 - 改进视频生成弹窗内的音量控件,保证宽度稳定,并增加收藏与下载操作按钮。 - 重构外观设置相关的JavaScript代码,支持无需保存即可预览效果。 - 更新CSS样式,统一各组件样式,包含播放速度控件和下载记录模块。
 3c1f265b88e5d439f58dc43434d493f2a32b8f4d 优化收藏和下载功能,增加错误提示,调整模态框样式
 2153b85f09b5f305469c0b82d58cc99909e63d58 优化设置模态框的行为,确保用户选择的设置标签在配置请求完成前保持不变
 a796e6115040df153748ba6b952c974429083f88 优化音源顺序,新增音质设置功能,更新相关测试和前端逻辑
 a4741b44952bbd8ea6d5cc1466a6e3ce5697840e 修复依赖版本,更新音乐库至 v1.1.2
 6dc08cd8ae62de78caf21d242883887d24ca6923 功能:新增下载记录

Snapshot: 2026-11-17T21:58:29Z · Data license Apache-2.0 · JSON