xiaomusic 在线搜索深度指南MusicFree 插件 与 LX Server 接口双模式配置与实战【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusicxiaomusic 的在线搜索模块让音箱不再依赖本地曲库——OnlineMusicServicexiaomusic/online_music.py负责搜索、直链解析、歌词查询JSPluginManagerxiaomusic/js_plugin_manager.py负责搜索源接入。读完本文你能拿到三样东西两种接口生态的选型依据、plugins-config.json每个字段的含义与配置路径、以及语音口令不生效、LX 接口连不上时的排错路径。底层机制拆解搜索请求怎么走到音箱一条在线播放 江南的语音请求数据流经过三层口令路由command_handler.py将唤醒词映射到online_play/singer_play/online_playlist_play参数以歌名|歌手的管道格式传入见 xiaomusic/command_handler.py业务编排OnlineMusicService.online_play先调_parse_keyword_with_ai提取歌名歌手AI 未启用时回退到_parse_keyword_by_dash按第一个-拆分再调get_music_list_online发起搜索最后由search_top_one_play走_search_top_one打分取最优经push_music_list_play构造_online_play临时歌单推给已绑定音箱搜索源执行入口get_music_list_online按api_type分流——2走_search_all_platform_lxLX Server 并行请求1走_search_all_pluginsMusicFree 插件并行搜索每插件限额limit // 插件数。聚合结果统一交给optimize_search_results排序优先级为「歌曲名匹配度 歌手名匹配度 插件权重」插件权重由启用列表顺序决定仅前 9 个插件有效排名越靠前分越高最高 9 分。双生态核心差异维度MusicFree 插件版api_type1LX Server 接口版api_type2接入机制Node 子进程沙箱加载.js插件配置 API 地址服务端统一逻辑启动方式_start_node_process拉起node js_plugin_runner.jsstdin/stdout 传 JSON 消息HTTP 请求${base_url}/music/*系列接口管理复杂度订阅/上传/启停/卸载插件填地址 可选鉴权头聚合单位已启用插件已配置平台tx/kg/kw/wy/mg适用场景已有 MusicFree 插件资源已部署 LX Sync Server⚠️ 两生态互斥back_conf_info.api_type是1/2的硬切换切换时前端弹确认框因为插件列表与平台列表配置互不兼容。LX Server 侧内置了完整的播放保障链音质优先级LX_QUALITY_PRIORITY [master, flac24bit, flac, 320k, 192k, 128k]解析失败自动降档原平台解析失败时按歌名歌手时长误差≤5 秒跨平台换源播放前先查${base_url}/music/cache/check缓存未命中再走进度接口 /music/url异步解析。MusicFree 侧的 Node 子进程带自愈_monitor_node_process每 5 秒探活崩溃后在 60 秒窗口内最多自动重启 1 次超限需人工介入。后台可视配置按操作区域逐项说明后台配置页位于 xiaomusic/static/onlineSearch/setting.html配套脚本见 setting-backend.js、setting-musicfree.js、setting-lxserver.js。接口生态区域配置项字段含义默认值生效条件生态选择back_conf_info.api_type1MusicFree 插件2LX Server 接口1POST /api/back-conf/update保存后立即生效MusicFree 插件区域仅api_type1可见配置项字段含义默认值生效条件订阅源地址music_free_info.plugin_source.source_url插件订阅 JSON 源空需点「更新订阅」POST /api/plugin-source/refresh才拉取启用插件music_free_info.enabled_plugins参与搜索的插件列表顺序即权重[]保存即生效空列表无法搜索口令偏好平台music_free_info.box_play_platform语音口令搜索的平台all聚合allPOST /api/box-play-platform/updateLX Server 区域仅api_type2可见配置项字段含义默认值生效条件接口地址lx_server_info.base_urlLX Server API 地址如http://127.0.0.1:9527/api空空则所有 LX 功能不可用鉴权头lx_server_info.x-user-name/x-user-token请求时附加的鉴权头空V1.1.3两者需同时非空才附加平台列表lx_server_info.platforms参与聚合的平台字典key 为标识含tx等 5 项增删后POST /api/lxServer/updatePlatforms保存口令偏好平台lx_server_info.box_play_platform同 MusicFree 侧all同左高级设置模态框GET/POST /api/advanced-config/*配置项字段含义默认值自动追加歌曲auto_add_song播完最后一首自动追加同歌手歌曲仅「全部播放」模式生效true自动拉取转换lx_server_info.auto_convert每 30 秒拉取 LX 歌单转 XM 歌单仅 LX 生态显示falseAI 口令提取aiapi_info大模型解析模糊语音指令未启用口令搜索偏好box_play_platform语音口令用哪个平台all语音搜单策略voice_playlist_strategy.value搜到多个歌单时的选取策略default配置文件字段速查plugins-config.json配置持久化在运行时目录的conf/plugins-config.json首次启动由模板 xiaomusic/plugins-config-example.json 生成插件元数据与文件分别落在该目录的plugins-config.json与js_plugins/下。完整结构{ account: , password: , auto_add_song: true, aiapi_info: {enabled: false, api_key: }, back_conf_info: { api_type: 1, api_options: [ {name: MusicFree插件, type: 1}, {name: LXServer接口, type: 2} ] } }lx_server_info与music_free_info两个生态节点lx_server_info: { base_url: , x-user-name: , x-user-token: , auto_convert: false, platforms: {tx: 小秋音乐, kg: 小枸音乐, kw: 小蜗音乐, wy: 小芸音乐, mg: 小蜜音乐}, box_play_platform: all }, music_free_info: { enabled_plugins: [], plugin_source: {source_url: }, plugins_info: [], box_play_platform: all }, voice_playlist_strategy: {desc: 语音搜单策略, value: default}字段所在节点含义api_typeback_conf_info生态选择1MusicFree2LX Serverenabled_pluginsmusic_free_info启用插件列表顺序决定权重前 9 个有效plugins_infomusic_free_info已安装插件的元数据source_urlmusic_free_info.plugin_source插件订阅源地址base_urllx_server_infoLX Server API 地址x-user-name/x-user-tokenlx_server_infoLX 鉴权头V1.1.3platformslx_server_infoLX 平台字典key 为平台标识auto_convertlx_server_infoLX 歌单自动转换定时任务30 秒间隔box_play_platform两个生态节点各一份语音口令搜索偏好all为聚合auto_add_song顶层自动追加同歌手歌曲开关aiapi_info顶层AI 提取配置enabled/api_key可选base_url/modelpassword顶层后台密码锁非空即启用V1.1.2voice_playlist_strategy.value顶层default/max_songs/max_plays/random⚠️ 涉及配置结构重构的版本升级如 V1.1.1旧用户需手动删除conf/plugins-config.json后重启服务在网页端重新配置。操作手册从选型到语音点歌第一步选型与生态切换前置条件已部署 xiaomusic 并可访问后台MusicFree 路径需有可用的.js插件或订阅源地址LX 路径需已部署 LX Sync Server操作动作后台「接口生态」区域点选目标生态确认弹窗后保存POST /api/back-conf/update预期反馈对应配置区插件列表 / LX 地址表单切换显示异常第一反应确认conf/plugins-config.json中api_type已落盘若两个配置区同时显示或都不显示删除配置文件重启重建。第二步配置搜索源MusicFree 路径填订阅源地址 → 点「更新订阅」POST /api/plugin-source/refresh系统校验响应含plugins数组后批量下载→ 在插件列表中启用 1-3 个可靠插件注意权重排序。手动上传仅限.js文件且ALL.js/all.js/OpenAPI.js/OPENAPI.js为保留名会被 409 拒绝同名插件重复上传同样 409POST /api/js-plugins/upload。在线导入走POST /api/js-plugins/import-online地址必须http(s)://开头。LX Server 路径填base_url→ 点「接口测试」GET /api/lxServer/test后端请求${base_url}/music/config并校验player.enableAuth、user.enablePublicRestriction字段判定合法性→ 按需配鉴权头 → 增删platforms参与聚合。预期反馈接口测试返回success: true插件启用后列表状态变绿异常第一反应测试失败先查地址是否带/api后缀、服务是否同机可达插件启用失败查日志中 Node 进程是否存活60 秒窗口内重启超限会停止自愈。第三步网页搜索与双通道播放前置条件搜索源已就绪推音箱播放还要求已在「小爱音箱设置面板」完成绑定操作动作搜索页输入歌名 - 歌手_parse_keyword_by_dash按首个-拆分提升精度翻页浏览每页 20 条预期反馈结果带标题、艺术家、专辑、时长、音质与来源平台标签异常第一反应某平台结果缺失看该插件/平台是否启用B 站类源推音箱失败时改用网页端播放该源音频流可能不被音箱解码支持。第四步开通语音口令前置条件在「允许唤醒的命令」中加入,singer_play,online_play,——漏配是最常见的不生效原因操作动作在线播放 林俊杰 江南或播放歌手 周杰伦预期反馈online_play经_search_top_one打分歌名完全匹配 90、开头 70、结尾 50、包含 30歌手匹配按 9/7/5/3 递减取最高分播放singer_play生成_online_歌手名歌单顺序播放异常第一反应音箱无响应先核对命令列表没找到歌曲则看box_play_platform是否指到了无结果的单一平台改all聚合。进阶能力AI 口令提取与定时转换AI 智能口令提取默认关闭。启用条件为aiapi_info.enabledtrue且api_key非空_parse_keyword_with_ai调用 xiaomusic/utils/openai_utils.py 的analyze_music_command解析模糊指令如那首关于秋天的歌。接口地址留空默认阿里百炼模型默认qwen-flash。回退机制AI 不可用或解析失败时自动退回歌名-歌手的-拆分功能不中断。⚠️ 所接大模型必须兼容 OpenAI API 规范非 OpenAI 协议接口无法使用。LX 歌单自动转换auto_converttrue后由js_plugin_manager的_auto_convert_loop每 30 秒拉取 LX 歌单并转换为_online_lx_前缀的 XM 歌单写入曲库转换出的歌单只有生态切回 LX Server 时才可正常解析播放。手动操作可用GET /api/lxServer/userList、GET /api/lxServer/pullPlaylist、GET /api/lxServer/convertPlaylist支持playlists参数指定歌单名。语音搜单策略online_playlist_play口令搜到多个歌单时按voice_playlist_strategy.value选取——default取首条、max_songs歌曲数最多、max_plays播放量最高、random随机选定后经pick_best_playlist拉全量歌曲推给音箱。后台密码锁V1.1.2password置非空即启用进后台时GET /api/password/check返回required: true触发密码框POST /api/password/verify校验通过方可进入置空即关闭。避坑清单LX Music Sync Server v1.8.2 增加了 Token 限制会导致 xiaomusic 接口调用异常——暂不要升级该版本等待 onlineSearch 适配V1.1.2 文档说明。权重只看前 9 个插件启用列表超过 9 项时第 10 个起对聚合搜索权重无贡献但插件本身仍会被请求。SSRF 防护会拦截内网直链_make_request_with_validation拒绝内网、回环、链路本地、多播地址本地测试用公网可达地址或代理。自动追加只认「全部播放」模式auto_add_song在随机/单曲循环下无效该开关早期版本未暴露到前端需改conf/plugins-config.json的auto_add_song字段。相对地址已自动归一化LX Server 返回的相对路径会拼base_url勿在base_url末尾多加/api之外的路径段导致 404。保留插件名ALL/all/OpenAPI/OPENAPI四个名字被系统占用上传或在线导入均会被拒。现象原因处置LX 生态搜得到但播不了Token 限制或缓存接口版本不符见 docs/issues/811.md降级 LX Server 版本核对base_url语音口令无反应唤醒命令列表未含singer_play/online_play后台补配置后重说指令AI 提取不生效aiapi_info未启用或接口非 OpenAI 规范查enabled/api_key换兼容接口上传插件 409保留名或同名冲突重命名后重传 平台歌单同步到音箱的完整方案讨论见 docs/issues/807.md。源码导航源文件职责xiaomusic/online_music.pyOnlineMusicService聚合搜索、_search_top_one打分、直链解析与换源降级、SSRF 防护xiaomusic/js_plugin_manager.pyJSPluginManagerNode 沙箱进程管理、插件加载、LX 接口请求、optimize_search_results、_auto_convert_loop定时转换xiaomusic/api/routers/plugin.py全部在线搜索 REST 路由插件启停/上传、LX 测试与鉴权、高级配置、密码校验xiaomusic/command_handler.py唤醒命令到online_play/singer_play/online_playlist_play的口令映射xiaomusic/plugins-config-example.jsonplugins-config.json初始模板xiaomusic/static/onlineSearch/setting.html后台配置页生态切换、插件区、LX 区、高级设置xiaomusic/static/onlineSearch/index.html前端搜索页与双通道播放入口xiaomusic/utils/openai_utils.pyanalyze_music_commandAI 口令解析封装选型确定后按「生态切换 → 搜索源配置 → 口令白名单 → 播放通道」四步走一遍语音点歌、聚合搜索与无限连播即全链路可用出问题时优先对照api_type落盘值、唤醒命令列表与 LX 版本这三处。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考