Music Player Skill - Windows 音乐播放技能

支持 Windows 系统的音乐搜索、下载和播放。
多网关可配置：GD音乐台 → Meting → 网易云直链，顺序与地址全部可用环境变量调整。

> 本技能在 2026-09-30 做过四次本地升级（v1.1.0 → v1.2.0 → v1.3.0 → v1.4.0 → v1.5.0），改动清单见 UPGRADE_NOTES.md。
> - v1.2.0：修复「把 HTML 错误页当 mp3 保存」的老问题，加入逐版本外链探测
> - v1.3.0：接入 GD音乐台，从单源变成多源
> - v1.4.0：网关可配置（环境变量）、接入 Meting 第二网关、音源自检、封面/歌词完整化、批量下载
> - v1.5.0：老曲库升音质（upgrade_quality.py），按名称 + Live 标记匹配版本，自动替换到 320kbps

功能特性

• 🎛️ 多网关可配置 - GD音乐台 → Meting → 网易云直链，顺序可调；自建实例可解锁 QQ/酷狗/酷我/咪咕
• 🔍 搜索 - GD音乐台 + Meting + 网易云公开搜索接口
• 📥 可靠下载 - 逐个版本探测，只保存真正返回音频的版本（文件头 + 体积双校验）
• 🎯 严格选曲 - 歌名精确匹配 + 歌手本人，自动排除翻唱/DJ/伴奏/钢琴版
• 🖼️ 封面 + 歌词 - 下载时自动抓封面写进 ID3 的 APIC，歌词写进 USLT（需 mutagen）
• 📋 批量下载 - 从清单文件一次下多首，已存在的自动跳过
• ⬆️ 老曲库升音质 - 扫描已有目录，把低码率文件自动换成 320kbps，封面/歌词一并补上
• 🩺 音源自检 - sources_check.py 一条命令体检所有网关
• 🎧 本地播放 - 调用 Windows 默认播放器
• 🎵 多版本下载 - 同一首歌的不同版本/音质批量拉取
• 🔁 抗抖动 - 自动重试 + 限流识别（公共网关会软限流，返回 200 []）

快速开始

1. 安装依赖

pip install requests              # 必需
pip install --user mutagen        # 可选，用于 ID3/封面/歌词嵌入

> ⚠️ 本机注意：直接 pip install mutagen 装到系统 site-packages 会被沙箱截断，
> 导致 import mutagen 成功但 from mutagen.id3 import ... 失败。请务必加 --user。

2. 搜索并下载

# 严格模式：第一个参数是歌手，其余是歌名
python download.py 伍佰 泪桥

# 智能模式：自由搜索串
python download.py "One by One Enya"

# 指定保存路径
python download.py 伍佰 挪威的森林 "D:\music\norway.mp3"

# 下载同一首歌的多个可用版本（默认 3 个）
python download_versions.py 伍佰 挪威的森林 5

默认保存到 ~/Music/<歌手>/<歌手> - <歌名>.mp3，已存在的文件自动跳过。
成功后会顺手写封面（同目录 .jpg/.png）和 ID3 标签（含歌词）。

3. 批量下载

清单文件每行一首，三种写法都认：

# 注释行会被忽略
伍佰 挪威的森林          # 歌手 + 歌名
伍佰 - 泪桥              # 用 - 分隔
One by One Enya          # 无歌手信息 → 智能模式

python batch_download.py songs.txt
python batch_download.py songs.txt --dir "D:\Music" --sleep 1.5

4. 音源体检

音源会失效，建议隔段时间跑一次：

python sources_check.py
python sources_check.py "周杰伦 晴天"

输出示例：

音源体检 · 关键词: 伍佰 挪威的森林
==========================================================================
GD音乐台 · netease                            ✅  15.0MB audio/mpeg; charset=UTF-8
Meting · https://api.qijieya.cn/meting/    ✅  15.0MB
网易云直链 outer/url                            ✅  新id:✅ 老id:❌
==========================================================================
可用: 3 / 3
引擎顺序: gd → meting → netease

5. 把已有曲库升到 320kbps

早前下载的文件可能只有 128kbps。这个脚本扫描目录，把未达标的文件重新拉成 320kbps：

# 先看会改哪些（不下载）
python upgrade_quality.py "C:\Users\X360\Music\伍佰" --dry-run

# 真升级
python upgrade_quality.py "C:\Users\X360\Music\伍佰"

# 歌手名默认读 ID3、退回文件名；读不到时手动指定
python upgrade_quality.py "D:\Music\周杰伦" --artist 周杰伦

输出示例：

扫描 9 个文件，目标 320kbps

  ✓ 伍佰 - 白鸽.mp3        128kbps → 320kbps  14.0MB
  ✓ 伍佰 - 牵挂.mp3        128kbps → 320kbps  12.6MB
  · 伍佰 - 泪桥.mp3        320kbps 已达标
完成：升级 2，已达标 1，失败 0

版本安全：GD 搜索接口对每一行都返回 duration: 0，所以无法用时长短来对齐版本。
脚本改用归一化歌名 + Live/录音室标记匹配：标了 (Live) 的文件只接受 Live 候选，
录音室版也绝不接受 Live 候选。原来那版用时长匹配，结果 9 首全部误判为「无匹配」。

替换是原子且安全的：新文件先下到临时目录，通过 MP3 文件头 + 体积校验、
且码率确实高于原文件后，才覆盖原文件。任何一步失败都保留原文件。

6. 播放 / 手动嵌元数据

python play_music.py "C:\Users\X360\Music\伍佰\伍佰 - 泪桥.mp3"
python embed_metadata.py "歌曲.mp3" "歌名" "歌手" "专辑" "封面.jpg"

配置（环境变量，不用改代码）

音源说明

想解锁 QQ音乐/酷狗/酷我/咪咕，需按 <https://github.com/gdstudio-org/Embeat> 自建实例，
然后用 MUSIC_GD_API + MUSIC_GD_SOURCES 指过去 —— 不需要改任何代码。

GD音乐台官网 <https://music.gdstudio.xyz>。

文件说明

工作原理

为什么不能直接信任外链

网易云外链 outer/url?id=<id>.mp3 对失效 id 不报错：返回 HTTP 200，body 却是 404 HTML 页面。
原版脚本只看状态码，于是把 100KB 的网页存成了 .mp3。而且 6 位老 id（如 156374）几乎全失效。

当前解析链路

按 MUSIC_ENGINES 顺序逐个尝试，任一成功即返回：

1. GD音乐台：搜索 → 严格筛选 → types=url 取链（依次尝试 320/192/128kbps）→ 校验 audio/* 且 ≥1MB
2. Meting：搜索 → 严格筛选 → 请求其 type=url 端点（302 到 CDN）→ 同样校验
3. 网易云直链兜底：逐版本探测外链
4. 下载校验：文件必须以 ID3 或 FF FB/F3/F2 开头且 ≥1MB，否则删除并报错
5. 收尾：抓封面 → 读歌词 → 写 ID3（歌名/歌手/专辑/封面/歌词）

实测对比（伍佰）：

输出目录

~/Music/<歌手>/（即 C:\Users\X360\Music\<歌手>\）。
download_versions.py 会在文件名后附加 [歌曲id] 以避免互相覆盖。

已知限制

• ⚠️ GD音乐台公共实例只开放 netease 源，自建部署可解锁更多（用 MUSIC_GD_SOURCES 配置）
• ⚠️ 公共网关会软限流：返回 200 [] 而非报错。脚本已做退避重试，但短时间内大量请求仍可能失败
• ⚠️ GD 的 types=pic 封面接口不稳定，部分 id 返回 173 字节废图（脚本会校验并跳过）
• ⚠️ 国内镜像 music-api.gdstudio.org 在本机不可达
• ⚠️ 本机携带失效代理变量，脚本已用 session.trust_env = False 规避
• ⚠️ 下载的音乐仅供个人学习使用，请勿分发或商用

故障排除

提示音源全部失败

1. 跑 python sources_check.py 看哪一层挂了
2. 换个查询措辞（例如加专辑名）
3. 确认能直连 music-api.gdstudio.xyz、api.qijieya.cn、music.163.com
4. 该曲可能确实无可用源

提示缺少 requests

pip install requests

元数据/封面没写进去

pip install --user mutagen        # 注意 --user，否则可能装残缺

想换音源但不改代码

用上面的环境变量表即可，例如 set MUSIC_ENGINES=meting,gd 把 Meting 提到前面。

更新日志

v1.5.0 (2026-09-30，本地升级)

• ✨ 新增：upgrade_quality.py —— 把已有曲库里的低码率文件批量换成 320kbps，封面/歌词一并补齐
• ✨ 新增：版本匹配改用「归一化歌名 + Live/录音室标记」（GD 搜索的 duration 恒为 0，时长匹配不可用）
• 🐞 修复：升级过程改为「先下到临时目录 → 校验 → 原子替换」，任何一步失败都保留原文件
• 📊 实测：伍佰目录 9 首 128kbps 全部升至 320kbps，17/17 达标，总容量 129.8MB → 199.4MB

v1.4.0 (2026-09-30，本地升级)

• ✨ 新增：Meting 第二网关（api.qijieya.cn/meting/），多网关自动回退
• ✨ 新增：全环境变量配置 —— 引擎顺序、网关地址、平台源、体积下限、输出目录
• ✨ 新增：sources_check.py 音源体检、batch_download.py 批量下载
• ✨ 新增：封面抓取写进 ID3 APIC；统一歌词接口（GD lyric → Meting lrc）
• 🐞 修复：公共网关软限流（200 []）被误判为「无结果」，现自动退避重试
• 🐞 修复：歌词接口偶发 503 HTML 会被写进标签，现识别并丢弃
• ♻️ 重构：_core.py 抽出 _get/_get_json 重试层与 _run_engine 调度

v1.3.0 (2026-09-30，本地升级)

• ✨ 新增：接入 GD音乐台 作为首选音源
• ✨ 新增：多音源自动回退（GD音乐台 → 网易云直链）
• ✨ 新增：按 320/192/128kbps 依次尝试，优先高音质
• 🐞 修复：大量经典老歌此前完全无法下载（网易云直链 404）

v1.2.0 (2026-09-30，本地升级)

• 🐞 修复：下载逻辑不再把 HTML 错误页存成 mp3（文件头校验 + 体积下限）
• ✨ 新增：多版本外链探测、严格选曲规则、download_versions.py
• ♻️ 重构：公共逻辑抽到 _core.py；旧入口改为转发

v1.1.0 (2026-03-24)

• 添加 go-music-api 支持、优化音质选择、添加多版本下载

v1.0.0 (2026-03-24)

• 初始版本：网易云 API 搜索下载、本地播放

许可证

本技能仅供学习交流使用，请勿用于商业用途。