企业官网建设流程全解析

xiaomusic 在线搜索：三种点歌方式，让音箱不再依赖本地曲库

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

音箱只会循环本地曲库里的几百首歌？xiaomusic 的在线搜索模块可以改变这件事：网页上输入歌名，结果直接推到音箱播放；或者对着音箱喊一句歌名，它自己完成搜索和播放。下面按"先绑定、再选生态、后调参数"的顺序，把整条链路走通。

能力全景：这套模块能做什么

接口版（LX Server）额外内置了一套播放保障：音质按master → flac24bit → flac → 320k → 192k → 128k逐档降级，直链解析失败自动换下一档，跨平台还能按"歌名+歌手+时长误差≤5 秒"换源重试，核心逻辑集中在 xiaomusic/online_music.py。所有 REST 接口的路由定义在 xiaomusic/api/routers/plugin.py。

方案选型：插件生态还是自建服务

后台配置里的api_type字段决定走哪条路：1是 MusicFree 插件，2是 LX Server 接口，同一时间只有一套生效。

插件版的工作机制：JSPluginManager（管理 JS 插件生命周期的组件）拉起一个 Node.js 子进程作为沙箱，Python 端通过标准输入输出收发 JSON 消息，实现见 xiaomusic/js_plugin_manager.py。

一句话选型建议：有插件资源就选 MusicFree，想少配置多部署就选 LX。

落地配置：先绑定，再选生态，后调参数

第一步，绑定音箱。打开「小爱音箱设置面板」完成音箱绑定。所有"推送到音箱"的能力都以这一步为前提，没绑定的音箱收不到任何推送。

第二步，选择生态。进入在线搜索配置页（见 xiaomusic/static/onlineSearch/setting.html），在「接口生态」里二选一。前端会弹确认框，因为两套配置互不兼容，切了之后旧配置对另一边失效。

• 插件版：编辑订阅地址后点「更新订阅」，系统拉取订阅源 JSON 并批量下载插件；也可以手动上传本地.js文件，或直接粘贴一个http(s)://插件地址在线导入。单个插件可启用、禁用、卸载。注意启用列表的顺序：排序算法只给前 9 个插件记权重（权重 = 9 - 排名，见optimize_search_results），顺序就是你的"源偏好"。
• 接口版：填入 LX Server 的 API 地址（形如http://127.0.0.1:9527/api），点「接口测试」验证连通性；服务端开了鉴权的话，补上x-user-name与x-user-token，请求时会自动带上这两个头。最后在平台列表里增删tx、kg、kw等搜索平台，全部保留即为聚合搜索。

第三步，按需调参数。持久化都落在运行目录的conf/plugins-config.json，看懂这个骨架就够日常维护了：

"back_conf_info": {"api_type": 1}, "lx_server_info": {"base_url": "", "platforms": {"tx": "小秋音乐"}}, "music_free_info": {"enabled_plugins": [], "plugin_source": {"source_url": ""}}

完整模板可对照 xiaomusic/plugins-config-example.json。

四个进阶开关

• 自动追加歌曲（auto_add_song，默认开启）：播放到歌单末尾时自动补同歌手歌曲。
• 自动拉取并转换 LX 歌单（auto_convert）：每 30 秒同步一次，仅接口版显示；转换出的歌单带_online_lx_前缀。
• AI 口令提取（aiapi_info，默认关闭）：开启后填接口地址（留空走阿里百炼）、API Key、模型名（默认qwen-flash）。"我想听那首关于秋天的歌"这类模糊说法会先经大模型解析出歌名和歌手再搜索；解析失败或 AI 不可用时自动回退到"歌名-歌手"的-分割法。注意模型接口需符合 OpenAI API 规范。
• 语音搜单策略（voice_playlist_strategy）：default取首条，另有歌曲最多（max_songs）、播放最多（max_plays）、随机（random）。

口令搜索偏好与网页端播放

高级设置里的box_play_platform可固定搜索偏好：指定某个平台优先，填all保持聚合；两种生态各有一份此字段，互不干扰。另外，如果只是想自己听，搜索结果不推音箱、直接在搜索页播放即可——部分插件（如 B 站源）拿到的流格式小爱可能播不了，这类资源用网页端最稳。

后台还有一把可选的密码锁：password字段填非空值即启用，置空即关闭。

语音点歌链路：口令、行为、后端方法

在「允许唤醒的命令」里加上singer_play、online_play两项后，音箱就多了直接开口的能力：

想看打分细节，从 xiaomusic/online_music.py 的_search_top_one读起；语音命令的分发入口在 xiaomusic/xiaomusic.py。

疑难排查速查

另外说明一个安全细节：后端对所有在线播放地址做校验，会拒绝内网、回环、多播等地址以防 SSRF，逻辑在online_music.py的_make_request_with_validation中。

延伸资料

• 在线搜索核心业务（搜索/聚合/直链/降级/AI 解析）：xiaomusic/online_music.py
• 插件沙箱与 LX 接口管理：xiaomusic/js_plugin_manager.py
• 全部 REST 接口路由：xiaomusic/api/routers/plugin.py
• 后台配置页及脚本：xiaomusic/static/onlineSearch/
• 配置文件模板：xiaomusic/plugins-config-example.json

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