企业官网建设流程全解析

小爱音箱自定义音乐播放完整指南：从部署到语音点歌

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

对着小爱音箱说"播放我整理的歌单"，音箱只回一句"暂不支持"。你的歌单卡在平台上，本地音乐库却够不着。XiaoMusic 是小爱音箱自定义音乐播放方案：它在本地跑一台音乐服务器，用 yt-dlp 在线下载歌曲，再用语音口令接管播放，让你想播什么就播什么。

项目速览

• 它是什么：运行在 NAS 或树莓派上的开源音乐服务器，音乐用 yt-dlp 下载，MIT 协议
• 解决什么：小爱音箱只能播平台曲库的问题，本地 mp3、flac 等 6 种格式文件和网络歌单都能播
• 适合谁：有局域网设备、想脱离平台曲库的 18 种已测试型号的小爱/小米音箱用户

原理拆解

把 XiaoMusic 想成点歌台接线员：它每秒拉取一次小爱的对话记录（对话记录即音箱后台保存的语音交互日志），一旦发现你说了以"播放歌曲"开头的口令，就立刻用局域网音乐链接打断原流程，让音箱改播你指定的歌。正因如此，口令必须带对前缀，说"播放音乐"它听不懂。

快速上手

新手一键路线

运行容器，映射 58090 到 8090 端口并挂入音乐、配置目录：

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

预期：容器启动后访问http://NAS_IP:58090打开 Web 后台。在设置页填入小米账号密码，设备列表自动出现，再按需勾选设备、保存带*的必填项即可。

⚠️ 目录不存在先mkdir -p创建 ⚠️ 8090 是容器端口，不要改 ⚠️ 登录失败先查 FAQ 问题集 ⚠️ 国内拉取困难可换国内镜像源

详见 FAQ 问题集合，镜像拉取失败、无声等问题都有对应解法。

源码路线

克隆仓库并准备 PDM 依赖环境：

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic cd xiaomusic ./install_dependencies.sh pdm install

预期：依赖安装完成，无报错。启动服务：

pdm run xiaomusic.py

预期：默认监听 8090 端口，访问http://localhost:8090/docs可看 API 接口文档。配置文件参考 config-example.json。

实战演示

场景一：语音口令点歌

核心目标：脱手用语音控制本地音乐播放。

基础操作：

1. 把 mp3、flac 等文件放进挂载的 music 目录，每个子目录自动成为一个播放列表
2. 对音箱说"播放歌曲周杰伦晴天"，命中即播；说"播放歌单某某"按目录名播放
3. 用"下一首""单曲循环""加入收藏"等口令切换和收藏

进阶技巧：口令词可在key_word_dict中自定义，"播放歌单第几个+列表名"能精确点歌；说一个本地没有的歌名，XiaoMusic 会先在线下载成 mp3 再播放，省去手动搜索下载。

小爱音箱 Web 后台：左侧管理设备与账号，中间按分类点播，底部控制播放与音量

场景二：播放网络歌单

核心目标：不占硬盘，直接播电台和在线歌曲。

基础操作：

1. 打开设置页，在自定义歌单输入框填入 JSON 歌单内容
2. 歌单支持电台（m3u8 格式）和在线歌曲两种条目，格式示例：

[{"name":"英文电台","musics":[ {"name":"BBC NEWS","url":"https://stream.live.vc.bbcmedia.co.uk/bbc_world_service","type":"radio"}]}]

3. 保存后对音箱说"播放歌单英文电台"即可收听

进阶技巧：type为radio的条目持续直播不切歌；网页自带 m3u 转换工具，可把电台文件直接转成 JSON 歌单，详见 网络歌单用法。

后台播放列表：按分类检索歌曲，右上角切换目标设备

生态与扩展

• Python 插件：plugins/ 下每个文件名即函数名，配合口令词可挂任意自定义动作
• JS 在线音乐插件：在 Web 后台加载第三方音源，在线歌曲走代理播放
• 第三方主题：pure、Tailwind、移动端播放器等主题已随仓库打包
• 社区维护：issue 区沉淀 FAQ 与歌单分享；注意 README 顶部公告项目已停止维护，可关注社区接力项目

写在最后

XiaoMusic 把小爱音箱从平台曲库的播放器变成你自己的音乐服务器。用 Docker 一键拉起，对着音箱喊出歌名，剩下的交给它。

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