企业官网建设流程全解析

xiaomusic在线搜索插件：语音点歌实战选型指南

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic

xiaomusic 是让小爱音箱播放音乐的工具，它的「在线搜索」扩展能让你在网页端直接搜各大音乐平台的歌曲，推给音箱播放，也能在网页在线播放，还支持语音点歌和 AI 口令提取。无论你已经搭好 LX Server，还是想直接开箱用聚合曲库，这篇指南都能帮你一次配通。

两种接口生态怎么选：MusicFree 插件还是 LX Server

这一节你会花一分钟选对搜索源生态。后台配置页的「接口生态」区域是两个互斥选项，同一时间只生效一种。

• 插件权重：启用列表前 9 个插件有效，排名越靠前权重越高，聚合结果按「歌曲名匹配度 > 歌手名匹配度 > 插件权重」排序。
• LX 音质：按 母带 > flac24bit > flac > 320k > 192k > 128k 依次降级；解析失败自动跨平台找时长误差 ≤5 秒的同歌换源。

如果你已经部署了 LX Sync Server，或本来就是洛雪生态用户，选 LX Server 接口版，填地址即生效；如果你只是想让音箱尽快能聚合搜歌、没有任何现成部署，选 MusicFree 插件版，订阅官方源就能用。

上手配置：两条完整路径

这一节你跟着屏幕一步步做完全部配置，入口都在后台配置页。

MusicFree 插件版：从订阅到聚合搜索

1. 在「接口生态」区域选中 MusicFree 插件
   • 目的：把系统切到插件生态。
   • 踩坑提示：从 LX Server 切过来会弹确认提示，两套配置互不兼容，别中途来回切。
2. 填插件订阅源地址，点「更新订阅」
   • 目的：系统会请求订阅源、校验其中的plugins数组后批量下载插件。
   • 踩坑提示：先确认订阅源地址可访问且返回合法 JSON，否则整批下载失败。
3. 按需上传或在线导入插件
   • 目的：补充搜索源，可手动传.js文件，也可直接粘贴 http(s) 插件地址导入。
   • 踩坑提示：只收.js；文件名不能是 ALL / all / OpenAPI / OPENAPI 这些保留字段；同名插件不能重复传。
4. 整理启用列表的排序
   • 目的：启用顺序就是聚合搜索优先级，前 9 个插件参与权重计算。
   • 踩坑提示：没启用的插件不参与搜索，启用列表为空时搜不到任何结果。

LX Server 接口版：填地址、测接口、选平台

1. 先自行部署 LX Sync Server
   • 目的：xiaomusic 本身不带曲库，接口版完全依赖这台自建服务。
   • 踩坑提示：先做这一步，否则后面「接口测试」必然不通；LX Server v1.8.2 之后接口加了 Token 限制，建议暂时别升到该版本。
2. 填接口地址并点「接口测试」
   • 目的：系统会请求${base_url}/music/config，校验返回中是否含player.enableAuth、user.enablePublicRestriction字段来判定合法性。
   • 踩坑提示：地址形如http://127.0.0.1:9527/api；测试不通过先查网络连通性和服务端版本。
3. 填认证信息（V1.1.3+）
   • 目的：系统请求 LX Server 时会自动带上x-user-name、x-user-token两个请求头，避免鉴权被拒。
   • 踩坑提示：只填了名字没填 Token 等于没认证。
4. 管理平台列表
   • 目的：搜索时系统会并行请求所有保留的平台（如tx、kg、kw、wy、mg）再合并结果。
   • 踩坑提示：只留你需要的平台，平台越多聚合越慢。

语音点歌实战：两条口令立即可用

这一节你会让音箱「开口即唱」，不用打开网页。下面是操作面板示意：

前置检查清单：

• 后台「允许唤醒的命令」列表里已加入online_play和singer_play
• 已在「小爱音箱设置面板」完成音箱绑定
• 二选一生态已配好：MusicFree 插件已启用，或 LX Server 接口测试通过

💡 AI 增强：高级设置里可开启大模型提取「歌名/歌手」，让模糊指令（如"我想听那首关于秋天的歌"）也能命中；接口地址留空默认用阿里百炼，模型默认qwen-flash；接口需符合 OpenAI API 规范，AI 不可用时自动回退「歌名 - 歌手」分割。

进阶开关速查：高级设置一览表

这一节你会知道哪些开关值得动、动了会怎样。

配置字段速查：plugins-config.json 关键字段

这一节你即使直接改文件也知道去哪改。全部在线搜索配置集中在conf/plugins-config.json（首次启动由插件配置模板生成）：

{ "password": "", "auto_add_song": true, "aiapi_info": { "enabled": false, "api_key": "" }, "back_conf_info": { "api_type": 1 }, "lx_server_info": { "base_url": "", "x-user-name": "", "x-user-token": "", "auto_convert": false, "box_play_platform": "all" }, "music_free_info": { "enabled_plugins": [], "plugin_source": { "source_url": "" }, "box_play_platform": "all" }, "voice_playlist_strategy": { "value": "default" } }

避坑与排查：常见报错怎么办

这一节你会不用翻代码就处理掉绝大多数问题。

⚠️ 硬约束（违反会直接报错或不可用）：

• LX Server v1.8.2 之后接口增加 Token 限制，暂时别升级该版本，等 onlineSearch 适配
• AI 口令提取只支持符合 OpenAI API 规范的大模型接口
• 遇到变更配置文件结构的版本升级（如 V1.1.1 重构），需手动删除conf/plugins-config.json，重启后在网页端重新配置

一般提醒：

• LX 接口生态无法播放：按 issues/811 处理方案 逐项排查。
• 平台歌单同步到音箱播放：参见 issues/807 方案讨论；注意 LX 歌单转换出的 XM 歌单（_online_lx_前缀）需切到 LXServer 生态才能用。
• AI 口令提取不生效：确认aiapi_info里enabled为true且api_key非空。
• 密码锁默认未开启；password置空即解锁、非空即启用，忘记密码改文件重置。
• MusicFree 的 B 站源等插件资源可能不被小爱音箱支持，这类歌改用网页端在线播放。
• 安全机制：系统会拒绝内网、回环、链路本地、多播等地址的在线 URL 以防范 SSRF（服务器端请求伪造），属正常拦截，不要试图绕过。

资源索引：源码与文档在哪看

这一节你会按用途快速定位到对应文件。

• xiaomusic/online_music.py — 搜索、聚合、播放直链、SSRF 防护
• xiaomusic/js_plugin_manager.py — 插件沙箱、LX 接口请求、自动转换
• xiaomusic/api/routers/plugin.py — 在线搜索相关 REST 接口
• xiaomusic/static/onlineSearch/setting.html — 后台配置页
• xiaomusic/static/onlineSearch/index.html — 在线搜索页
• xiaomusic/plugins-config-example.json — 配置文件模板

【免费下载链接】xiaomusic使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic