小爱音箱放本地音乐的完整指南：xiaomusic 从安装到开口点播

小爱音箱放本地音乐的完整指南：xiaomusic 从安装到开口点播

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

周六早晨你随口一句"小爱同学，放周杰伦的晴天"，音箱没去在线平台找歌，而是直接从你 NAS 的音乐目录里把文件放了出来。这就是 xiaomusic 干的事：跑一个服务，让小爱音箱播放本地音乐，还能全程语音控制。

装之前，先搞清三件事

• 要什么硬件？一台小爱音箱（L05B、L05C、LX06 等二十多款型号都测试过），加一台能长期开机的电脑或 NAS。
• 要什么软件？Docker 环境最省事；没有 Docker 也可以用 Python 3.8+ 配 pip 直接跑。
• 网络有什么要求？音箱和跑服务的机器在同一局域网，音箱本身能正常联网就行。

最省事的装法：Docker Compose 一条配置

写一个 docker-compose.yml，就这几行：

services: xiaomusic: image: hanxi/xiaomusic ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf

两个挂载路径换成你自己的目录即可，音乐放 /app/music 对应的目录，配置放 /app/conf 对应的目录，目录不存在先mkdir -p建好。国内拉镜像慢，可以把 image 换成 docker.hanxi.cc/hanxi/xiaomusic。不想用 Compose 直接 docker run 也行，参数完全一样，写法见官方 README。

启动后浏览器打开http://你的服务器IP:58090，看到这个面板就算装好了：

让音箱认识你：账号登录与 DID 怎么拿

按操作顺序来，每步一个动作：

1. 网页左侧点"账号设置"，填你的小米账号和密码，保存。
2. 回到"小爱设备控制"，系统会自动列出账号下的小爱音箱——列表是空的，多半是账密没保存成功或音箱不在线。
3. 选中你的音箱，复制它的 DID，填进配置的 mi_did 项。现在网页设置页就能直接填，不用再折腾环境变量。

DID 在哪看，看这张图：右上角就是设备切换下拉框，选中哪台就控哪台。

🎵 把音乐喂给它

把音乐文件放进 compose 里挂载的音乐目录，子文件夹按歌手或专辑分，界面里就会按目录生成歌单。支持的格式：

• mp3
• flac（L05B、L05C、LX06、L16A 这几个型号不支持）
• wav
• ape
• ogg
• m4a

格式兼容性差的型号，在设置里打开"转换为MP3"和"型号兼容模式"即可。音乐库在"播放列表"页管理：全部、所有歌曲、收藏、下载四个标签，能搜索、能播放、能删。本地没有的歌，说"播放歌曲+歌名"时会走 yt-dlp 在线下载后再播——这就是项目简介里"音乐使用 yt-dlp 下载"的含义。

🎤 动嘴不动手：常用语音指令

装好后最常用的几句：

• "播放歌曲周杰伦晴天" → 本地有就播本地，没有就在线下载再播
• "下一首" / "上一首" → 切歌
• "随机播放" / "单曲循环" → 切换播放模式
• "播放歌单收藏" → 播放你收藏的那批歌
• "30分钟后关机" → 到点自动停止播放
• "暂停" → 停止当前播放

想加自己的口令，改配置里的 key_word_dict / user_key_word_dict 就行，指令处理逻辑在 xiaomusic/command_handler.py。

想先照抄一套默认口令，看 config-example.json。

⚠️ 出问题了先看这里

拿不准就盯日志，一条命令：docker logs -f xiaomusic。另外网页设置页底部能直接下载日志文件，反馈问题时带上会快很多。

再往后玩一玩

三个进阶玩法，都不用改代码：

• 多设备：mi_did 支持逗号分隔多个 DID，一个服务带几个房间的音箱。
• 网络歌单：配一个 JSON 歌单，支持电台和歌曲；仓库里还带了 m3u 转网络歌单的转换工具，电台文件可以直接转。
• 定时播放：crontab_json 里填 cron 表达式任务，比如每天早上 8 点播"周杰伦"歌单：

[ {"expression": "0 8 * * *", "name": "play_music_list", "did": "你的设备DID", "arg1": "周杰伦"} ]

🔒 别把门开给陌生人

• 要公网访问，就开密码登录（httpauth 相关配置项），密码设复杂一点。
• 别用绑了摄像头的小米账号——账号密码一旦泄露，监控录像可能跟着泄露。
• 公共 WiFi 下别裸奔，这个服务持有你小米账号的凭据，泄露代价不小。

周六早上那句"放周杰伦"从此有了着落：音乐自己说了算，音箱只负责出声。用起来有 bug 或者有想法，直接去 xiaomusic 项目页面的 Issues 里提一个，带上设置页下载的日志，问题会定位得快很多。

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