xiaomusic 同步网易云歌单实战从歌单 ID 到小爱音箱语音播放【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic本篇技术指南聚焦 xiaomusic 的“网易云歌单同步”主题讲解如何借助独立工具netease-playlist通过网易云歌单 ID 下载歌曲或生成 xiaomusic 可识别的歌单配置并深入剖析官方推荐的替代实现——自定义口令插件方案让你彻底读懂歌单 ID → 歌单数据 → 小爱音箱播放的完整链路。读完本文你将掌握配置自定义口令、编写 Python 插件拉取歌单、以及调用 docs/issues/269.md 中社区验证过的getmy_playlist插件的完整实战能力。一、方案概览三条通往网易云歌单的路径在 xiaomusic 中接入网易云歌单社区验证过的主要有下面三种方式方案实现形态适合场景netease-playlist独立工具独立模块可 Docker 部署一次性/批量下载歌曲或离线生成歌单配置自定义口令插件将插件代码挂在exec#口令下语音实时拉取歌单并播放可配合米家自动化网络歌单 JSON官方原生在设置页配置歌单 JSON / JSON URL电台、m3u8、B 站等在线流媒体歌单三条路径并非互斥你完全可以用netease-playlist把歌单导出成 自定义网络歌单格式 后填入设置页也可以用插件方案实现把歌曲扔进网易云歌单 → 喊一句口令 → 小爱音箱随机播放的实时同步体验。二、独立工具 netease-playlist歌单 ID 驱动下载与配置生成Issue 312 的核心内容是推广独立模块netease-playlist。它的能力可以用一句话概括通过网易云音乐歌单 ID下载歌曲或生成 xiaomusic 可用的歌单配置。2.1 在 xiaomusic 体系中的定位原文档明确说明了两点定位独立模块可 Docker 部署——它不修改 xiaomusic 本体不依赖 xiaomusic 的插件机制可作为不用插件的另外实现方式——如果你不想维护插件代码可以只靠这个工具完成任务。也就是说netease-playlist与 xiaomusic 的耦合点是歌单 ID与歌单配置 JSON前者是输入后者是输出。2.2 它生成的歌单配置长什么样netease-playlist生成的目标格式就是 xiaomusic 原生支持的自定义网络歌单 JSON。参考 docs/issues/78.md 中官方给出的结构[ { name: 歌单1, musics: [ { name: 歌名1, url: http://.../index.m3u8, type: radio }, { name: 歌名2, url: https://.../64k.mp3 } ] } ]要点顶层是歌单数组每个元素含name歌单名与musics歌曲数组每首歌含name与url两个必填字段type为radio时表示电台流会一直播放当前源不切下一首url可以是直链、m3u8 电台地址也可以是self:///api/proxy/plugin-url?data开头的在线音乐插件代理链接v0.4.15 起支持需配合 OnlineSearch 的 JS 插件并开启“网络歌曲过代理”开关。拿到这份 JSON 后有两种落地方式直接粘贴到 xiaomusic 设置页的歌单 JSON 输入框把 JSON 上传到 gist / GitHub / Gitee 等可直链分享的地址在JSON URL 输入框里填入 raw 链接点击“获取”按钮自动填充。三、配置生成的两种入口设置页与 config 文件官方在 docs/issues/105.md 中明确提示“建议通过插件实现或者新增一个页面工具把歌单导出 json歌单的 json 格式见 /issues/78”。对应的配置字段在config-example.json中体现为三个相关项music_list_url: , music_list_json: , custom_play_list_json: 其中music_list_json/custom_play_list_json即歌单 JSON 的注入位置music_list_url则是 JSON 文件的远程地址。设置页上对应的就是“歌单 JSON 输入框”与“JSON URL 输入框”。需要注意的是社区在实战中反馈最好在setting.json里配置网页端配置有时会出现匹配不上的情况见 Issue 269 评论 13。所以一个稳妥的做法是先用设置页在线验证歌单可用再把最终 JSON 固化进配置文件。四、进阶方案用自定义口令插件实现实时歌单同步netease-playlist是离线/半离线方案做不到往歌单扔歌 → 音箱马上能播。社区验证过的实时方案是自定义口令插件。这正是 Issue 105 讲解的功能也是 Issue 312 中不用插件的另一面。4.1 自定义口令的运行原理从源码看整个链路是这样的配置注入在config.py的Config模型中user_key_word_dict与key_word_dict都是独立的配置字段config.py。调用init()时append_user_keyword()会把user_key_word_dict中每个k: v合并进key_word_dict并追加进key_match_order匹配优先级表config.py口令解析command_handler.py中无论完全匹配还是模糊匹配只要opvalue以exec#开头就把#之后的部分当作可执行代码返回command_handler.py插件执行XiaoMusic.exec()拿到代码后调用plugin_manager.execute_plugin(code)xiaomusic.py代码校验PluginManager先用ast.parse校验代码必须是“直接调用插件函数的表达式”支持字符串/数字/布尔/None/列表/元组/字典作为参数不支持关键字参数plugin.py动态加载启动时PluginManager遍历plugins/包内所有模块动态导入并取出与文件名同名的函数注册进_funcsplugin.py。因此code1对应 plugins/code1.pyhttpget对应 plugins/httpget.py同步/异步兼容execute_plugin通过inspect.iscoroutinefunction判断异步函数await调用同步函数直接调用plugin.py。4.2 最小可运行配置以官方插件示例code1为例配置user_key_word_dict即可会自动插入key_word_dict{ user_key_word_dict: { 测试自定义口令: exec#code1(\hello\), 测试链接: exec#httpget(\https://github.com/hanxi/xiaomusic\) } }同时必须在active_cmd中配上口令对应的动作值用于唤醒active_cmd: play,set_random_play,playlocal,play_music_list,play_music_list_index,stop_after_minute,stop,测试自定义口令active_cmd的作用见 Issue 105 评论 20决定在 xiaomusic 未播放时哪些命令可以唤醒 xiaomusic 接管处理。从 command_handler.py 看当设备未在播放且非控制面板来源时若opvalue与opkey都不在active_cmd_arr中该命令会被忽略。插件本体放在plugins/目录下文件内的函数名必须与文件名一致。仓库自带的官方示例 plugins/code1.py 展示了如何拿到用户语音原文并让音箱回读async def code1(arg1): global log, xiaomusic log.info(fcode1:{arg1}) did xiaomusic.get_cur_did() await xiaomusic.do_tts(did, 你好我是自定义的测试口令) query xiaomusic.command_handler.last_cmd.strip() await xiaomusic.do_tts(did, f你说的是: {query})关键点global log, xiaomusic是插件运行时的约定注入变量由PluginManager._load_plugins注入模块命名空间xiaomusic.get_cur_did()获取当前说话设备xiaomusic.pyxiaomusic.command_handler.last_cmd保存了最近一次语音输入原文command_handler.py插件内部自行做前缀切割即可实现“口令 参数”的玩法do_tts(did, value)让指定设备说话xiaomusic.py早期版本签名是do_tts(value)重构后必须传didIssue 105 评论 3 正是这个报错。httpget则演示了用语音触发一次 HTTP 请求可用来对接任意 REST 服务import requests def httpget(url): global log response requests.get(url, timeout5) # 增加超时以避免长时间挂起 response.raise_for_status() # 如果响应不是200引发HTTPError异常 log.info(fhttpget url:{url} response:{response.text})容器部署时需将plugins/目录挂载出来才能让自定义插件文件生效。五、社区验证的完整方案getmy_playlist 插件Issue 269 的评论 13 给出了经过真机验证的完整方案一个名为getmy_playlist.py的插件通过 NeteaseCloudMusicApi 拉取歌单并注入 xiaomusic 内存让网易云歌单直接变为语音歌单。5.1 它的工作方式插件核心逻辑要点提炼自 Issue 269 中的完整代码支持两种入参uid拉取该用户全部歌单与playlist_id拉取单个歌单通过{api_host}/user/playlist?uid{uid}获取用户歌单列表再对每个歌单调用{api_host}/playlist/detail?id{id}获取曲目对每首歌构造播放地址{api_host}/song/url?id{id}br350000realIP...proxy...写入三个关键数据结构xiaomusic.all_music[name] url把歌曲名映射到播放地址xiaomusic.all_music_tags[name] {...}写入标题、歌手、专辑、封面等元数据picture用music[al][picUrl]xiaomusic.music_list[list_name] one_music_list把歌单名映射到歌曲名列表最后调用xiaomusic.try_save_tag_cache()保存标签缓存。5.2 关键参数与接线方式在setting.json中用user_key_word_dict绑定口令注意 Issue 269 中演示的口令动作值是exec#getmy_playlist(playlist_id12758992225)user_key_word_dict: { 获取歌单: exec#getmy_playlist(playlist_id12758992225) }同时在active_cmd末尾追加获取歌单示例完整active_cmd见 Issue 269 评论 13。部署要点如下事项说明API 服务本地/局域网运行 NeteaseCloudMusicApi可用gnehs/neteasecloudmusicapi-docker镜像部署播放地址用song/url接口按歌曲 ID 换直链proxyHTTP:%2F%2F127.0.0.1:8080参数配合 UnblockNeteaseMusic 解锁灰色歌曲触发方式对小爱音箱说获取歌单或将此口令挂到米家我回来了智能场景自动触发局限性歌曲地址时效性强网易侧 API 变动可能导致取不到播放地址见 Issue 269 评论 15-17此时可退化为用 yt-dlp 全量下载后本地播放5.3 为什么推荐生成 JSON 再提交Issue 269 的作者 hanxi 在评论 5 中的评价值得注意直接改接口强改歌单保存逻辑不太通用更通用的做法是生成 JSON再用现有接口提交 JSON。这与 Issue 312 中netease-playlist生成歌单配置的思路完全一致——把 xiaomusic 当作消费方而不是去改它的内部逻辑。六、常见问题与避坑清单综合 Issue 312 / 269 / 105 的社区反馈整理以下实战避坑点口令不触发检查active_cmd是否已包含该口令对应的值或口令本身评论多次确认需要在 active_cmd 里配一下才能正常唤醒自定义口令无法覆盖默认口令user_key_word_dict只能以插入方式添加不能删除系统默认口令如播放歌曲如需改动去网页后台设置页改Issue 105 评论 14-17插件函数卡死整个服务插件内不要写阻塞型死循环长任务用asyncio.sleep让步并另写一个口令杀掉对应 taskIssue 105 评论 25-29do_tts报缺少value参数旧版本签名问题升级到修复后的版本即可拿不到播放地址网易 API 变动会导致song/url失效需要更新 API 服务或改用下载方案Issue 269 评论 15-17Docker 部署注意插件目录要挂载ARM 设备需确认镜像是否提供对应架构Issue 269 评论 19-21歌曲时长获取不到部分 m4a / 流媒体格式无法解析时长会影响自动切歌可配合remove_id3tag、convert_to_mp3等配置规避Issue 78 评论 7-13。七、总结围绕网易云歌单同步这一需求xiaomusic 生态给出了从轻到重的完整方案谱系只想下载/离线播放用独立工具netease-playlistIssue 312 推荐想要实时同步、语音可控写一个自定义口令插件Issue 105 269 的getmy_playlist是经过真机验证的参考实现播放电台、m3u8 或在线流媒体直接用网络歌单 JSON原生能力Issue 78。无论选哪条路其底层都共享同一套契约把歌单数据规整为歌单名 → 歌曲名 → 播放地址结构要么通过配置文件、要么通过all_music/music_list等内存结构注入 xiaomusic。理解这条契约你就能把 QQ 音乐、Apple Music 等任何平台歌单用同样的思路接入小爱音箱。相关参考插件运行机制源码口令匹配源码配置合并源码官方示例插件 code1 / httpget歌单 JSON 格式说明【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaomusic 同步网易云歌单实战：从歌单 ID 到小爱音箱语音播放
xiaomusic 同步网易云歌单实战从歌单 ID 到小爱音箱语音播放【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic本篇技术指南聚焦 xiaomusic 的“网易云歌单同步”主题讲解如何借助独立工具netease-playlist通过网易云歌单 ID 下载歌曲或生成 xiaomusic 可识别的歌单配置并深入剖析官方推荐的替代实现——自定义口令插件方案让你彻底读懂歌单 ID → 歌单数据 → 小爱音箱播放的完整链路。读完本文你将掌握配置自定义口令、编写 Python 插件拉取歌单、以及调用 docs/issues/269.md 中社区验证过的getmy_playlist插件的完整实战能力。一、方案概览三条通往网易云歌单的路径在 xiaomusic 中接入网易云歌单社区验证过的主要有下面三种方式方案实现形态适合场景netease-playlist独立工具独立模块可 Docker 部署一次性/批量下载歌曲或离线生成歌单配置自定义口令插件将插件代码挂在exec#口令下语音实时拉取歌单并播放可配合米家自动化网络歌单 JSON官方原生在设置页配置歌单 JSON / JSON URL电台、m3u8、B 站等在线流媒体歌单三条路径并非互斥你完全可以用netease-playlist把歌单导出成 自定义网络歌单格式 后填入设置页也可以用插件方案实现把歌曲扔进网易云歌单 → 喊一句口令 → 小爱音箱随机播放的实时同步体验。二、独立工具 netease-playlist歌单 ID 驱动下载与配置生成Issue 312 的核心内容是推广独立模块netease-playlist。它的能力可以用一句话概括通过网易云音乐歌单 ID下载歌曲或生成 xiaomusic 可用的歌单配置。2.1 在 xiaomusic 体系中的定位原文档明确说明了两点定位独立模块可 Docker 部署——它不修改 xiaomusic 本体不依赖 xiaomusic 的插件机制可作为不用插件的另外实现方式——如果你不想维护插件代码可以只靠这个工具完成任务。也就是说netease-playlist与 xiaomusic 的耦合点是歌单 ID与歌单配置 JSON前者是输入后者是输出。2.2 它生成的歌单配置长什么样netease-playlist生成的目标格式就是 xiaomusic 原生支持的自定义网络歌单 JSON。参考 docs/issues/78.md 中官方给出的结构[ { name: 歌单1, musics: [ { name: 歌名1, url: http://.../index.m3u8, type: radio }, { name: 歌名2, url: https://.../64k.mp3 } ] } ]要点顶层是歌单数组每个元素含name歌单名与musics歌曲数组每首歌含name与url两个必填字段type为radio时表示电台流会一直播放当前源不切下一首url可以是直链、m3u8 电台地址也可以是self:///api/proxy/plugin-url?data开头的在线音乐插件代理链接v0.4.15 起支持需配合 OnlineSearch 的 JS 插件并开启“网络歌曲过代理”开关。拿到这份 JSON 后有两种落地方式直接粘贴到 xiaomusic 设置页的歌单 JSON 输入框把 JSON 上传到 gist / GitHub / Gitee 等可直链分享的地址在JSON URL 输入框里填入 raw 链接点击“获取”按钮自动填充。三、配置生成的两种入口设置页与 config 文件官方在 docs/issues/105.md 中明确提示“建议通过插件实现或者新增一个页面工具把歌单导出 json歌单的 json 格式见 /issues/78”。对应的配置字段在config-example.json中体现为三个相关项music_list_url: , music_list_json: , custom_play_list_json: 其中music_list_json/custom_play_list_json即歌单 JSON 的注入位置music_list_url则是 JSON 文件的远程地址。设置页上对应的就是“歌单 JSON 输入框”与“JSON URL 输入框”。需要注意的是社区在实战中反馈最好在setting.json里配置网页端配置有时会出现匹配不上的情况见 Issue 269 评论 13。所以一个稳妥的做法是先用设置页在线验证歌单可用再把最终 JSON 固化进配置文件。四、进阶方案用自定义口令插件实现实时歌单同步netease-playlist是离线/半离线方案做不到往歌单扔歌 → 音箱马上能播。社区验证过的实时方案是自定义口令插件。这正是 Issue 105 讲解的功能也是 Issue 312 中不用插件的另一面。4.1 自定义口令的运行原理从源码看整个链路是这样的配置注入在config.py的Config模型中user_key_word_dict与key_word_dict都是独立的配置字段config.py。调用init()时append_user_keyword()会把user_key_word_dict中每个k: v合并进key_word_dict并追加进key_match_order匹配优先级表config.py口令解析command_handler.py中无论完全匹配还是模糊匹配只要opvalue以exec#开头就把#之后的部分当作可执行代码返回command_handler.py插件执行XiaoMusic.exec()拿到代码后调用plugin_manager.execute_plugin(code)xiaomusic.py代码校验PluginManager先用ast.parse校验代码必须是“直接调用插件函数的表达式”支持字符串/数字/布尔/None/列表/元组/字典作为参数不支持关键字参数plugin.py动态加载启动时PluginManager遍历plugins/包内所有模块动态导入并取出与文件名同名的函数注册进_funcsplugin.py。因此code1对应 plugins/code1.pyhttpget对应 plugins/httpget.py同步/异步兼容execute_plugin通过inspect.iscoroutinefunction判断异步函数await调用同步函数直接调用plugin.py。4.2 最小可运行配置以官方插件示例code1为例配置user_key_word_dict即可会自动插入key_word_dict{ user_key_word_dict: { 测试自定义口令: exec#code1(\hello\), 测试链接: exec#httpget(\https://github.com/hanxi/xiaomusic\) } }同时必须在active_cmd中配上口令对应的动作值用于唤醒active_cmd: play,set_random_play,playlocal,play_music_list,play_music_list_index,stop_after_minute,stop,测试自定义口令active_cmd的作用见 Issue 105 评论 20决定在 xiaomusic 未播放时哪些命令可以唤醒 xiaomusic 接管处理。从 command_handler.py 看当设备未在播放且非控制面板来源时若opvalue与opkey都不在active_cmd_arr中该命令会被忽略。插件本体放在plugins/目录下文件内的函数名必须与文件名一致。仓库自带的官方示例 plugins/code1.py 展示了如何拿到用户语音原文并让音箱回读async def code1(arg1): global log, xiaomusic log.info(fcode1:{arg1}) did xiaomusic.get_cur_did() await xiaomusic.do_tts(did, 你好我是自定义的测试口令) query xiaomusic.command_handler.last_cmd.strip() await xiaomusic.do_tts(did, f你说的是: {query})关键点global log, xiaomusic是插件运行时的约定注入变量由PluginManager._load_plugins注入模块命名空间xiaomusic.get_cur_did()获取当前说话设备xiaomusic.pyxiaomusic.command_handler.last_cmd保存了最近一次语音输入原文command_handler.py插件内部自行做前缀切割即可实现“口令 参数”的玩法do_tts(did, value)让指定设备说话xiaomusic.py早期版本签名是do_tts(value)重构后必须传didIssue 105 评论 3 正是这个报错。httpget则演示了用语音触发一次 HTTP 请求可用来对接任意 REST 服务import requests def httpget(url): global log response requests.get(url, timeout5) # 增加超时以避免长时间挂起 response.raise_for_status() # 如果响应不是200引发HTTPError异常 log.info(fhttpget url:{url} response:{response.text})容器部署时需将plugins/目录挂载出来才能让自定义插件文件生效。五、社区验证的完整方案getmy_playlist 插件Issue 269 的评论 13 给出了经过真机验证的完整方案一个名为getmy_playlist.py的插件通过 NeteaseCloudMusicApi 拉取歌单并注入 xiaomusic 内存让网易云歌单直接变为语音歌单。5.1 它的工作方式插件核心逻辑要点提炼自 Issue 269 中的完整代码支持两种入参uid拉取该用户全部歌单与playlist_id拉取单个歌单通过{api_host}/user/playlist?uid{uid}获取用户歌单列表再对每个歌单调用{api_host}/playlist/detail?id{id}获取曲目对每首歌构造播放地址{api_host}/song/url?id{id}br350000realIP...proxy...写入三个关键数据结构xiaomusic.all_music[name] url把歌曲名映射到播放地址xiaomusic.all_music_tags[name] {...}写入标题、歌手、专辑、封面等元数据picture用music[al][picUrl]xiaomusic.music_list[list_name] one_music_list把歌单名映射到歌曲名列表最后调用xiaomusic.try_save_tag_cache()保存标签缓存。5.2 关键参数与接线方式在setting.json中用user_key_word_dict绑定口令注意 Issue 269 中演示的口令动作值是exec#getmy_playlist(playlist_id12758992225)user_key_word_dict: { 获取歌单: exec#getmy_playlist(playlist_id12758992225) }同时在active_cmd末尾追加获取歌单示例完整active_cmd见 Issue 269 评论 13。部署要点如下事项说明API 服务本地/局域网运行 NeteaseCloudMusicApi可用gnehs/neteasecloudmusicapi-docker镜像部署播放地址用song/url接口按歌曲 ID 换直链proxyHTTP:%2F%2F127.0.0.1:8080参数配合 UnblockNeteaseMusic 解锁灰色歌曲触发方式对小爱音箱说获取歌单或将此口令挂到米家我回来了智能场景自动触发局限性歌曲地址时效性强网易侧 API 变动可能导致取不到播放地址见 Issue 269 评论 15-17此时可退化为用 yt-dlp 全量下载后本地播放5.3 为什么推荐生成 JSON 再提交Issue 269 的作者 hanxi 在评论 5 中的评价值得注意直接改接口强改歌单保存逻辑不太通用更通用的做法是生成 JSON再用现有接口提交 JSON。这与 Issue 312 中netease-playlist生成歌单配置的思路完全一致——把 xiaomusic 当作消费方而不是去改它的内部逻辑。六、常见问题与避坑清单综合 Issue 312 / 269 / 105 的社区反馈整理以下实战避坑点口令不触发检查active_cmd是否已包含该口令对应的值或口令本身评论多次确认需要在 active_cmd 里配一下才能正常唤醒自定义口令无法覆盖默认口令user_key_word_dict只能以插入方式添加不能删除系统默认口令如播放歌曲如需改动去网页后台设置页改Issue 105 评论 14-17插件函数卡死整个服务插件内不要写阻塞型死循环长任务用asyncio.sleep让步并另写一个口令杀掉对应 taskIssue 105 评论 25-29do_tts报缺少value参数旧版本签名问题升级到修复后的版本即可拿不到播放地址网易 API 变动会导致song/url失效需要更新 API 服务或改用下载方案Issue 269 评论 15-17Docker 部署注意插件目录要挂载ARM 设备需确认镜像是否提供对应架构Issue 269 评论 19-21歌曲时长获取不到部分 m4a / 流媒体格式无法解析时长会影响自动切歌可配合remove_id3tag、convert_to_mp3等配置规避Issue 78 评论 7-13。七、总结围绕网易云歌单同步这一需求xiaomusic 生态给出了从轻到重的完整方案谱系只想下载/离线播放用独立工具netease-playlistIssue 312 推荐想要实时同步、语音可控写一个自定义口令插件Issue 105 269 的getmy_playlist是经过真机验证的参考实现播放电台、m3u8 或在线流媒体直接用网络歌单 JSON原生能力Issue 78。无论选哪条路其底层都共享同一套契约把歌单数据规整为歌单名 → 歌曲名 → 播放地址结构要么通过配置文件、要么通过all_music/music_list等内存结构注入 xiaomusic。理解这条契约你就能把 QQ 音乐、Apple Music 等任何平台歌单用同样的思路接入小爱音箱。相关参考插件运行机制源码口令匹配源码配置合并源码官方示例插件 code1 / httpget歌单 JSON 格式说明【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考