by guohuiyuan
一个基于 Go 语言的全网音乐搜索与下载工具。支持 CLI 命令行与 Web 服务双模式,内置网易云、QQ、酷狗、Bilibili、汽水音乐等 10+ 个主流平台,支持多源并发搜索与无损音质解析。music-dl交流群:1125708443
From $49 · 30 days · terms & refunds
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM lists this project for discovery and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
Automated security scan — not a certification.
# Add to your Claude Code skills
git clone https://github.com/guohuiyuan/go-music-dlGuides for using ai agents skills like go-music-dl.
Last scanned: 11/20/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-11-20T12:31:18.170Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}See how go-music-dl compares with popular alternatives.
⭐ 如果这个项目对你有帮助,欢迎点一个 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 或自己的开发者证书重签。
music-dl-desktop-rust 或 music-dl-desktop-go 对应平台包,解压后直接运行。music-dl_arm64-v8a.apk,已内置 FFmpeg,无需额外安装。music-dl-ios-unsigned.ipa 自行签名。# 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 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 本地构建。
Web 服务提供 AI 能力索引和播放器控制接口。搜索、歌单、专辑、排行榜、歌单分类、换源、歌词、下载和本地音乐等能力全部复用现有的 /music/* 接口,不再维护第二套 AI 包装路由。
# 搜索歌曲,只请求 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 就能远程操作这个页面:点歌、切歌、暂停、调音量、拖动进度,全部靠一条 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 确认已经在放。
# 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。
每个打开的页面(标签页、桌面端、另一台设备)都是独立客户端,状态互不覆盖,命令互不串台:
?client_id=xxx 声明身份;老页面匿名连上来后,第一次上报状态时会被自动认领。POST /play 和 /command 带 client_id 就只投给那一台;只有 1 台在线时自动定向,一条 curl 照样能用。client_id → 返回 409 ambiguous_client 和候选列表,绝不并发让所有页面一起切歌。GET /state 不带参数时优先选择在线、正在播放、页面可见的客户端,同类按连接顺序稳定选择,不会被 2 秒一次的状态上报带着来回跳;GET /state?client_id=xxx 精确读取某一台。last_command,查询某台不会混入其他客户端的命令。connected:false 并保留最后状态 10 分钟;定向投给它返回 409 client_not_connected。503 player_busy,不会假装投递成功。使用前提: 页面必须处于打开状态(后台标签页也能收命令,但浏览器会节流定时器,进度上报会变慢);升级后请 Ctrl+F5 硬刷新,app.js 是编译进二进制的,旧页面用不了 client_id 定向。这套接口默认无鉴权,仅靠 X-Requested-With 做 CSRF 防护,请勿把服务直接暴露到公网;远程使用请走 SSH 隧道或放在反向代理的鉴权后面。


Web 与 TUI 都支持单曲、歌单、专辑三种搜索类型;粘贴歌单或专辑链接会自动识别来源并进入详情。曲目列表支持播放、下载、批量操作和导入本地歌单。
渠道覆盖网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music、Spotify、Bilibili、Jamendo、JOOX 和千千等,实际可用来源以界面列表为准。
Spotify 不再强制要求 Cookie 或开发者凭据:歌曲、专辑、歌单搜索以及公开链接、分类、榜单、歌词和试听均可直接使用。配置 Client ID/Secret 后会自动优先官方 API;匿名 Web Player 不可用时会明确提示,不会伪装成“没有搜到”。Spotify 请求支持 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY;Windows 下未设置这些环境变量时会自动读取当前用户的静态系统代理设置。
首页“排行榜”聚合网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music 和 Spotify 的官方榜单。各平台的“热门单曲”对应当地热歌榜,榜单歌曲可直接播放、下载和批量处理。
QQ 下载需要有效 Cookie;汽水支持 Cookie + 签名获取会员整曲,签名不可用时自动回退到公开试听片段。
设置页可管理各平台 Cookie,并提供手动抓取步骤和请求域名。网易云、QQ、酷狗和 Bilibili 支持扫码登录,成功后自动保存 Cookie。
汽水音乐扫码暂不可用,需要手动配置 Cookie;会员整曲优先使用 music-lib 内置的本机签名器,也可配置可信的远程签名服务。Cookie 仅保存在本地数据目录,请勿公开分享配置文件。
默认读取 data/downloads,Android 建议使用 /sdcard/Music。支持 mp3、flac、m4a、ogg、wav、wma 和 aac。
ffprobe 补全。local 搜索源,支持分页、扫描快照、元数据缓存、后台刷新和 SQLite 索引。{name}、{artist}、{album_artist}、{album}、{source}、{id}、{ext} 等文件名模板;专辑艺人不可用时自动回退到普通艺人。下载默认走流式模式,支持 Range 断点和拖动播放。设置页可按需开启:
ffmpeg;缺失时自动跳过,不影响原始音频下载。FFmpeg 与 ffprobe 用于本地音乐探测和元数据写入。Docker 镜像和 Android APK 已内置;CLI、桌面和 iOS 包如需这些能力,请自行安装。可用 ffmpeg -version 检查。
local 搜索源,支持分页缓存、后台刷新、批量收藏、硬删除和歌单失效换源。client_id 隔离,命令定向投递、状态分槽存储,多标签页互不干扰。# 搜索
./music-dl -k "周杰伦"
TUI 常用按键:
↑/↓ 移动空格 选择a 全选/清空r 对勾选项换源Enter 下载b 返回w 每日推荐歌单q 退出更多用法:
# 查看帮助
./music-dl -h
# 指定搜索源
./music-dl -k "周杰伦 晴天" -s qq,netease
# 指定下载目录
./music-dl -k "周杰伦" -o ./my_music
# 下载时包含封面和歌词
./music-dl -k "周杰伦" --cover --lyrics
本项目已配置 GitHub Actions 工作流。当推送代码并打上版本标签(如 v1.0.0)时,会自动触发 .github/workflows/docker.yml,构建跨平台镜像(支持 amd64 和 arm64)并推送到 DockerHub。
项目支持通过 Gio 打包 Android APK,输出文件为仓库根目录下的三个 APK:
music-dl_arm64-v8a.apk(推荐,大多数 Android 设备)music-dl_x86_64.apk(x86_64 设备/模拟器)music-dl.apk(无分片兼容包,极个别设备无法使用分片包时再下载)安装 Android APK 后,建议在 Web 右上角“设置”中把“本地下载目录”改为 /sdcard/Music,这样下载文件会直接进入系统音乐目录。
前置条件:
go-music-dl is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by guohuiyuan. 一个基于 Go 语言的全网音乐搜索与下载工具。支持 CLI 命令行与 Web 服务双模式,内置网易云、QQ、酷狗、Bilibili、汽水音乐等 10+ 个主流平台,支持多源并发搜索与无损音质解析。music-dl交流群:1125708443. It has 6,627 GitHub stars.
Yes. go-music-dl passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/guohuiyuan/go-music-dl" and add it to your Claude Code skills directory (see the Installation section above).
go-music-dl is primarily written in Go. It is open-source under guohuiyuan on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh go-music-dl against similar tools.
No comments yet. Be the first to share your thoughts!