GitHub/xiaomusic
1
0
Fork 0
mirror of https://github.com/hanxi/xiaomusic.git synced 2026-04-04 11:45:14 +08:00
Code Packages Releases Activity
Files
ca4ef0927d6983c593d4ea7cebd0c4e90cb44c25
xiaomusic/docs/issues/655.md
Issues Docs [BOT] 663214c298 Auto-Generate docs 🤖
2026-03-26 04:04:53 +00:00

10 KiB
Raw Blame History

title
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 Image

评论

评论 1 - hanxi

入口：

Image

搜索和推送到当前播放音箱：

Image ---

评论 2 - gdzjy

@boluofan 建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。

评论 3 - boluofan

@boluofan 建议把https://github.com/lyswhut/lx-music-mobile 的音源也兼容了吧 ，毕竟lx-music-mobile项目比MusicFree更早，有很多免费的音源。

lxmusic的插件沙箱环境不好做，暂不打算支持。 已支持，更新到作者发布的 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 链接

View Git Blame Copy Permalink