企业官网建设流程全解析

如何让小爱音箱免费放歌：XiaoMusic 本地音乐服务器部署指南

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

XiaoMusic 是面向小爱音箱的开源音乐服务器，部署在 NAS 或家里任意一台常开的机器上，它用 yt-dlp（一个开源音视频下载工具）把歌曲下载下来，让音箱从平台曲库切换到你的本地曲库。

小爱音箱自带的音乐服务绑在平台上：部分歌曲提示需要会员，曲库随时变动，孩子想听的故事也不稳定。更关键的是，这些歌曲并不留在音箱上，每次都依赖平台链路播放。XiaoMusic 的做法是：你用语音报出歌名，它在本地曲库查找，找不到就在线搜索并下载，之后播放就走本地文件，不再受平台限制。

一、XiaoMusic 快速部署：Docker 一条命令跑起来

最短路径是 Docker 部署（Docker 是一种把程序连同运行环境打包成镜像的容器工具，NAS 上一般预装）：

docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic

三个参数各管一件事：58090:8090是端口映射，58090 用主机上空闲的端口即可，8090 是服务内部端口不要改；两个-v分别把音乐目录和配置目录映射到主机，建议分开存放。国内网络环境可将镜像换成docker.hanxi.cc/hanxi/xiaomusic。如果报目录不存在，先执行mkdir -p /xiaomusic_music /xiaomusic_conf建好再启动。

习惯 Python 环境的话也可以用 pip 方式：

pip install -U xiaomusic xiaomusic --config config.json

config.json直接照仓库里的 config-example.json 改。

二、配置小米账号：只有两处必填

服务起来后，浏览器访问http://NAS_IP:58090进入 Web 后台，配置只有两步：

1. 在设置页填入小米账号和密码（带*号的项是必填项），保存后页面会拉取到你的音箱设备列表。
2. 确认音乐存放目录，其余配置项不用时保持默认即可。

保存账号前看不到设备列表是正常的，这是设计如此。如果登录失败（日志里提示 Login Failed），FAQ 里列了常见解法：关本地代理、米家 App 重新登录、或在小米官网完成一次人脸/滑块验证，详见 docs/issues/99.md。

三、语音口令：你能对音箱说什么

部署后，对音箱直接说这些就行：

• “播放歌曲周杰伦晴天”：核心玩法。先在本地曲库匹配，没有就在线搜索，用 yt-dlp 下载成 mp3 后播放，下次再点同一首就是纯本地速度。
• “上一首 / 下一首 / 暂停 / 关机”：基础播放控制。
• “单曲循环 / 全部循环 / 随机播放”：切换播放模式，音箱会用 TTS 语音确认。
• “播放歌单其他”：播放音乐目录下指定子目录的全部歌曲，目录名即歌单名。
• “加入收藏 / 取消收藏”：把当前歌加入或移出收藏歌单。

口令词本身可以改。配置文件里的user_key_word_dict段把任意短语映射到命令，还支持exec#code1(...)、exec#httpget(...)这类写法去调用自定义函数，仓库 plugins/ 目录带了两份示例插件（TTS 播报、发起 HTTP 请求），照着写就能给自己的音箱加专属指令。

四、本地歌单与网络歌单：两种曲库来源

本地库扫描音乐目录下的 mp3、flac、wav、ape、ogg、m4a 文件生成歌单；下载的歌曲统一是 mp3。已知 L05B、L05C、LX06、L16A 等型号不能直接播 flac，遇到这种情况在设置里打开“转换为 MP3”即可。

除本地文件外，XiaoMusic 还支持配置一个 json 格式的网络歌单，电台和歌曲都可以放，也可以直接用别人分享的链接。仓库自带 m3u 文件转换工具，能把 m3u 电台文件转成网络歌单格式，具体用法见 docs/issues/78.md。

五、Web 后台：XiaoMusic 管理界面能做什么

后台页面承担了日常管理的绝大部分工作：搜索并下载歌曲、删除歌曲（删除先进回收站，有一次反悔机会）、切换多台音箱设备、拖动进度条定点播放，底部还能看到当前播放歌曲名、时长和设备音量条。

六、长期使用 XiaoMusic 的建议与注意

• 先了解维护状态：README 顶部明确标注项目已停止维护，不再接受新功能开发与 bug 修复，作者建议迁移到社区接力项目 songloft。已部署的使用不受影响，但新增需求建议到接力项目提。
• 安全设置不可省：如果要让后台走公网访问，务必开启密码登录并设复杂密码；同时不建议把这个小米账号与摄像头等设备共用，账号泄露风险会连带扩散。
• 语音口令功能要随手关：语音控制依赖“获取对话记录”开关，频繁拉取对话记录可能触发登录失败，不听歌时可以在后台把它关掉。
• 设备兼容性：README 列了 L06A、L07A、S12、LX06、LX01 等已测试型号，未列出的型号一般也能播；个别型号需要开启“特殊型号获取对话记录”或“型号兼容模式”，遇到语音控制无效时优先查 docs/issues/99.md。

七、小结与入口

XiaoMusic 解决的核心问题很单一：把小爱音箱的音乐来源从平台曲库换成你自己的本地曲库，一条 Docker 命令就能起步。

• 项目说明与完整功能列表：README.md
• 新手常见问题与报错处理：docs/issues/99.md
• 文档站点入口：docs/index.md
• 核心源码目录：xiaomusic/

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