企业官网建设流程全解析

家庭客厅里，xiaomusic 如何让小爱音箱播放本地音乐跑通

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

xiaomusic 是一个把 NAS 或电脑上的本地音乐接到小爱音箱上的开源服务。能语音播放 mp3、flac，也能从网上搜歌、下载。适合想绕开流媒体平台的家庭用户，也适合想改代码折腾的人。

你的曲库为什么播不了

手机里的歌都躺在本地，可小爱只能播它绑定的平台曲库。你喊"播放周杰伦"，它也不会播你自己的收藏。xiaomusic 把你自己的音乐目录接到音箱上，再拦下语音口令。这样"播放歌曲+歌名"走的是你的曲库，不是平台的。它每秒轮询一次对话记录再打断，所以口令和播放之间有轻微延迟，属正常。

先判断人群，再走搭建路径

先判断你属于哪一类，再走对应的路径。每条路径都是三步：前置条件、操作、怎么确认跑起来了。

只想要个能跑的服务

前置条件：有 Docker 的机器（NAS 或服务器），且它和音箱在同一局域网。

目录不存在就先建好：

mkdir -p /xiaomusic_music /xiaomusic_conf

再起容器，music 存歌，conf 存配置：

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

58090 是你 NAS 上的本地端口，8090 是容器内端口，后者别改。

拉镜像慢的话，把镜像名换成国内源：

docker.hanxi.cc/hanxi/xiaomusic

确认跑起来：浏览器打开http://NAS_IP:58090，换成 NAS 实际地址。在设置页面输入小米账号密码，看到设备列表就是跑起来了。

想用 Python 跑

前置条件：Python 3.10 以上，默认端口同样是 8090。

先装包，再用配置文件启动：

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

配置模板看根目录的 config-example.json。复制为 config.json，先填账号和音乐目录。

确认跑起来：访问http://localhost:8090，同样输入账号拿到设备列表。

要改代码的

前置条件：把仓库克隆下来：

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic

装依赖并启动服务，pdm 管理整个环境：

./install_dependencies.sh pdm install pdm run xiaomusic.py

确认跑起来：默认监听 8090，浏览器打开 /docs 能看到接口文档，主页能打开即可。

开箱后你得到什么：小爱音箱本地音乐播放

装好之后，先得到一套完整语音口令。"播放歌曲"播本地曲库，"上一首/下一首"切歌。"单曲循环"、"全部循环"、"随机播放"设模式。"加入收藏"、"取消收藏"管收藏，"关机"停播。

后台页面也立即可用。音乐目录下每个子目录会被识别成一个歌单，双击歌曲就能播。还有全部歌曲、收藏、下载三个页签，方便查库。

格式覆盖也宽。mp3、flac、wav、ape、ogg、m4a 都能扫到。L05B、L05C、LX06、L16A 等型号放不了 flac，在设置里打开【转换为MP3】即可。L06A、L07A、LX06、L16A、LX01 都在已测名单里。共 18 款，完整对照见 README.md。

想再挖深一点：在线歌曲和自定义口令

没有本地曲库也行，xiaomusic 会下歌。说"播放歌曲+歌名"，它用 yt-dlp 在线搜，下载成 mp3 再播。

网络歌单用 JSON 配置，电台和歌曲都支持，也能直接填别人分享的链接。电台类歌单会一直循环同一条目，适合挂在线电台。m3u 文件也能用自带工具转成这个格式，详见 docs/issues/78.md。

口令词也能自己改。配置里 key_word_dict 字段能把新词映射到现有命令。插件代码在 xiaomusic/plugins/ 目录，httpget.py、httppost.py 是 HTTP 类示例。

常见卡点：设备不显示、没声音、口令失灵

账号密码填了，后台却看不到设备列表。多是小米账号登录失败，代理或验证状态导致。关掉代理，在局域网环境重新登录 mi.com。还不行，就在米家 app 重新登录后再保存一次。

日志显示正在播放，音箱却没声。多半是音箱拿歌的地址不对。先确认 hostname 填的是局域网 IP，不是 localhost。再把日志里的歌曲链接复制到浏览器打开，打不开就是端口或地址问题。

后台点着能播，说"播放歌曲"却没反应。语音口令是单独的开关。要在设置页打开【获取对话记录】。首次保存 did 后，记得重启一次容器。

如果要挂公网，先开密码登录。别把绑了摄像头的小米账号拿出来用。

第一步做什么

适合谁：家里有 NAS 或常开电脑的，以及想给小爱音箱扩音乐源的人。第一步：打开根目录 config-example.json，先认识后面会改的字段。卡住了就查 docs/issues/99.md 的 FAQ。

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