企业官网建设流程全解析

小爱音箱本地音乐播放：说一句自动下载，完整上手指南

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

下班回家喊一句“小爱，播放周杰伦”，音箱直接放出了《晴天》。第一次是它从网上自动下好再播，第二次开始就是本地直出。这就是 XiaoMusic，一个让小米小爱音箱用语音控制播放音乐、下载交给 yt-dlp 的开源工具。

一、关键词区

核心关键词：小爱音箱音乐播放，XiaoMusic，语音控制，自动下载

长尾关键词：小爱音箱怎么播放本地音乐，XiaoMusic安装教程，Docker部署XiaoMusic，音箱自定义歌单，智能音箱音乐下载工具，开源音乐播放方案，小爱音箱语音口令，家庭音乐服务器搭建，音箱播放列表管理，NAS部署音乐服务

二、它解决了什么问题

小爱音箱一直能放歌，但曲库绑在某个在线平台上：想听的歌没有，会员到期曲库缩水。XiaoMusic 把曲库搬回你自己的设备，三件事都变了：

• 歌曲被平台限定→ 曲库换成你自己的文件加网络下载源，说一句就自动下载播放，不用找“有什么能听”
• 配置门槛高→ 一条 docker 命令跑起来，账号设备都在网页界面里填，不用改配置文件
• 语音口令白学了→ 原生指令“播放歌曲 / 下一首 / 单曲循环”全部兼容，不用记新口令

它的工作路径很直白：收到口令先查本地曲库，有就直接放；没有就联网下载到 music 目录再放。下载过的歌会一直留在本地，第二次播放不用等。

设备兼容性也不用操心。官方 README 里列了从小爱音箱、Redmi 小爱音箱 Play 到 Xiaomi Sound 的完整型号清单，均已测试过。家里有多台音箱的话，一个服务可以同时管理，网页上切换控制哪一台。

本地支持的格式也不挑，这几种都能扫出来：

• mp3，最常见
• flac、ape、wav，无损格式
• ogg、m4a，其他常见格式

三、5 分钟跑起来 🚀

Docker 是最短路径。两条命令的事：

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

两个目录分别挂载进容器：music 存音乐文件，conf 存配置，建议分开放。目录不存在会报错，先跑第一条建一下就行。启动后打开http://局域网IP:58090，在设置页填这几项：

保存之后，设备列表里能看到你的小爱音箱，就说明部署成功了；播放列表页面再刷出歌单，就可以正式点播放了。同地址后面加/docs还能看到完整的接口文档，爱折腾的可以翻一翻。

国内拉镜像慢的话，把 image 换成docker.hanxi.cc/hanxi/xiaomusic。更习惯 Pip 的话，pip install -U xiaomusic后执行xiaomusic --config config.json，配置文件参考仓库里的 config-example.json 即可。

网页界面也不只是填设置：点歌、搜索歌名、管理播放列表都在页面上做，配合语音口令，一个动手、一个动嘴，两条路都通。

四、按场景学功能 🎵

不照模块背功能，直接上四个高频场景。

让音箱自己下载歌曲

• 你想干嘛：歌不在本地库，但又不想自己找链接下载
• 怎么操作：直接说“播放歌曲 周杰伦 晴天”，库里有就放，没有就自动搜、下、播
• 效果：第一次等几秒，第二次起就是纯本地体验，下载的文件会沉淀在 music 目录里

用老语音口令控制新曲库

• 你想干嘛：保持原来小爱的使用习惯，不学新口令
• 怎么操作：什么都不用做，“下一首 / 上一首”切歌，“单曲循环 / 随机播放”换模式，“停止播放”停歌
• 效果：音箱大脑还是小爱，只是曲库换了，全家不用培训就会用

按目录名播放歌单

• 你想干嘛：把一大堆音乐组织成一个个歌单
• 怎么操作：在 music 目录下建子目录，比如“流行”“古典”，说“播放歌单 流行”就放对应目录
• 效果：目录结构就是歌单结构，复制了新文件说“刷新列表”即可同步进来

接入在线电台与网络歌单

• 你想干嘛：连没有音乐文件的电台也想一起播
• 怎么操作：设置页填入分享的歌单 json 链接（music_list_url）或本地 json 路径，电台条目 type 设 radio 就会持续播放
• 效果：本地文件和在线流进同一个播放列表，语音切换无缝衔接

不想下载、就想在线听的话，口令里还有“在线播放”，直接联网放，不存到本地。收藏也是语音管的：说“加入收藏”当前歌就进收藏歌单，“取消收藏”拿出去，“播放歌单 收藏”整单循环。

五、进阶玩法

如果你只想加自定义口令：在config.json的user_key_word_dict里写一条口令到动作的映射，对应逻辑放进plugins/目录（容器部署记得把这个目录挂载出来）。

{ "user_key_word_dict": { "测试自定义口令": "exec#code1(\"hello\")" } }

仓库自带的code1.py、httpget.py可以直接当模板抄。改完重启即可生效。

如果你只想让音箱每天定时放歌：用定时任务配置（crontab 格式），任务类型支持 play、stop、tts 文字转语音、刷新列表、设置音量等。

[ {"expression": "0 8 * * *", "name": "tts", "arg1": "早上好，该起床了"}, {"expression": "0 22 * * *", "name": "stop"} ]

任务可以指定 did，多台音箱能分别定时；表达式支持加# workday注释，只在工作日触发。改完重启即可生效。

如果你只想批量导入已有音乐：把音乐文件拷进 music 目录，子目录也按目录名建好，然后在网页点“刷新列表”或对小爱说“刷新列表”。之后所有歌都能被语音点到，按目录名整单播放。

六、踩坑速查 ⚠️

登录失败、设备列表不显示

1. 关掉本地代理
2. NAS 容器网络从 bridge 改成 host
3. 米家 app 退出重登
4. mi.com 官网重新登录一次（滑块验证）
5. 核对设置里账号密码无误

语音口令没反应

1. 设置页打开语音口令（获取对话记录）开关
2. 检查口令前缀，默认是“播放歌曲”
3. 重启一次容器
4. 查日志确认对话记录拉取正常

歌曲链接打不开、没声音

1. 确认 hostname 是音箱能访问的局域网 IP
2. 确认端口和实际端口映射一致
3. 确认音箱与服务在同一局域网
4. 试试打开型号兼容模式

flac 等格式播放不了

1. 打开“转换为 MP3”选项
2. 或提前批量转成 mp3
3. 注意转换会占 CPU，体验略受影响

七、安全与注意事项

• 别用主力小米账号：单独注册一个专用号，真泄露了不用改全家密码
• 该账号别绑定摄像头：账号密码一旦泄露，监控录像跟着有风险
• 要公网访问就开网页密码：设一个复杂密码，防止陌生人动你的曲库

八、资源与延伸

更多配置与教程看这里：

• FAQ问题集合
• 文档汇总
• 定时任务配置格式

社区方面，README 讨论区挂了 QQ 群和微信群入口，卡住先去群里问一嘴通常有现成答案。

另外还有多个第三方主题和配套小程序、手机 App，README 的“相关资源”一节都列了，按需取用。

音箱不再把曲库绑在平台上，听到的都是你自己的库。现在就 docker run 起来试试。

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