mirror of
https://github.com/hanxi/xiaomusic.git
synced 2026-04-14 20:53:41 +08:00
255 lines
10 KiB
Markdown
255 lines
10 KiB
Markdown
---
|
||
title: 在线搜索说明文档
|
||
---
|
||
# 在线搜索说明文档
|
||
## 📅 版本说明
|
||
|
||
### 🔸 V1.1.2 (最新版本)
|
||
|
||
**更新概述：**
|
||
常规优化更新。
|
||
|
||
**主要更新内容：**
|
||
1. **增加接口测试**：LX Server 配置页新增接口连通性测试功能，方便用户快速排查地址配置问题。
|
||
2. **增加歌词查询**：支持通过 LX Server 接口查询并显示歌词信息。
|
||
3. **增加密码校验**：设置界面新增密码校验功能（若未配置密码则不启用此校验），增强配置安全性。
|
||
4. **界面优化**：移除【推送】按钮，统一合并为【播放】
|
||
|
||
---
|
||
|
||
### 🔹 V1.1.1
|
||
**⚠️ 重要升级提示**
|
||
本次更新涉及配置文件结构变化。旧版用户需手动删除 `/conf/plugins-config.json` 文件，重启服务后在网页端配置即可生效。
|
||
|
||
**更新概述：**
|
||
本版本重构了底层架构，引入了双接口生态支持，并优化了搜索与播放体验。
|
||
|
||
**主要更新内容：**
|
||
1. **双接口生态架构**：
|
||
- 配置界面支持 **MusicFree 插件版** 与 **LX Server 接口版** 两种模式，用户可二选一切换。
|
||
- 新增 **LX Server 适配**，支持通过配置 API 地址接入洛雪音乐生态。
|
||
2. **功能优化**：
|
||
- **歌曲追加**：优化自动追加逻辑，支持翻页追加同歌手歌曲，实现无限连播（默认开启）。
|
||
- **搜索体验**：优化前端展示，支持服务端分页查询。
|
||
- **AI 集成**：新增 **AI 智能口令提取** 功能配置（位于高级设置）。
|
||
|
||
---
|
||
|
||
# 📘 功能说明书
|
||
|
||
## 1. 功能概述
|
||
|
||
在线搜索扩展是 `xiaomusic` 的扩展功能，旨在提供在线音乐搜索与播放功能。用户可通过网页端搜索来自多个音乐平台的资源，并灵活选择**推送至小爱音箱**或**网页端在线播放**。
|
||
|
||
系统底层支持两种独立的接口生态，用户可在后台**二选一**进行切换，以适应不同的使用习惯和资源需求。同时，提供了智能追加歌曲及 AI 提取用户口令等高级特性。
|
||
|
||
---
|
||
|
||
## 2. 接口生态选择（二选一）
|
||
|
||
用户需在后台配置页面选择其中一种模式作为当前生效的搜索源。**两者为并列关系，同一时间仅有一种生效。**
|
||
|
||
### 🅰️ 生态一：MusicFree 插件版
|
||
|
||
**核心机制**：基于插件化架构，通过加载不同的 JS 插件对接各类音乐源。
|
||
|
||
**主要特点**：
|
||
- **高度灵活**：支持订阅插件源自动更新，也可手动导入本地 `.js` 插件文件
|
||
- **精细管控**：可单独启用、禁用或卸载特定插件
|
||
- **聚合搜索**：支持在后台配置支持搜索的插件平台，根据插件排序聚合平台结果
|
||
- **权重策略**：搜索结果优先级遵循 `【歌曲名匹配度】>【歌手名匹配度】>【插件权重】`
|
||
- *注：插件权重由启用列表中的排序决定，前 9 个插件有效，排名越靠前权重越高（最高 9 分）*
|
||
|
||
**适用场景**：MusicFree生态，有相关插件和资源
|
||
|
||
### 🅱️ 生态二：LX Server 接口版
|
||
|
||
**核心机制**：基于开源的 LX Sync Server 项目，通过配置服务器地址接入。
|
||
|
||
**主要特点**：
|
||
- **配置简便**：只需填写有效的接口地址（如 `http://127.0.0.1:9527/api`）
|
||
- **聚合搜索**：支持在后台配置支持搜索的音乐平台列表，聚合平台结果
|
||
- **稳定高效**：由服务端统一维护接口逻辑，无需管理单个插件
|
||
- **新功能 (V1.1.2)**：支持接口测试与歌词查询
|
||
|
||
**适用场景**：洛雪生态，且已部署LX Sync Server相关服务
|
||
|
||
---
|
||
|
||
## 3. 主要功能特性
|
||
|
||
### 3.1 跨平台搜索与展示
|
||
|
||
- **精准搜索**：支持 `歌曲名 - 艺术家` 格式，提升匹配准确度
|
||
- **信息丰富**：结果展示标题、艺术家、专辑、时长、音质及来源平台标签
|
||
- **分页浏览**：采用服务端分页策略，每页默认 20 条，支持快速翻页及返回顶部
|
||
|
||
### 3.2 智能追加歌曲
|
||
|
||
- **自动追加（高级）**
|
||
- **功能**：当播放到歌单末尾时，自动搜索并添加**同歌手**的其他歌曲，实现无限连播
|
||
- **配置**：默认开启，可在高级设置中关闭，仅对「全部播放」模式生效
|
||
|
||
---
|
||
|
||
## 4. 语音交互与智能解析
|
||
|
||
### 4.1 新增语音口令
|
||
|
||
支持通过语音直接在线搜索 [歌曲、歌手]。
|
||
|
||
> **前置配置**：需在后台【允许唤醒的命令】选项中添加：`,singer_play,online_play,`
|
||
|
||
**在线播放指定歌曲**
|
||
- **指令格式**：`在线播放 + 关键词`
|
||
- **示例**：`在线播放 林俊杰 江南 `、` 在线播放 陈奕迅`
|
||
- **行为**：直接调用当前选定的接口生态（MusicFree 或 LX Server）进行搜索，匹配首个资源立即播放
|
||
|
||
**在线播放歌手歌单**
|
||
- **指令格式**：`播放歌手 + 歌手名`
|
||
- **示例**：`播放歌手 周杰伦`
|
||
- **行为**：搜索该歌手热门歌曲，创建临时歌单并顺序播放
|
||
|
||
### 4.2 AI 智能口令提取（高级设置）
|
||
|
||
- **功能**：利用 AI 大模型分析复杂的用户语音指令，精准提取"歌名"和"歌手名"
|
||
- **优势**：显著提高模糊指令（如"我想听那首关于秋天的歌"）的搜索命中率
|
||
- **配置**
|
||
- 默认**未启用**
|
||
- 需用户在高级设置中配置 AI 接口地址、API Key 及模型名称（留空地址默认使用阿里百炼）
|
||
|
||
---
|
||
|
||
## 5. 后台管理与配置指南
|
||
|
||
### 5.1 接口生态切换
|
||
|
||
- **操作位置**：后台配置页面的「接口生态」区域
|
||
- **切换逻辑**
|
||
- 用户可点击切换 `MusicFree` 或 `LX Server`
|
||
- 切换时系统会弹出确认提示，因为不同生态的配置项（插件列表 vs 平台列表）互不兼容
|
||
- **生效规则**：切换后，搜索功能将立即使用新选定的生态逻辑
|
||
|
||
### 5.2 详细配置项
|
||
|
||
**若选择 MusicFree 插件版：**
|
||
- **插件源管理**：编辑订阅地址，点击「更新订阅」获取最新插件列表
|
||
- **插件操作**：查看已安装插件状态，支持启用、禁用、卸载及手动上传 `.js` 文件导入
|
||
- **官方频道**：提供直达 MusicFree 官方插件市场的链接
|
||
|
||
**若选择 LX Server 接口版：**
|
||
- **地址配置**：输入有效的 API 地址，系统自动校验格式
|
||
- **接口测试 (V1.1.2)**：点击测试按钮验证地址连通性
|
||
- **平台管理**：管理支持搜索的音乐平台，支持添加或删除平台配置，实现聚合搜索
|
||
|
||
### 5.3 高级设置
|
||
|
||
- **自动追加歌曲**：开关控制，决定是否在列表播完后自动补充同歌手歌曲
|
||
- **AI 大模型配置**
|
||
- 输入框：接口地址、API Key、模型名称
|
||
- 说明：非必须功能，追求极致搜索体验的用户建议配置
|
||
- **安全设置 (V1.1.2)**
|
||
- 密码校验：可设置访问密码，保护配置界面安全
|
||
|
||
---
|
||
|
||
## 6. 常见问题
|
||
|
||
- **设备绑定**：使用推送功能前，务必在系统首页完成小爱音箱的设备绑定
|
||
- **密码校验**：密码校验功能默认未开启，如需开启请在`conf/plugins-config.json`下设置校验密码！
|
||
- **资源兼容性**：MusicFree 部分插件（如B站源）获取的音频流可能不被小爱音箱支持，此类资源建议使用**网页端播放**
|
||
- **优先级逻辑**
|
||
- 选定 **LX Server** 时：只调用 LX Server 接口
|
||
- 选定 **MusicFree** 时：调用已启用且排序靠前的 MusicFree 插件
|
||
- **语音命令配置**：自定义语音口令生效前，请检查【允许唤醒的命令】列表中是否包含 `singer_play` 和 `online_play`
|
||
<img width="509" height="102" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/aff9a971-0f88-4ff4-8042-63cef51478b1" />
|
||
## 评论
|
||
|
||
### 评论 1 - hanxi
|
||
入口：
|
||
|
||
<img width="325" height="326" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/7718a251-4419-4833-909e-3d2bf8fd7c8f" />
|
||
|
||
搜索和推送到当前播放音箱：
|
||
|
||
<img width="327" height="641" alt="Image" src="https://gproxy.hanxi.cc/proxy/user-attachments/assets/3722a302-42f4-4c16-9754-98697f1d0dfc" />
|
||
---
|
||
|
||
### 评论 2 - gdzjy
|
||
@boluofan 建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。
|
||
---
|
||
|
||
### 评论 3 - boluofan
|
||
> [@boluofan](https://github.com/boluofan) 建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。
|
||
|
||
~~lxmusic的插件沙箱环境不好做，暂不打算支持。~~
|
||
已支持，更新到作者发布的 [v0.5.0](https://github.com/hanxi/xiaomusic/releases/tag/v0.5.0)及以上版本
|
||
---
|
||
|
||
### 评论 4 - VectorZhao
|
||
用户口令智能提取没有生效，**/conf/plugins-config.json配置如下
|
||
|
||
```
|
||
{
|
||
"account": "",
|
||
"password": "",
|
||
"openapi_info": {
|
||
"search_url": "https://music-dl.sayqz.com/api/",
|
||
"enabled": false
|
||
},
|
||
"enabled_plugins": [],
|
||
"plugins_info": [],
|
||
"auto_add_song": true,
|
||
"aiapi_info": {
|
||
"base_url": "https://api.xxxxxx",
|
||
"api_key": "sk-98ALygBWge9nExxxxxxxxxxxxxxx",
|
||
"model": "gemini-3-flash-preview",
|
||
"enabled": true
|
||
}
|
||
}
|
||
```
|
||
---
|
||
|
||
### 评论 5 - mail4zc
|
||
这个 自动追加歌曲功能 如何使用，我 用在线播放 口令播放了某首歌曲，播完后可以继续追加该歌手的歌曲吗？
|
||
那个【全部播放】模式是指的什么，是全部循环吗？
|
||
---
|
||
|
||
### 评论 6 - boluofan
|
||
> 用户口令智能提取没有生效，**/conf/plugins-config.json配置如下
|
||
>
|
||
> ```
|
||
> {
|
||
> "account": "",
|
||
> "password": "",
|
||
> "openapi_info": {
|
||
> "search_url": "https://music-dl.sayqz.com/api/",
|
||
> "enabled": false
|
||
> },
|
||
> "enabled_plugins": [],
|
||
> "plugins_info": [],
|
||
> "auto_add_song": true,
|
||
> "aiapi_info": {
|
||
> "base_url": "https://api.xxxxxx",
|
||
> "api_key": "sk-98ALygBWge9nExxxxxxxxxxxxxxx",
|
||
> "model": "gemini-3-flash-preview",
|
||
> "enabled": true
|
||
> }
|
||
> }
|
||
> ```
|
||
|
||
你这个LLM模型调用是否符合 【OpenAI API 规范】，暂时只支持这个规范。详见https://cloud.tencent.com/developer/article/2546689
|
||
---
|
||
|
||
### 评论 7 - boluofan
|
||
> 这个 自动追加歌曲功能 如何使用，我 用在线播放 口令播放了某首歌曲，播完后可以继续追加该歌手的歌曲吗？ 那个【全部播放】模式是指的什么，是全部循环吗？
|
||
|
||
暂时没将配置添加到前端，只能通过修改配置文件中的属性启用：
|
||
// 启用自动添加歌曲功能
|
||
"auto_add_song": true,
|
||
|
||
【全部播放】模式就是【全部循环】，默认在线点播创建的歌单就是该模式。
|
||
---
|
||
|
||
[Issue 链接](https://github.com/hanxi/xiaomusic/issues/655)
|