MusicFree 插件：Jamendo（开放授权 CC 音源）

一个 MusicFree 音乐源插件，数据来自 Jamendo 官方开放 API（api.jamendo.com）。 Jamendo 上的音乐全部由创作者以 Creative Commons 等开放授权发布，可合法搜索、试听、播放。

开发依据：https://github.com/maotoumao/musicfree-skills （musicfree-plugin-dev skill）

特性

• 搜索：单曲 / 专辑 / 歌手 / 歌单
• 播放：实时获取带签名的音频直链（192kbps MP3）
• 歌词（Jamendo 歌词为纯文本，插件转为整段 LRC）
• 专辑详情 / 歌手作品 / 歌单详情
• 排行榜（本周/本月热门、最新上架）
• 推荐标签（按音乐风格浏览）
• 支持导入 Jamendo 歌曲/歌单链接

安装到 MusicFree

1. 打开 MusicFree → 「我的」→「插件」→「从 URL 安装插件」
2. 填入插件文件直链（托管到 GitHub 后为 https://github.com/ghraw/<用户名>/<仓库>/<分支>/jamendo.js）
3. 安装后在插件设置中填写 Jamendo Client ID（见下）

本地验证插件本体：node test-jamendo.js（需先 npm install）

获取 Jamendo Client ID（免费，约 2 分钟）

1. 打开 https://www.jamendo.com/ 点右上角 Sign up 注册账号（邮箱即可，用于登录开发者平台）
2. 登录后打开 https://developer.jamendo.com/ ，进入 My Apps（我的应用）
3. 点 Create an App（创建应用），名称随意（如 musicfree-plugin），提交
4. 页面会显示 Client ID（一长串字母数字），复制它
5. 在 MusicFree 插件设置中把 Client ID 粘贴到「Jamendo Client ID」一栏
6. 也可以粘贴到本目录的 jamendo-client-id.txt 后运行 node test-jamendo.js 做完整自测

Client ID 是公开的应用标识符（不是密码），但仍建议只给自己的插件用。

技术说明

• 所有请求：https://api.jamendo.com/v3.0/<端点>?client_id=...&format=json&...
• 分页：Jamendo 使用 offset（必须为 limit 的整数倍），插件按 offset = (页码-1) * 30 换算
• 音频直链带时效签名，因此 cacheControl: 'no-store'，每次播放都实时获取
• 音质映射：low → mp31(128k)，standard/high/super → mp32(192k)（Jamendo 合法取值 [mp31, mp32, ogg, flac]）
• 插件运行在 MusicFree 沙箱，使用内置的 axios，无第三方依赖
• 限流说明：Jamendo API 对短时间内的密集请求会静默返回空结果（非报错）。插件已做应对：列表类方法空结果自动重试一次；播放链接空结果停顿 600ms 重试。正常"搜索→点歌→播放"的人肉节奏完全不受影响

常见问题

搜索报「未配置 Jamendo Client ID」 → 到插件设置里填写 Client ID，然后重新搜索。

搜索偶尔没结果/播放偶尔失败 → 多为 Jamendo 限流，重试即可；若持续失败请检查网络能否访问 api.jamendo.com。

为什么没有华语流行歌曲？ Jamendo 是独立音乐人开放授权平台，曲库以欧美独立音乐、电子、氛围、摇滚等为主。想听商业平台的华语 VIP 曲目属于受版权保护内容，插件不会也不应提供绕过手段。