XiaoMusic 入门指南：3 步部署，让小爱音箱免费播放全网歌曲

XiaoMusic 入门指南：3 步部署，让小爱音箱免费播放全网歌曲

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

XiaoMusic 是一个开源的音乐播放工具，通过 yt-dlp 下载音乐并推送到小爱音箱，让设备脱离原有平台的曲库限制，免费点播全网歌曲、播放网络歌单与本地曲库。它部署在 NAS、树莓派或任意 Linux 机器上，通过 Web 控制台完成配置，之后直接用语音控制小爱同学即可。

本文会带你完成：

• 30 分钟内的部署与验证流程
• 3 条最常用的语音口令实测
• 网络歌单、多设备分组、自定义插件 3 个进阶玩法
• 一张故障速查表

先看效果：三条口令的实际表现

点播全网歌曲

对小爱同学说"播放歌曲周杰伦晴天"，XiaoMusic 会先通过 yt-dlp 把这首歌下载到本地music/download目录，再推送到音箱。第二次再点同一首歌时由于已有缓存，响应速度会明显加快。

切换播放模式

以下口令直接触发对应动作：

• "单曲循环" - 重复播放当前歌曲
• "随机播放" - 随机顺序播放
• "下一首" / "上一首" - 切换歌曲
• "关机" - 停止播放

口令到命令的映射全部是数据驱动的，核心逻辑在 xiaomusic/command_handler.py 里，可以在config.json中完全自定义。

下载并播放有声故事

对小爱同学说"播放歌曲小猪佩奇的故事"，XiaoMusic 会先用 yt-dlp 搜索并下载对应的音频文件，再播放。这个能力对家中有孩子的场景特别有用，不用提前准备本地文件，说一声就行。

30 分钟从零跑通

准备环境

XiaoMusic 支持两种安装方式，任选其一：

• Docker（推荐）：镜像内已包含 Python、ffmpeg、node 等全部依赖，适合 NAS、树莓派
• Pip 安装：适合已有 Python 环境的机器

两种方式的 Web 端口都是 8090，Docker 默认映射为宿主机的 58090。

Docker 启动

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

参数说明：

• /xiaomusic_music是宿主机上的音乐存储目录，对应容器内/app/music
• /xiaomusic_conf是宿主机上的配置存储目录，对应容器内/app/conf
• 两个目录建议分开，便于单独备份
• 国内网络环境可把镜像前缀换成docker.hanxi.cc/hanxi/xiaomusic

如果提示目录不存在，先执行mkdir -p /xiaomusic_music /xiaomusic_conf创建。

Pip 启动

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

config.json可参考仓库根目录的 config-example.json，关键字段：

{ "account": "小米账号", "password": "小米密码", "music_path": "music", "conf_path": "conf", "port": 8090 }

登录小米账号并绑定音箱

浏览器访问http://NAS_IP:58090进入 Web 控制台。首次进入需要在设置页输入小米账号和密码并保存，系统会自动拉取该账号下的小爱音箱设备列表。

已测试支持的型号覆盖目前在售的小爱音箱系列，包括 L06A、L07A、LX06、LX01、L05B、L05C、L16A、L17A、L15A、LX05、LX5A、L09A 等，完整清单见 README 的设备支持章节。

验证：发一条口令

音箱开机后对小爱同学说"播放歌曲晴天"。如果音箱开始播放，整个链路就跑通了。Web 控制台的播放列表页也会同步显示当前正在播放的歌曲，进度条会实时更新。

进阶玩法

网络歌单与 M3U 转换

除了本地音乐库，XiaoMusic 还支持 JSON 格式的网络歌单，可以直接填一个电台或歌曲 URL 列表，用"播放歌单"口令触发。

仓库自带一个 M3U 转换页 xiaomusic/static/default/m3u.html，把.m3u8/.m3u电台文件粘贴进去就能转成 JSON 歌单，省去手写。

多设备分组

家里有多台小爱音箱时，可以在 config-example.json 的group_list字段配置分组，格式为组名:设备ID1,设备ID2，用逗号分隔多个组。之后可以用"播放歌单+组名"的口令让整个分组同步播放，实现客厅和卧室放同一首曲子，或者各放各的。

自定义语音口令与插件

config.json中提供两个口令字段：

• key_word_dict：口令到内置命令的映射
• user_key_word_dict：用户自定义口令

示例：

"key_word_dict": { "播放周杰伦的歌": "singer_play", "测试口令": "exec#code1(\"hello\")" }

第二种exec#函数名的形式可以调用 plugins/ 目录下任意 Python 插件。仓库自带了一个示例插件 plugins/code1.py，触发后会调用xiaomusic.do_tts让音箱朗读自定义文本。基于这个机制，你可以把音箱接到任意第三方服务，比如定时播报天气、触发智能家居场景等。

故障速查

遇到其他问题可以从 Web 设置页底部"下载日志文件"按钮拿到日志，搜索确认里面没有账号密码后再反馈。常见问题集合参考 docs/issues/99.md。

安全与长期运行

• 不要暴露公网：config.json的hostname默认是局域网 IP，保持这样即可。如果一定要公网访问，务必开启disable_httpauth: false并设置强密码，避免小米账号泄露。
• 账号隔离：不要用绑定了摄像头的主小米账号，账号一旦泄露，监控录像也会跟着暴露。
• 定期备份：conf目录存了账号凭据与配置，music目录存了本地曲库，两者分开备份最方便。
• 磁盘清理：下载的 MP3 会持续累积，xiaomusic/crontab.py 里已经内置了凌晨 3 点清理临时文件的定时任务，也可手动定期删除music/download下的旧文件。

小结

XiaoMusic 把"小爱音箱只能听平台曲库"这件事变成了"小爱音箱能听任何 yt-dlp 能下载的音乐"。30 分钟部署完，语音口令直接生效，之后按需扩展网络歌单、多设备分组或自定义插件，就是完整的使用路径。

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