miao-moe/Koneko_api_for_QZ-Music
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update to v0.0.4: add aggregated plugins with API failover, update docs

Browse Source
This commit is contained in:
miao-moe
2026-06-20 12:31:39 +08:00
commit c6eeb253d0
14 changed files with 7890 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

856
QZMusicV2 插件规范│QZ-Music-Plugin-Development-Guide.md Normal file
View File

@@ -0,0 +1,856 @@
# QZ Music 插件开发帮助文档
## 目录
1. [概述](#概述)
2. [核心设计原则](#核心设计原则)
3. [从 LX Music 迁移指南](#从-lx-music-迁移指南)
4. [插件基本结构](#插件基本结构)
5. [数据格式规范](#数据格式规范)
6. [示例代码详解](#示例代码详解)
7. [平台配置参考](#平台配置参考)
8. [常见问题](#常见问题)
---
## 概述
本文档用于指导开发者编写 QZ Music 音源插件。QZ Music 使用 Node.js 运行时环境，插件采用 CommonJS 模块规范，通过 `module.exports` 导出功能接口。
### 与 LX Music 的区别
| 特性 | QZ Music | LX Music |
|------|----------|----------|
| 运行时 | Node.js | JavaScript 运行时 |
| 模块规范 | CommonJS | 全局事件监听 |
| 导出方式 | `module.exports` | `send(EVENT_NAMES.inited)` |
| 通信方式 | 直接函数调用 | 事件驱动 |
| HTTP 请求 | `axios` 或内置 `httpFetch` | `globalThis.lx.request` |
### 插件类型
QZ Music 插件属于**完整音源插件**，核心功能包括：
- 搜索歌曲
- 获取音频播放 URL
- 获取歌词
- 获取歌单/专辑信息
- 获取热搜/排行榜
---
## 核心设计原则
### 1. 单平台原则（重要）
**每个插件只支持一个音乐平台**，例如：
- ✅ 网易云音乐插件（仅支持 wy）
- ✅ QQ音乐插件（仅支持 tx）
- ❌ 聚合插件（同时支持 wy + tx + kw）
**原因说明**：
```
用户向插件传配置只能通过环境变量（env）
如果插件支持多平台，切换平台时需要修改环境变量，操作繁琐
单平台插件更清晰，维护成本低，不易出现"代码屎山"
```
**如需多平台支持**：建议自建后端服务，统一处理搜索和 URL 获取，前端插件只作为代理。
### 2. 配置方式
通过 `process.env` 或插件内置的 `env` 配置读取环境变量：
```javascript
// 读取用户配置的 API 密钥
const API_KEY = process.env.API_KEY || ''
// 读取自定义服务端地址
const CUSTOM_SERVER = process.env.SERVER_URL || '默认地址'
```
### 3. 支持的音质标识
| 标识 | 说明 |
|------|------|
| `128k` | 标准音质，MP3 格式 |
| `320k` | 高品音质，MP3 格式 |
| `flac` | 无损音质，16bit FLAC |
| `flac24bit` | 无损音质，24bit FLAC |
| `hires` | 高解析度无损 |
---
## 从 LX Music 迁移指南
### 迁移对照表
| LX Music | QZ Music | 说明 |
|----------|----------|------|
| `globalThis.lx` | `require` 模块 | 不再需要全局对象 |
| `globalThis.lx.request` | `axios` 或 `httpFetch` | 使用标准 HTTP 库 |
| `globalThis.lx.env` | `process.env` | 环境变量读取方式 |
| `on(EVENT_NAMES.request, ...)` | 直接导出函数 | 改为函数导出 |
| `send(EVENT_NAMES.inited, ...)` | `module.exports` | 改为模块导出 |
| `musicInfo.songmid` | `musicInfo.id` | 字段名可能不同 |
| `info.type` | `quality` 参数 | 音质参数位置 |
### 迁移步骤
#### 步骤 1：修改模块导入
**LX Music 原代码：**
```javascript
const { EVENT_NAMES, request, on, send, env, version } = globalThis.lx
```
**QZ Music 新代码：**
```javascript
const axios = require('axios')
const crypto = require('crypto')
// 环境变量
const API_KEY = process.env.API_KEY || ''
```
#### 步骤 2：修改 HTTP 请求
**LX Music 原代码：**
```javascript
function httpRequest(url) {
return new Promise((resolve, reject) => {
request(url, { headers }, (err, resp) => {
if (err) return reject(err)
resolve(resp.body)
})
})
}
```
**QZ Music 新代码：**
```javascript
async function httpRequest(url, options = {}) {
const response = await axios({
url,
method: options.method || 'GET',
headers: options.headers,
timeout: options.timeout || 10000
})
return response.data
}
```
#### 步骤 3：修改函数导出
**LX Music 原代码：**
```javascript
// 事件监听方式
on(EVENT_NAMES.request, ({ action, source, info }) => {
switch (action) {
case 'musicUrl':
return getMusicUrl(info.musicInfo, info.type)
}
})
// 初始化事件
send(EVENT_NAMES.inited, {
status: true,
sources: musicSource
})
```
**QZ Music 新代码：**
```javascript
// 直接导出函数
module.exports = {
// 搜索功能
musicSearch,
// 获取音频 URL
getUrl,
// 获取歌词
getLyric,
// 获取歌单
songList,
// 获取专辑
album,
// 获取热搜
hotSearch,
// 插件信息
pluginInfo: {
info: { id: 'wy', name: '网易云', version: '3' },
quality: [...],
supportFunc: [...]
}
}
```
#### 步骤 4：修改返回数据格式
**LX Music 原代码：**
```javascript
// 直接返回 URL 字符串
return 'https://example.com/music.mp3'
// 或返回歌词对象
return {
lyric: '[00:00.000]歌词内容',
tlyric: '[00:00.000]翻译歌词'
}
```
**QZ Music 新代码：**
```javascript
// 搜索返回统一格式
return {
list: [{
id: '123456',
name: '歌曲名',
artists: '歌手名',
source: 'wy',
pic: '封面URL',
mPic: '中封面URL',
sPic: '小封面URL',
albumName: '专辑名',
albumId: '专辑ID',
interval: '03:45',
qualities: { '128k': '4.2M', 'flac': '35M' }
}],
total: 100,
page: 1,
limit: 20,
allPage: 5,
source: 'wy'
}
// 歌词返回格式
return {
lyric: '歌词内容',
tlyric: '翻译歌词'
}
```
---
## 插件基本结构
### 文件头部注释
```javascript
/**
* @name 网易云音乐源
* @description QZ Music 音源插件
* @version 3.0.0
* @author 开发者
* @homepage https://github.com/your-repo
* @license MIT
*
* 支持平台: 网易云音乐 (wy)
* 支持音质: 128k, 320k, flac, flac24bit, hires
*/
```
### 核心导入
```javascript
'use strict'
// 标准 Node.js 模块
const axios = require('axios')
const crypto = require('crypto')
```
### 配置区域
```javascript
// ========== 用户可配置区域 ==========
// 服务端地址（用户可通过环境变量覆盖）
const API_BASE = process.env.SERVER_URL || 'https://your-server.com'
// API 密钥（用户通过环境变量设置）
const API_KEY = process.env.API_KEY || ''
// 当前平台标识（单平台插件固定值）
const PLATFORM = 'wy' // wy: 网易云, tx: QQ音乐, kw: 酷我, kg: 酷狗, mg: 咪咕
// 支持的音质列表
const SUPPORT_QUALITIES = ['128k', '320k', 'flac', 'flac24bit', 'hires']
```
### 导出结构
```javascript
// ========== 插件导出 ==========
module.exports = {
// 核心功能（必须实现）
musicSearch, // 歌曲搜索
getUrl, // 获取音频 URL
// 可选功能
getLyric, // 获取歌词
songList, // 歌单详情
album, // 专辑详情
hotSearch, // 热搜词
tipSearch, // 搜索提示
leaderboard, // 排行榜
// 插件信息（必须）
pluginInfo: {
info: {
id: 'wy', // 平台标识
name: '网易云', // 显示名称
description: '网易云音乐插件', // 描述
version: '3' // 版本号
},
env: [ // 环境变量配置
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
],
ext: [], // 扩展功能
quality: [ // 支持的音质
{ name: '标准音质', ui: '标', id: '128k' },
{ name: '高品音质', ui: 'HQ', id: '320k' },
{ name: '无损音质', ui: 'SQ', id: 'flac' },
{ name: 'Hi-Res', ui: 'HR', id: 'hires' }
],
supportFunc: [ // 支持的功能
'search_song',
'search_playlist',
'playlist',
'album',
'lyric'
]
}
}
```
---
## 数据格式规范
### 搜索结果统一格式
```javascript
{
list: [
{
id: String, // 歌曲唯一标识
name: String, // 歌曲名（已解码 HTML 实体）
artists: String, // 歌手名（用 "、" 分隔）
source: String, // 平台标识: 'wy'/'tx'/'kw'/'kg'/'mg'
pic: String, // 大封面图 URL（500x500）
mPic: String, // 中封面图 URL（300x300）
sPic: String, // 小封面图 URL（150x150）
albumName: String, // 专辑名
albumId: String, // 专辑 ID
interval: String, // 时长 "mm:ss"
qualities: { // 音质 -> 文件大小
'128k': '4.2M',
'320k': '8.5M',
'flac': '35M',
'hires': '68M'
}
}
],
total: Number, // 总数量
page: Number, // 当前页码
limit: Number, // 每页数量
allPage: Number, // 总页数
source: String // 平台标识
}
```
### 歌词统一格式
```javascript
{
lyric: String, // 普通歌词 (LRC 格式)
tlyric: String, // 翻译歌词
qrc: String, // 逐字歌词 (QRC 格式)
roma: String // 音译歌词
}
// 注意：至少返回 lyric 或 qrc 之一
```
### 歌单详情统一格式
```javascript
{
list: [/* 歌曲列表，格式同搜索结果 */],
page: Number,
limit: Number,
total: Number,
source: String,
info: {
name: String, // 歌单名
img: String, // 封面图
desc: String, // 描述
author: String // 作者
}
}
```
### 专辑详情统一格式
```javascript
{
list: [/* 歌曲列表，格式同搜索结果 */],
page: Number,
limit: Number,
total: Number,
source: String,
info: {
name: String, // 专辑名
img: String, // 封面图
desc: String, // 描述
author: String // 艺术家
}
}
```
---
## 示例代码详解
### 完整插件模板
```javascript
/**
* @name 网易云音乐源
* @description QZ Music 音源插件示例
* @version 3.0.0
* @author 开发者
*
* 支持平台: 网易云音乐 (wy)
* 支持音质: 128k, 320k, flac
*/
'use strict'
// ==================== 核心导入 ====================
const axios = require('axios')
const crypto = require('crypto')
// ==================== 配置区域 ====================
// 平台标识（固定值，单平台插件）
const PLATFORM = 'wy'
// 服务端配置
const CONFIG = {
serverUrl: process.env.SERVER_URL || 'https://api.example.com',
apiKey: process.env.API_KEY || '',
timeout: 10000
}
// 支持的音质
const SUPPORT_QUALITIES = ['128k', '320k', 'flac']
// ==================== 工具函数 ====================
/**
* 文件大小格式化
* @param {number} size - 字节数
* @returns {string} 格式化后的字符串
*/
function sizeFormate(size) {
if (!size || isNaN(size)) return ''
if (size > 104857600) return (size / 104857600).toFixed(1) + 'MB'
if (size > 1048576) return (size / 1048576).toFixed(1) + 'MB'
if (size > 1024) return (size / 1024).toFixed(1) + 'KB'
return size + 'B'
}
/**
* 播放时间格式化
* @param {number} time - 秒数
* @returns {string} 格式化后的字符串
*/
function formatPlayTime(time) {
if (!time || isNaN(time)) return '--/--'
const m = Math.floor(time / 60)
const s = Math.floor(time % 60)
return m + ':' + s.toString().padStart(2, '0')
}
/**
* 歌手名称格式化
* @param {Array} singerList - 歌手列表
* @returns {string} 用 "、" 连接的歌手名
*/
function formatSingerName(singerList) {
if (!singerList || !Array.isArray(singerList)) return ''
return singerList.map(s => s.name || s).join('、')
}
/**
* HTML 实体解码
* @param {string} str - 含 HTML 实体的字符串
* @returns {string} 解码后的字符串
*/
function decodeName(str) {
if (!str) return ''
return str
.replace(/'/g, "'")
.replace(/"/g, '"')
.replace(/&lt;/g, '<')
.replace(/&gt;/g, '>')
.replace(/&amp;/g, '&')
.replace(/&nbsp;/g, ' ')
}
// ==================== 核心功能 ====================
/**
* 搜索歌曲
* @param {string} str - 搜索关键词
* @param {number} page - 页码，从 1 开始
* @param {number} limit - 每页数量
* @returns {Promise<Object>} 搜索结果
*/
async function musicSearch(str, page = 1, limit = 20) {
// 构造请求参数
const params = {
keyword: str,
page: page,
limit: limit
}
// 发送请求
const url = `${CONFIG.serverUrl}/search`
const response = await axios.get(url, {
params,
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
// 解析数据
const data = response.data
// 转换为统一格式
const list = data.songs.map(item => ({
id: String(item.id),
name: decodeName(item.name),
artists: formatSingerName(item.artists),
source: PLATFORM,
pic: item.picUrl || '',
mPic: item.picUrl || '',
sPic: item.picUrl || '',
albumName: decodeName(item.album?.name || ''),
albumId: String(item.album?.id || ''),
interval: formatPlayTime(item.duration),
qualities: {
'128k': sizeFormate(item.size128),
'320k': sizeFormate(item.size320),
'flac': sizeFormate(item.sizeFlac)
}
}))
return {
list,
total: data.total,
page: page,
limit: limit,
allPage: Math.ceil(data.total / limit),
source: PLATFORM
}
}
/**
* 获取音乐播放 URL
* @param {string} songId - 歌曲 ID
* @param {string} quality - 音质标识
* @returns {Promise<string>} 播放 URL
*/
async function getUrl(songId, quality) {
// 检查音质
if (!SUPPORT_QUALITIES.includes(quality)) {
quality = SUPPORT_QUALITIES[0]
}
// 发送请求
const url = `${CONFIG.serverUrl}/music/url`
const response = await axios.get(url, {
params: { id: songId, quality: quality },
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
const data = response.data
if (!data.url || !data.url.startsWith('http')) {
throw new Error('获取链接失败')
}
return data.url
}
/**
* 获取歌词
* @param {string} songId - 歌曲 ID
* @returns {Promise<Object>} 歌词对象
*/
async function getLyric(songId) {
const url = `${CONFIG.serverUrl}/music/lyric`
const response = await axios.get(url, {
params: { id: songId },
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
const data = response.data
return {
lyric: data.lyric || '',
tlyric: data.tlyric || ''
}
}
/**
* 获取歌单详情
* @param {string} id - 歌单 ID
* @param {number} page - 页码
* @param {number} limit - 每页数量
* @returns {Promise<Object>} 歌单详情
*/
async function songList(id, page = 1, limit = 20) {
const url = `${CONFIG.serverUrl}/playlist`
const response = await axios.get(url, {
params: { id, page, limit },
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
const data = response.data
// 转换歌曲列表
const list = data.songs.map(item => ({
id: String(item.id),
name: decodeName(item.name),
artists: formatSingerName(item.artists),
source: PLATFORM,
pic: item.picUrl || '',
mPic: item.picUrl || '',
sPic: item.picUrl || '',
albumName: decodeName(item.album?.name || ''),
albumId: String(item.album?.id || ''),
interval: formatPlayTime(item.duration),
qualities: {}
}))
return {
list,
page,
limit,
total: data.total,
source: PLATFORM,
info: {
name: data.name || '',
img: data.cover || '',
desc: data.description || '',
author: data.creator?.name || ''
}
}
}
/**
* 获取专辑详情
* @param {string} id - 专辑 ID
* @param {number} page - 页码
* @returns {Promise<Object>} 专辑详情
*/
async function album(id, page = 1) {
const url = `${CONFIG.serverUrl}/album`
const response = await axios.get(url, {
params: { id, page },
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
const data = response.data
// 转换歌曲列表
const list = data.songs.map(item => ({
id: String(item.id),
name: decodeName(item.name),
artists: formatSingerName(item.artists),
source: PLATFORM,
pic: item.picUrl || data.cover || '',
mPic: item.picUrl || data.cover || '',
sPic: item.picUrl || data.cover || '',
albumName: decodeName(data.name || ''),
albumId: String(id),
interval: formatPlayTime(item.duration),
qualities: {}
}))
return {
list,
page,
limit: 1000,
total: data.total,
source: PLATFORM,
info: {
name: data.name || '',
img: data.cover || '',
desc: data.description || '',
author: data.artist?.name || ''
}
}
}
/**
* 获取热搜词
* @returns {Promise<Object>} 热搜列表
*/
async function hotSearch() {
const url = `${CONFIG.serverUrl}/hotsearch`
const response = await axios.get(url, {
headers: { 'X-API-Key': CONFIG.apiKey },
timeout: CONFIG.timeout
})
return {
source: PLATFORM,
list: response.data.list || []
}
}
// ==================== 插件导出 ====================
module.exports = {
// 核心功能
musicSearch,
getUrl,
getLyric,
songList,
album,
hotSearch,
// 插件信息
pluginInfo: {
info: {
id: PLATFORM,
name: '网易云',
description: '网易云音乐插件',
version: '3'
},
env: [
{ key: 'SERVER_URL', name: '服务端地址', description: '自定义服务端地址' },
{ key: 'API_KEY', name: 'API密钥', description: '服务端API密钥' }
],
ext: [],
quality: [
{ name: '标准音质', ui: '标', id: '128k' },
{ name: '高品音质', ui: 'HQ', id: '320k' },
{ name: '无损音质', ui: 'SQ', id: 'flac' }
],
supportFunc: ['search_song', 'search_playlist', 'playlist', 'album', 'lyric']
}
}
```
---
## 平台配置参考
### 各平台标识对照表
| 平台 | 标识 | 常见歌曲 ID 字段 |
|------|------|-----------------|
| 网易云音乐 | `wy` | `id`, `songmid` |
| QQ音乐 | `tx` | `songmid`, `id` |
| 酷我音乐 | `kw` | `rid`, `id`, `hash` |
| 酷狗音乐 | `kg` | `hash`, `id` |
| 咪咕音乐 | `mg` | `copyrightId`, `id` |
| 汽水音乐 | `qx` | `id` |
### 音质支持参考
```javascript
// 各平台常见音质配置
const PLATFORM_QUALITIES = {
wy: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
tx: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
kw: ['128k', '320k', 'flac', 'flac24bit'],
kg: ['128k', '320k', 'flac', 'flac24bit', 'hires'],
mg: ['128k', '320k', 'flac', 'flac24bit'],
qx: ['128k', '320k', 'flac']
}
```
---
## 常见问题
### Q1: 如何从 LX Music 迁移到 QZ Music？
**A**: 参考本文档的"从 LX Music 迁移指南"章节，主要修改点：
1. 将 `globalThis.lx.request` 改为 `axios`
2. 将事件监听改为函数导出
3. 修改数据返回格式
4. 添加 `module.exports` 导出
### Q2: 插件加载失败怎么办？
**A**: 检查以下几点：
1. 文件语法是否正确：`node -c your-plugin.js`
2. `pluginInfo` 是否完整
3. 导出的函数名是否正确
4. 依赖模块是否已安装（如 `axios`）
### Q3: 搜索返回空结果？
**A**: 检查：
1. API 请求是否成功（查看日志）
2. 响应数据解析是否正确
3. 数据格式是否符合规范
4. 返回的 `source` 是否与平台标识一致
### Q4: 音频无法播放？
**A**: 检查：
1. `getUrl` 返回的 URL 是否有效
2. URL 是否以 `http` 开头
3. 音质标识是否正确
4. 是否有跨域或权限问题
### Q5: 用户如何配置插件？
**A**: 用户通过 QZ Music 的设置界面配置环境变量：
```
SERVER_URL = 自定义服务端地址
API_KEY = 用户的API密钥
```
插件通过 `process.env` 读取：
```javascript
const SERVER_URL = process.env.SERVER_URL || '默认地址'
```
---
## 附录
### 参考资源
- QZ Music 官方文档
- 提供的音源文件（lx&qz官方部分音源）
- Node.js 官方文档
- axios 文档
### 版本历史
- v1.0.0 (2024-05-28): 初始版本
---
**文档结束**