xiaomusic 在线搜索完整配置指南MusicFree 与 LX Server 双生态从入门到语音点歌【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusicxiaomusic 的在线搜索能让你不靠本地曲库直接从小爱音箱里点单全网音乐。本文带你用最快速度配通接口讲清 MusicFree 插件生态与 LX Server 接口生态的选型逻辑再覆盖语音点歌口令、AI 口令提取、自动追加歌曲这些进阶玩法配完即可实现动口不动手的在线听歌体验。一、为什么需要在线搜索先想一个问题小爱音箱说播放周杰伦它到底播哪首xiaomusic 默认从本地曲库选歌。曲库用 yt-dlp 下载但歌曲得先躺在硬盘里音箱才会播。你没下过的歌它就真的没有。在线搜索就是给这个短板打了个补丁。它不依赖本地硬盘直接调用后台配置好的接口去互联网音乐源里搜歌把搜到的结果打包成歌单推到你的小爱音箱上播放。可以把它想象成点外卖本地曲库是你家冰箱在线搜索则是把需求丢给外卖平台——平台替你在各家商家音乐平台里挑好菜音频打包送到你的音箱门口。更省事的是它不只支持在网页上点。你还能对着音箱说在线播放 林俊杰 江南它就自己去搜、自己去播。这就是本文要带你配完的全部能力。二、快速上手十分钟内让音箱播上在线歌曲 目标只有一个让一首歌在线搜出来、在小爱音箱里响起来。跟着走就行。第 1 步部署并启动 xiaomusic。仓库地址是 https://gitcode.com/GitHub_Trending/xia/xiaomusic 拉下来后按项目说明安装依赖并启动确认网页端能打开。第 2 步绑定音箱。打开「小爱音箱设置面板」完成音箱绑定。这一步是音箱推送播放的前置条件不做这一步后面搜得再准也播不出来。第 3 步进入在线搜索后台配置页。在线搜索有独立的后台入口对应仓库里的xiaomusic/static/onlineSearch/setting.html。页面顶部就是「接口生态」选择区。第 4 步二选一配通接口。手里已有 LX Sync Server选LX Server 接口版填入你的 API 地址形如http://127.0.0.1:9527/api点「接口测试」连通即通过。更习惯用插件选MusicFree 插件版填插件订阅地址点「更新订阅」把至少一个插件启用。⚠️ 两种生态互斥同一时间只有一种生效。切换时会弹确认提示因为两边的配置项互不兼容。第 5 步打开在线搜索页搜一首歌。结果列表会显示歌曲标题、艺术家、专辑、时长、音质和来源平台标签默认每页 20 条可以翻页。第 6 步选播放方式。搜到目标歌曲后你有两个选择推送到小爱音箱命中后构造临时歌单推给你已绑定的音箱播放网页端在线播放不经过音箱直接在当前网页里播音频流。走到这里第一条在线歌曲应该已经在你的音箱里响了。三、接口选型决策表MusicFree 还是 LX Server在线搜索的底层支持两套并列且互斥的接口生态。选哪个取决于你手上有什么资源。先看选型对比表对比项MusicFree 插件版LX Server 接口版工作原理加载不同 JS 插件各自对接不同音乐源接入一套 LX Sync Server由服务端统一管理接口逻辑要准备什么插件订阅源或本地.js插件文件一个能访问的 LX Server API 地址配置复杂度要管理插件的订阅、启停、上传填地址即可可选填认证信息聚合搜索方式并行调用所有已启用插件每插件限额按limit // 插件数分配再统一排序并行请求所有已配置平台合并排序搜索权重策略启用列表的排序决定插件权重前 9 个插件有效排第一权重最高9 分无插件权重按平台聚合运行方式Python 端启动一个 Node.js 子进程作为插件沙箱node js_plugin_runner.js通过标准输入/输出收发 JSON 消息直接向配置的地址发 HTTP 请求适合谁手上有可用 MusicFree 插件资源的人已经部署了 LX Sync Server 的人对应到配置conf/plugins-config.json里back_conf_info.api_type取值1代表 MusicFree 插件2代表 LX Server 接口切换走POST /api/back-conf/update这个接口。选项 ALX Server 接口版——省心的托管式方案你只需要一个有效地址搜索、取直链全由服务端完成。从源码看这套生态内置了一整套播放保障机制值得了解音质优先级链master、flac24bit、flac、320k、192k、128k从高到低排列优先按你的偏好选偏好无效就依次降级解析失败自动降档某一档音质直链解析失败自动换下一档再试跨平台自动换源原始平台解析失败时按歌名 歌手 时长误差 ≤ 5 秒到其他平台找同一首歌再尝试播放播放前缓存检查先请求${base_url}/music/cache/check命中缓存直接返回缓存 URL没命中再走 SSE 进度接口配合${base_url}/music/url异步解析直链相对地址补全服务端返回相对路径时自动拼接base_url补成完整可播 URL。另外它还有几个版本相关的细节接口测试V1.1.2点「接口测试」按钮后端请求${base_url}/music/config校验返回字段player.enableAuth、user.enablePublicRestriction来确认这是不是合法的 LX Server 接口认证鉴权V1.1.3可配置x-user-name与x-user-token请求时自动附加这两个请求头歌词查询V1.1.2调用${base_url}/music/lyric获取歌词。⚠️ 版本兼容提醒LX Music Sync Server v1.8.2 之后给接口加了 Token 限制。如果你要用 LX Server建议暂时不要升级到该版本等 onlineSearch 新版适配。选项 BMusicFree 插件版——灵活的自助餐方案插件化架构的精髓是想接哪个音乐源就上哪个插件。插件的获取方式有四种订阅更新编辑订阅地址后点「更新订阅」系统请求订阅源 JSON校验其中包含plugins数组后批量下载插件手动上传只收.js文件文件名不能撞保留字段ALL、all、OpenAPI、OPENAPI同名插件不允许重复上传在线导入直接粘贴一个http(s)://插件地址远程拉取单个插件单个管控启用、禁用、卸载分别走PUT /api/js-plugins/{name}/enable|disable和DELETE /api/js-plugins/{name}/uninstall。插件文件放在配置目录的js_plugins/文件夹元数据记录在conf/plugins-config.json的music_free_info节点下。搜索时插件如何分工所有已启用插件并行搜索每个插件分到的配额是limit // 插件数最后把各路结果统一排序。排序的核心优先级是歌曲名匹配度 歌手名匹配度 插件权重。插件权重由启用列表的排序决定只有前 9 个插件的权重参与计分排第一的拿 9 分。⚠️ 兼容性提醒MusicFree 部分插件比如 B 站源拿到的音频流可能不被小爱音箱支持这类资源建议改走网页端播放。搜索本身还有两个小能力精准搜索支持歌曲名 - 艺术家的写法后端会以第一个-为界拆开关键词和歌手匹配更准分页浏览服务端分页默认每页 20 条支持快速翻页和返回顶部。四、实战配置按你的使用场景来配置页上的项目很多但按场景分组后其实就四组。哪组跟你有关就看哪组。场景 1选了 LX Server 接口版在 LX Server 配置区填这几项其余保持默认字段作用默认值base_urlLX Server 的 API 地址例http://127.0.0.1:9527/api空x-user-name鉴权用户名V1.1.3请求时作为请求头附加空x-user-token鉴权 TokenV1.1.3同上空platforms参与聚合搜索的平台字典key 为平台标识value 为展示名内置tx小秋音乐、kg小枸音乐、kw小蜗音乐、wy小芸音乐、mg小蜜音乐box_play_platform语音口令搜索时偏好的平台all表示全部聚合allauto_convert是否每 30 秒自动拉取 LX 歌单并转成 XM 歌单关闭填完地址点「接口测试」确认连通性再按需要增删platforms里的平台聚合搜索就齐了。场景 2选了 MusicFree 插件版MusicFree 配置区对应的是插件的订阅—安装—排序三步字段作用默认值music_free_info.plugin_source.source_url插件订阅源地址点「更新订阅」后从这里拉插件列表空music_free_info.enabled_plugins已启用的插件列表顺序即权重顺序前 9 个参与权重计分空列表music_free_info.plugins_info已安装插件的信息记录空列表music_free_info.box_play_platform语音口令搜索时偏好的插件平台all为聚合all后台还提供了一个直达 MusicFree 官方插件市场的入口按钮找插件时可以从那里进。场景 3想让语音口令直接搜歌这是在线搜索最有意思的部分。开启它一共三步第一步进入 xiaomusic 的后台设置找到「允许唤醒的命令」选项第二步在现有列表基础上追加三个口令标识,singer_play,online_play,online_playlist_play第三步对着音箱直接说口令指令格式示例系统行为在线播放指定歌曲在线播放 关键词在线播放 林俊杰 江南用当前选定生态搜索给结果打分歌名完全匹配 90、开头匹配 70、结尾 50、包含 30歌手名匹配按 9/7/5/3 递减取最高分那首播放播放歌手歌单播放歌手 歌手名播放歌手 周杰伦搜该歌手热门歌曲生成_online_歌手名临时歌单顺序播放在线歌单歌单搜索口令见上表口令设置搜歌单列表按策略挑一个最优歌单拉取全量歌曲推到音箱播放⚠️ 口令生效的前提是「允许唤醒的命令」列表里确实包含了对应标识。配完不生效十有八九是这一步漏了。补充一句歌单搜索口令和歌手口令的文案本身也可以改后台有「在线播放口令」「在线搜索歌单口令」「播放歌手口令」三个输入项默认分别是在线播放、在线歌单,搜索歌单、播放歌手但命令标识也就是上面那串逗号分隔的内容别漏。场景 4想锁住后台配置页在线搜索后台默认是裸奔的谁打开都能改。想加一道锁V1.1.2打开conf/plugins-config.json把顶层的password字段填成你想用的密码之后进后台前端会先请求GET /api/password/check返回required: true就弹密码框输对了POST /api/password/verify才放行忘密码了就把该字段重新改对置空即关闭密码锁。五、进阶能力按需开启的增强项以下四项都是可选项默认关闭或默认值已经够用想用哪个开哪个。AI 智能口令提取解决什么问题模糊指令比如我想听那首关于秋天的歌传统拆词法很难命中。原理后端_parse_keyword_with_ai读取aiapi_info配置当enabled为true且api_key非空时调用 AI 大模型从语音里提取歌名和歌手名解析失败或 AI 不可用自动回退到歌名-歌手的传统分割方式功能不会断。怎么开在高级设置里填三项——是否启用 AI、接口地址留空默认走阿里百炼、API Key 和模型名默认qwen-flash。配置示例aiapi_info: { enabled: true, api_key: 你的API Key, base_url: , model: qwen-flash }⚠️ 所调用的大模型接口必须符合OpenAI API 规范目前暂只支持这一种规范。自动追加歌曲解决什么问题在线点播的歌单播到最后一首就停了意犹未尽。原理播放到末尾时系统自动搜索并追加同歌手的歌曲保持连播。默认就是开启的auto_add_song: true。注意它只对「全部播放」模式生效而「全部播放」本质上就是全部循环在线点播创建的歌单默认就是这个模式。早期版本这项没有暴露到前端只能手改配置文件现在高级设置里可以直接关。语音搜单策略语音搜歌单时搜出一批歌单选哪一条来播voice_playlist_strategy控制这个策略取值含义default取首条默认值max_songs取歌曲最多的max_plays取播放最多的random随机一条LX 歌单自动转换LX Server 生态专属开启auto_convert后每 30 秒自动拉取 LX 侧歌单转成 xiaomusic 自己的歌单。转换出来的歌单用_online_lx_前缀命名必须把生态切到 LX Server 才能使用——如果你此时切回了 MusicFree这批歌单是看得见摸不着的。六、避坑清单出问题先查这里把分散在各处的注意事项合并成一张问题 → 排查清单遇到什么查什么。你遇到的问题大概率原因解决办法LX Server 接口生态无法播放服务端接口或网络问题先点「接口测试」确认地址连通再看服务端日志仍不行参考仓库docs/issues/811.md的处理方案LX Server 升级后接口不通v1.8.2 之后加了 Token 限制新版 onlineSearch 尚未适配暂时回退 LX Server 版本等新版适配语音口令说了没反应「允许唤醒的命令」列表里没有对应标识检查列表是否包含singer_play和online_play要搜歌单再加online_playlist_playAI 口令提取不生效配置没开全或接口不符合规范确认aiapi_info里enabled: true且api_key非空确认接口符合 OpenAI API 规范升级后后台配置全丢了某次版本如 V1.1.1重构过配置文件结构手动删除conf/plugins-config.json重启服务在网页端重新配置会基于模板重新生成某首歌网页能放、音箱不响部分 MusicFree 插件如 B 站源的音频流不被小爱音箱支持这类资源改用网页端在线播放转换出来的 LX 歌单播不了歌单用了_online_lx_前缀只在 LX Server 生态下有效把接口生态切回 LX Server后台突然要密码 / 忘记密码password字段被设置过改conf/plugins-config.json里的password重置置空即关锁想同步平台歌单到音箱平台歌单同步的诉求已有专门讨论参考仓库docs/issues/807.md的方案讨论另外两条机制说明不算故障但知道不慌SSRF 防护源码里所有在线 URL 校验都会拒绝内网、回环、链路本地、多播地址见online_music.py的_make_request_with_validation。如果你的接口地址莫名被拦多半是命中了这条规则搜索结果不精准试试歌曲名 - 艺术家的写法让后端拆出歌名和歌手分开匹配。七、写在最后回到开头的外卖类比本地曲库是冰箱在线搜索是外卖平台而 MusicFree 和 LX Server 就是两家平台——前者自由度高、插件随便挑后者省心、填个地址就开工。选对了平台、绑好了音箱你获得的是一套完整的在线听歌链路网页搜歌能推给音箱音箱也能被语音直接点单播完一首还能自动续上同歌手的下一首模糊需求还能交给 AI 兜底。接下来你可以做什么按「快速上手」六步跑通第一首在线歌曲给「允许唤醒的命令」加上singer_play和online_play试试对着音箱点歌高级设置里把 AI 口令提取打开看看模糊指令的命中率变化如果配置过程中踩了坑先翻一遍上面的避坑清单再去docs/issues/找对应工单。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
