嗨，我是小华同学，专注解锁高效工作与前沿AI工具！每日精选开源技术、实战技巧，助你省时50%、领先他人一步。👉免费订阅，与10万+技术人共享升级秘籍！
XiaoMusic 是一个开源的“小爱音箱音乐增强方案”：在你的 NAS 或任意一台电脑上部署一个服务，通过小米账号与小爱音箱打通，利用
yt-dlp自动下载网络音乐，结合本地音乐目录，让小爱音箱像真正的家庭音乐服务器一样自由点歌、搜索播放、循环、收藏。
痛点场景：为什么小爱音箱总是“买前真香，用后吃灰”？
如果你的体验类似，大概会遇到这些场景：
-
本地音乐放不起来：NAS 里有一堆无损音乐，结果小爱音箱只认自家音乐服务，很难直接播放本地文件。 -
想听的歌搜不到 / 要开会员：想听冷门歌、翻唱、电台、直播流，小爱音箱原生能力有限，而 XiaoMusic 通过 yt-dlp把“全网音乐”搬到本地目录。 -
家里多台音箱控制混乱：客厅一个、小孩房一个、卧室一个，每台音箱里的歌单都不一样，还得拿手机点来点去。 -
NAS 明明在线 24×7，却只是个“下载盘”：没有一个优雅的方式把 NAS 的存储能力和音箱打通。
XiaoMusic 要解决的，就是：让小爱音箱彻底变成你家里的“音乐前端”，所有音乐逻辑放到你自己可控的服务上。
核心功能亮点
语音口令控制：真正做到“开口即播”
XiaoMusic 实现了一整套与小爱音箱的语音联动，你只要对小爱说话，不用掏手机：
-
播放歌曲：随机播放本地歌曲 -
播放歌曲+歌名：如“播放歌曲周杰伦晴天”，本地找不到就会用yt-dlp下载后播放 -
上一首 / 下一首 / 单曲循环 / 全部循环 / 随机播放 -
播放列表+列表名：按歌单播放，例如“播放列表其他” -
加入收藏 / 取消收藏 / 播放列表收藏：管理收藏歌单 -
搜索播放+关键词：如“搜索播放林俊杰”，按搜索结果临时生成播放列表 -
本地搜索播放+关键词：只从本地音乐中搜，不会下载新歌 -
刷新列表：拷贝新歌到目录后，用口令刷新索引
还有一个小彩蛋：对小爱说“播放歌曲小猪佩奇的故事”，XiaoMusic 会先下载，再播放这个故事。
本地音乐“吃干榨尽”：多格式 + 自动转码
XiaoMusic 会扫描你挂载的音乐目录，支持多种常见格式：mp3 / flac / wav / ape / ogg / m4a。
对于部分不支持 flac 的音箱型号（如 L05B、L05C、LX06、L16A），可以在设置中打开：
-
「转换为 MP3」 -
「型号兼容模式」
这样就能自动转码成兼容格式播放，老设备也能享受无痛听歌体验。
网络歌单与电台：JSON 一配置，音箱立刻能听电台 / 网络流
除了本地文件，XiaoMusic 还支持网络歌单功能：
-
使用一个 JSON 文件定义多个歌单 -
歌单项可以是电台流（如 m3u8、网络电台）或网络歌曲 URL -
提供 m3u → JSON 的转换小工具，能把现有电台列表快速“迁入” XiaoMusic
来自作者公开的示例（简化版）：
[
{
"name": "测试电台",
"musics": [
{
"name": "测试电台1",
"url": "http://ngcdn001.cnr.cn/live/zgzs/index.m3u8",
"type": "radio"
}
]
},
{
"name": "测试歌单",
"musics": [
{
"name": "测试歌名1",
"url": "http://music.163.com/song/media/outer/url?id=447925558.mp3"
}
]
}
]把这个 JSON 配置到 XiaoMusic 后，你就可以用“小爱播放列表测试电台”这样的口令直接听网络电台。
一键 Docker / NAS 部署：真正的“傻瓜安装”
文档给出的最简 Docker 启动命令如下：
docker run -p 58090:8090 \
-e XIAOMUSIC_PUBLIC_PORT=58090 \
-v /xiaomusic_music:/app/music \
-v /xiaomusic_conf:/app/conf \
hanxi/xiaomusic国内用户可以直接换成镜像站：
docker run -p 58090:8090 \
-e XIAOMUSIC_PUBLIC_PORT=58090 \
-v /xiaomusic_music:/app/music \
-v /xiaomusic_conf:/app/conf \
docker.hanxi.cc/hanxi/xiaomusic配置要点（官方文档已说明）：
-
/xiaomusic_conf：配置文件目录 -
/xiaomusic_music：音乐存放目录（推荐和配置分开） -
XIAOMUSIC_PUBLIC_PORT：NAS 本地访问端口（对外暴露的端口） -
容器内固定使用 /app/music、/app/conf，不要修改
只要容器启动成功，就可以在 Web 界面完成剩余参数配置。
支持 pip 安装 & 本地开发
不想用 Docker？也可以走 Python 生态：
pip install -U xiaomusic
xiaomusic --help
# 或者使用配置文件
xiaomusic --config config.json-
默认监听端口 8090，直接运行xiaomusic即可 -
config.json可以参考仓库中的config-example.json
开发者可以用 pdm 配环境，运行：
./install_dependencies.sh
pdm run xiaomusic.py并通过 http://localhost:8090/docs 查看 API 文档。
多型号小爱音箱广泛适配
官方文档列出了大量已测试支持的型号，包括：小爱音箱、Redmi 小爱音箱 Play、小米 AI 音箱、小爱音箱万能遥控版、小爱音箱 Pro、Xiaomi Sound / Sound Pro 等十余种型号，并说明了部分触屏版需要打开“型号兼容模式”或“特殊型号获取对话记录”。
作者也明确表示：目前几乎所有设备类型都已支持播放，有问题可以通过 Issue 或交流群反馈。
自定义口令 & 插件机制
文档主页强调：XiaoMusic 支持口令自定义，可以写自己的插件，扩展更多玩法。
在“高级篇”里，项目列出了：
-
自定义口令功能 -
多设备单独播放功能设计 -
更多高级配置示例
对于喜欢折腾的人，可以基于现有的语音框架做更多自动化逻辑，比如定时播报、晨间电台、固定时间放儿歌等。
安全提醒与公网访问支持
XiaoMusic 既支持局域网使用，也支持通过域名 + 反向代理暴露到公网（如通过 XIAOMUSIC_HOSTNAME 配置域名），方便在非同一局域网下使用。
同时作者在文档中给出了明确的安全提醒：
-
如果配置公网访问，一定要开启密码登录，并使用复杂密码，避免在公共 WiFi 下使用。 -
不推荐把同一小米账号同时绑定摄像头，以防账号泄露带来的隐私风险。
技术架构：如何把“语音指令”变成“本地音乐播放”
整体架构图
XiaoMusic 借鉴了社区对小爱音箱的通用方案：通过 MiService 等库获取小爱对话记录，并调用小米 TTS/控制接口，将下载好的音频推送到音箱播放。
可以看到，XiaoMusic 位于“小米云端”和“本地音乐库”之间，相当于为小爱音箱增加了一层“自定义控制大脑”。
技术栈与优势概览
| 模块 | 使用技术 | 优势说明 |
|---|---|---|
| Web 后端 | Python + FastAPI | 异步性能好、文档完善、自带 OpenAPI UI。 |
| 前端控制台 | 默认 jQuery 主题，可扩展 Vue 等主题 | 实现简单，易于被第三方前端替换、定制。 |
| 部署方式 | Docker 镜像 + docker-compose + pip | 适合 NAS、家用服务器、开发环境等多种场景。 |
| 音乐获取与处理 | yt-dlp 下载 + ffmpeg 转码 |
支持主流站点和多种格式，解决兼容性问题。 |
| 小米账号与设备 | MiService 等第三方库 | 无需 root 设备，通过云端接口控制音箱。([GitHub][5]) |
| 配置与数据持久化 | 本地 JSON 配置文件 + 挂载目录 | 迁移简单，更换 NAS 只需迁移目录。 |
使用方法：3 分钟从“零配置”到“第一首歌响起”
下面以最常见的 Docker + 局域网 NAS 场景为例，整理一条从 0 到可用的最短路径。（所有示例均来自官方 README / 文档，做了少量整理。）
第一步：启动 XiaoMusic 容器
在 NAS 或任意一台 Linux 服务器上，执行：
docker run -p 58090:8090 \
-e XIAOMUSIC_PUBLIC_PORT=58090 \
-v /xiaomusic_music:/app/music \
-v /xiaomusic_conf:/app/conf \
hanxi/xiaomusic若提示目录不存在，可先创建：
mkdir -p /xiaomusic_{music,conf}或者使用 docker-compose（推荐）：
services:
xiaomusic:
image: hanxi/xiaomusic # 国内可换成 docker.hanxi.cc/hanxi/xiaomusic
container_name: xiaomusic
restart: unless-stopped
ports:
- 58090:8090
environment:
XIAOMUSIC_PUBLIC_PORT: 58090
volumes:
- /xiaomusic_music:/app/music
- /xiaomusic_conf:/app/conf第二步：打开 Web 后台，配置小米账号与设备
-
在浏览器访问：
http://NAS_IP:58090（例如http://192.168.1.100:58090） -
首次进入设置页时：
-
填写 小米账号 与 密码（或 Cookie） -
点击底部“保存”，XiaoMusic 会通过账号获取你的设备列表。
-
-
回到页面顶部，勾选要控制的小爱音箱，再次保存。
此时，你的音箱已经与 XiaoMusic 建立了连接。
第三步：准备音乐目录
-
把本地音乐文件放到 /xiaomusic_music对应的目录下（挂载在容器内的/app/music）。 -
支持 mp3、flac、wav、ape、ogg、m4a 等格式。 -
复制完后，对小爱说一句“刷新列表”，就能让 XiaoMusic 重新扫描歌曲。
如果你有网络歌单：
-
写一个 JSON 文件（如 network_playlist.json） -
在 Web 设置或配置文件中指定该歌单路径 -
即可通过“播放列表+列表名”来播放对应歌单。
第四步：体验语音点歌
现在可以试试：
-
“播放歌曲” -
“播放歌曲周杰伦晴天” -
“搜索播放林俊杰” -
“播放列表测试歌单”
XiaoMusic 会根据本地/网络资源自动完成下载、转码和播放流程。
界面效果与交互体验
默认 Web 控制台：以实用为主
官方文档指出，目前默认 Web 控制台的界面比较简洁，主要提供：
-
小爱设备列表选择 -
小米账号与密码 / Cookie 配置 -
音乐目录 / 下载目录 / 网络歌单等参数配置 -
下载日志文件、调试信息等辅助功能
虽然不是“花里胡哨”的现代化 UI，但胜在清晰直接，适合作为 NAS 管理后台的一部分。
第三方前端主题：更好看的控制面板与移动端体验
社区已经围绕 XiaoMusic 做了一些 UI 增强项目：
-
xiaomusicUI：基于 Vue.js 的前端页面，专门为 XiaoMusic 提供设备控制、播放列表、账号设置、设置等可视化面板。 -
XMusicPlayer：为 XiaoMusic 编写的移动端播放器主题，更适合手机访问和操作。
这些项目通过调用 XiaoMusic 的 HTTP 接口，把原本偏“工具型”的后台，变成更日常、好看的音乐控制台。
项目成长轨
XiaoMusic 还提供了一张 Star 历史曲线图，可以看到项目从最初发布到如今 7k+ Star 的成长过程：
典型应用场景
把 NAS 变成真正的家庭音乐中枢
对于已经有 NAS 的用户，XiaoMusic 让 NAS 不再只是“下载机”或“备份盘”，而是：
-
集中存储全家人的音乐、听书、播客 -
多个小爱音箱都从同一音乐库取资源 -
通过网络歌单统一管理电台与网络音乐
儿童与家庭故事机
搭配网络歌单和 epub2mp3 这样的工具，XiaoMusic 可以变成“故事机”：
-
用 epub2mp3 把电子书转成 MP3 -
放到 XiaoMusic 的音乐目录 -
小孩只要对小爱说“播放歌曲小猪佩奇的故事”，就能听故事
多房间音乐 & 分区播放
在“多设备单独播放功能设计”等文档设计中，XiaoMusic 支持根据不同的设备 ID 进行控制，使每个房间的小爱可以播放不同的内容。
-
客厅播放轻音乐 -
书房播 Lo-fi 作为工作 BGM -
小孩房播放儿歌与故事
所有逻辑都在一套 XiaoMusic 服务内管理。
异地访问与远程点歌
通过反向代理和内网穿透（如 frp），可以把 XiaoMusic 暴露成公网服务，让不在同一局域网的小爱音箱也能访问到你的音乐库。
当然，文档也多次强调了要注意账号安全与密码复杂度。
同类项目
围绕“小爱音箱 + 音频内容”，已经形成了一个小生态。下面选取几个与 XiaoMusic 关系密切的项目做个对比。
| 项目名称 | 定位 | 主要功能 | 典型场景 |
|---|---|---|---|
| XiaoMusic（本项目） | 小爱音箱音乐中枢 | 使用 yt-dlp 下载网络音乐 + 管理本地音乐目录；通过语音口令控制播放、歌单、收藏等；提供 Docker / pip 部署与 Web 配置界面。 | 家庭 NAS / 家用服务器上的综合音乐解决方案 |
| xiaomusicUI | 基于 XiaoMusic 的 Vue 前端 | 为 XiaoMusic 提供更丰富的 Web 操作界面，包括设备控制、播放列表、账号设置和设置页面。 | 希望在浏览器中拥有更美观控制台的用户 |
| XMusicPlayer | XiaoMusic 移动端播放器主题 | 针对手机等移动端，为 XiaoMusic 提供播放界面和交互体验。 | 用手机控制 XiaoMusic、随时查看当前播放情况 |
| epub2mp3 | 听书内容生产工具 | 使用 Microsoft Edge TTS 将 EPUB 电子书转为 MP3，可与 XiaoMusic 搭配，用小爱音箱播放有声书。 | 把电子书批量转换成有声书，在家中音箱播放 |
从表中可以看出：
-
XiaoMusic 是“核心引擎”：负责与小爱音箱交互、下载/索引音乐、提供 API 和 Web 配置。 -
xiaomusicUI / XMusicPlayer 是“界面增强件”：让 XiaoMusic 更好看、更好用。 -
epub2mp3 等工具则是“内容补充来源”：生成更多适合用小爱听的音频内容。
如果你只想让小爱音箱变得更能听歌，直接部署 XiaoMusic 即可；如果想要更强的 Web 或移动端控制体验，再搭配其它前端项目一起使用会更舒服。
总结
XiaoMusic 已经从一个“个人小工具”，成长为拥有 7.9k+ Star、完整文档、丰富生态 的成熟项目：
-
通过 yt-dlp与本地目录结合，解决了小爱音箱“内容被平台锁死”的痛点； -
通过语音口令体系和网络歌单，让“我想听什么，就对小爱说什么”成为现实； -
借助 Docker / pip，使其在 NAS、家用服务器、甚至普通电脑上都能一键部署； -
配套的 UI 主题与周边工具，则把整个体验延伸到了 Web、移动端和听书场景。
如果家里的小爱音箱正在积灰，或者 NAS 一直没有找到称心如意的音乐方案，XiaoMusic 值得你花一个晚上折腾一下。
项目地址
https://github.com/hanxi/xiaomusic
