从零开始轻松部署 XiaoMusic让小爱音箱彻底告别会员限制随心播放私人音乐库【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic你是否也遇到过这样的场景明明自己电脑里存着几百首高音质音乐却只能打开手机 App 一首首手动切换家里的小爱音箱每天都在却只会回答抱歉没有找到相关歌曲。有没有想过只需对小爱说一句播放周杰伦的晴天音箱就能立刻响起你收藏的旋律今天要介绍的 XiaoMusic 正是为此而生——一个让小爱音箱变身私人音乐管家的开源项目用 yt-dlp 下载音乐让本地与在线资源都能通过语音随心播放。先看成果十分钟跑通第一个最小可用 Demo先别急着研究原理我们直接把最激动人心的部分提前——用最简单的两条命令让 XiaoMusic 跑起来然后亲耳听到小爱音箱为你播放第一首歌。第一步准备两个目录在你的电脑或 NAS 上先规划好两个文件夹mkdir -p /xiaomusic_music mkdir -p /xiaomusic_conf这段命令创建了两个目录music目录用来存放你的音乐文件conf目录用来保存 XiaoMusic 的配置和账号信息。两个目录分开存放以后备份、迁移都会非常省心。第二步用 Docker Compose 一键拉起服务创建一个docker-compose.yml文件内容如下services: xiaomusic: image: docker.hanxi.cc/hanxi/xiaomusic container_name: xiaomusic restart: always ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf这段配置做了三件事从国内镜像源拉取 XiaoMusic 镜像把宿主机的 58090 端口映射到容器内的 8090 端口把前面创建的两个目录挂载进容器。如果你身处海外把image换成hanxi/xiaomusic即可其余不变。第三步启动并打开管理界面docker compose up -d等待镜像下载完成后在浏览器访问http://你的设备IP:58090你就能看到 XiaoMusic 的 Web 管理界面。第一次打开时需要完成一次绑定在设置页输入小米账号和密码保存系统会自动获取你的设备列表勾选你要控制的小爱音箱再次保存即可。XiaoMusic 的 Web 界面自带功能标注几乎每个按钮都告诉你该点哪里到这里最小可用 Demo 就已经跑通了。现在试着在网页里搜索一首歌点击播放如果音箱响起音乐恭喜你最难的 20% 已经完成复盘原理它到底是怎么听懂小爱说话的体验过后我们来拆解一下这个神奇的桥梁是如何工作的。你可以把 XiaoMusic 想象成一位同声传译官——它坐在你的小爱音箱和音乐库中间一边监听小爱说了什么一边把指令翻译成音乐播放动作。整个工作流大致是这样的监听对话XiaoMusic 会周期性地拉取小爱的对话记录识别出你设定的口令关键词默认是播放歌曲。解析指令把播放歌曲周杰伦晴天拆解成歌手周杰伦和歌名晴天支持模糊匹配说错一两个字也能找到。寻找音乐先在本地音乐库搜索找不到就用 yt-dlp 从网络下载到本地目录。推送播放通过小米的服务接口把音乐链接推送给音箱开始播放同时接管播放、暂停、切歌等控制权。在 Web 界面里你的每一首本地歌曲都清晰可查、双击即播看到这里你会发现XiaoMusic 本质上是一个语音指令翻译器 音乐下载器 音箱控制器的三合一工具核心代码都在xiaomusic/目录下想深入研究的同学可以翻阅xiaomusic/xiaomusic.py和xiaomusic/command_handler.py这两个文件。深入配置把每个关键开关都调到最顺手Demo 跑通只是开始接下来我们逐个梳理那些值得关注的配置项让 XiaoMusic 更贴合你的使用习惯。1. 语音口令让小爱听懂你的话默认口令是播放歌曲你可以完全自定义。打开xiaomusic/plugins-config-example.json或直接在设置页里配置关键词{ keywords_play: 播放歌曲,放歌曲, keywords_playlist: 播放列表,播放歌单, keywords_stop: 关机,暂停,停止,停止播放 }这段配置定义了四类指令的触发词播放、播放歌单、停止播放。你可以把放歌曲改成来一首让指令更符合你的说话习惯。2. 播放模式与收藏XiaoMusic 支持完整的播放模式控制用语音就能切换语音指令功能播放歌曲歌名搜索并播放指定歌曲上一首 / 下一首切换歌曲单曲循环 / 全部循环 / 随机播放切换播放模式加入收藏 / 取消收藏管理收藏歌单播放歌单目录名播放指定文件夹的歌单X 分钟后关机定时停止播放隐藏玩法对小爱说播放歌曲小猪佩奇的故事XiaoMusic 会先自动搜索下载相关内容再开始播放。家里有孩子的朋友这一条值得立刻试试。3. 音质与兼容性XiaoMusic 支持 MP3、FLAC、WAV、APE、OGG、M4A 等常见格式。如果你的音箱型号较旧如 L05B、L05C建议在设置里打开转换为 MP3选项虽然会消耗一些 CPU但能保证老设备稳定播放。进阶玩法把 XiaoMusic 玩出花来当你熟悉了基本操作是时候探索这些隐藏能力了。定时任务让音乐自动唤醒你XiaoMusic 内置了 crontab 格式的定时任务在设置页面的定时任务配置里填入 JSON 即可。比如每天早晨 7 点播放周杰伦的晴天[ { expression: 0 7 * * *, name: play, did: 123456789, arg1: 周杰伦晴天 } ]这里expression是标准的 cron 表达式0 7 * * * 表示每天 7 点name是任务类型arg1是播放内容。更实用的场景是每天晚上 12 点自动关闭对话记录拉取、早上 6 点重新开启能有效缓解小米接口的风控限制。完整任务类型见文档docs/issues/182.md。网络歌单把电台搬进音箱除了本地音乐XiaoMusic 还支持 JSON 格式的网络歌单可以配置电台或 m3u8 直播流。在设置页填入歌单 URL就能让小爱播放网络电台。格式示例见docs/issues/78.md还贴心地配备了 m3u 转 json 的转换工具。自定义口令写一行插件扩展能力XiaoMusic 的口令支持exec前缀调用插件项目自带的plugins/目录里就有现成例子。例如plugins/code1.py演示了如何自定义一条语音回复plugins/httpget.py演示了如何让口令触发一次网络请求。如果你想写自己的插件参考这两个文件就能快速上手。多设备与多目录家里有多台小爱音箱在 Web 界面切换设备即可让音乐在不同房间流转。音乐目录也支持多个用 Docker 挂载多个子目录即可每一层文件夹会自动识别为一个播放列表。避坑手册高频故障自查清单根据社区反馈我把最常遇到的问题整理成了问题→原因→解决的对照表遇到状况直接按图索骥。问题 1登录失败后台看不到设备列表原因小米账号在官网登录过滑块验证后旧会话失效或本地开了加速代理。解决先去官网www.mi.com完成一次登录验证关掉本地代理用局域网内的手机重新登录米家 App必要时改用 cookie 登录。问题 2网页能播放语音却无响应原因语音口令功能默认是关闭的需要手动开启获取对话记录开关。解决到设置页打开对应开关保存后重启容器。注意这个功能会频繁请求接口不用时随手关闭防止触发风控。问题 3日志显示在播放音箱却没有声音原因多半是hostname配错了地址音箱访问不到你的服务。解决检查设置里的地址是否为 NAS 的局域网 IP且与音箱在同一网段用浏览器打开日志里的歌曲链接测试能否访问确认端口映射是否被修改过。问题 4flac 格式无法播放原因部分型号如 L05B、L05C、LX06、L16A不支持 flac 格式。解决开启转换为 MP3选项或提前用工具批量转码。问题 5容器日志提示 DNS 解析错误原因容器无法解析小米域名。解决把主机的 DNS 改为223.5.5.5后重启 Docker或者把容器网络模式改为 host 模式。通用排查技巧遇到任何疑难杂症先去 Web 设置页底部点击下载日志文件用日志定位问题再求助比盲猜高效得多。安全与运维安心使用的几个底线XiaoMusic 需要用到你的小米账号安全这根弦一定要绷紧。尽量只跑在局域网不要让服务直接暴露到公网。如果必须公网访问务必开启 HTTP 认证并设置复杂密码且不要在公共 WiFi 环境下配置账号。不要绑定摄像头强烈建议不要在小爱音箱的小米账号下绑定摄像头等隐私设备账号一旦泄露后果会很严重。定期更新升级 Docker 镜像非常轻松docker compose pull docker compose up -d备份配置定期备份conf目录里面保存着你的全部设置。迁移到新设备时挂载原目录即可无缝恢复。下一步行动清单现在动手的时刻到了。按照这份清单一步步走很快你就能享受语音点歌的快乐克隆项目git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic部署容器按照本文的 Compose 配置启动服务绑定音箱设置页输入小米账号勾选你的设备导入音乐把音乐文件放进 music 目录或者直接用语音让小爱下载体验指令从播放歌曲歌名开始逐步尝试歌单、收藏、定时任务探索进阶试试插件、网络电台、多设备协同音乐是生活的背景音智能是时代的快捷键。当它们在小爱音箱里相遇你只需要开口剩下的交给 XiaoMusic。愿从今晚开始每一句播放歌曲都能得到最动听的回应。让传统与现代结合黑胶情怀遇上智能科技【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
