企业官网建设流程全解析

XiaoMusic 快速上手指南：把小爱音箱变成本地音乐播放器

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

晚上十点，你对客厅的音箱说"播放歌曲周杰伦晴天"，音箱真的响了起来。这首歌的来源不是某个在线平台，而是你自己 NAS 上的一个 mp3 文件。XiaoMusic 做的事，就是把小爱音箱的语音入口，变成你自己音乐库的播放入口。

项目速览

XiaoMusic 是一个面向小爱音箱的本地音乐播放工具，核心逻辑是：音乐库放在你的 NAS 或电脑上，音箱只负责播放。对音箱说歌名，它就播本地库里的歌；库里没有的歌，会先通过 yt-dlp 下载下来再播放。播放、切歌、随机、收藏、定时关机等语音口令都是内置的，口令本身也支持完全自定义。项目用 Python + FastAPI 编写，带 Web 管理后台，Docker 一条命令即可部署到 NAS 或普通电脑，已测试支持 L05C、S12、L17A、LX06 等 20 多款小米音箱型号。

三步部署

第一步，写一份 compose 文件。Docker 镜像自带 yt-dlp 和依赖，不需要装源码；两个挂载目录分别是音乐存放和配置存放，建议分开：

services: xiaomusic: image: hanxi/xiaomusic ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf

第二步，启动容器。

docker compose up -d

第三步，进 Web 后台配置。浏览器打开http://NAS_IP:58090，填入小米账号密码（能登录米家的账号即可），保存后设备列表就会出现在页面上。接着选中要使用的音箱，服务地址填与音箱同一局域网的 IP——不带端口号，也别填 localhost。

后台布局大致是：左侧导航，中间歌曲列表（每首歌带播放和删除按钮），底部进度条与播放控制，右上角可切换设备。

场景化能力拆解

语音口令覆盖日常听歌

默认口令一套齐全："播放歌曲+歌名"播本地歌，"下一首/上一首"切歌，"随机播放、全部循环、单曲循环"切播放模式，"加入收藏"把当前歌收进收藏，"30 分钟后关机"到点自动停。另外"播放歌单+目录名"能直接播某个子目录，把音乐库按场景分文件夹（儿歌、助眠、轻音乐）会非常好用。

一句话下载新歌

库里没有的歌，它会先用 yt-dlp 下载再播放。比如对小爱说"播放歌曲小猪佩奇的故事"，会自动先下载再播，下载的文件分类存好，下次直接播本地。家里主要用音箱放儿童故事的话，省去了手动一首首下到 NAS 的麻烦。

断网时音乐不断

本地歌存在你自己的机器上，播放只依赖局域网，断网、在线服务改版、广告插播都不影响。库支持 mp3、flac、wav、ape、ogg、m4a 六种格式，下载的新歌统一存成 mp3。

一个后台管多台音箱

设备列表里出现多台音箱后，可以在后台右上角切换设备，不同音箱播各自的歌单——客厅放背景乐，卧室只放助眠歌单，互不干扰。

进阶玩法

自定义语音口令

你遇到了什么场景：想让音箱只响应家里的专属口令，或者把某个口令绑定到特定功能。怎么配：在示例配置的user_key_word_dict里加一条，左边是口令词，右边是动作：

"user_key_word_dict": { "播放我的最爱": "play_music_list#我的最爱" }

配完效果：说一句"播放我的最爱"就开始播"我的最爱"目录的歌单。动作还支持exec#调用 Python 插件函数，口令可以接任何你自己写的逻辑。

定时任务自动化

你遇到了什么场景：早上定点唤醒播报、深夜自动停止播放。怎么配：在后台"定时任务"栏填一个 JSON 数组，支持标准 crontab 表达式和工作日/节假日判断，did填音箱的设备 ID：

{"expression": "0 7 * * 1-5", "name": "play", "did": "123456789", "arg1": "晨间音乐"}

配完效果：周一到周五早上 7 点自动播放"晨间音乐"。任务类型还覆盖 TTS 播报、调音量、刷新列表等，完整格式见定时任务配置。

网络歌单与电台

你遇到了什么场景：除了本地歌，还想让音箱播电台。怎么配：在后台填入 JSON 格式歌单，每条是电台或 m3u8 地址，也支持直接粘贴别人分享的链接；项目自带 m3u 转换工具，电台的 m3u 文件可一键转成 JSON 歌单。配完效果：电台作为在线音源并入播放列表，和本地歌同样能播，具体例子见网络歌单文档。

避坑指南：你大概率会踩的坑

设备列表不显示，日志出现 Login Failed

多数是代理或登录态问题。先关代理，再到 mi.com 官网完成一次带滑块验证的登录，基本能解决；还不行就换 Cookie 登录方式，见FAQ 问题集合。

日志显示"正在播放"，音箱却没声音

先把"型号兼容模式"设为 true，能解决大部分触屏机型和部分老机型。仍没声音就检查服务地址：必须是与音箱同局域网的 IP（别填 localhost）；改过容器端口映射的，配置里的端口要和实际映射一致。

说"播放音乐"没反应

默认口令前缀是"播放歌曲"，说"播放音乐"是识别不到的——要么说对格式，要么自己改口令词。另外确认"语音口令/获取对话记录"开关已打开：它默认是关的，而长期开着有触发风控的风险，不常用语音口令时建议随手关掉。

flac 歌曲播不了

L05B、L05C、LX06、L16A 等型号不支持 flac，在设置里打开"转换为 MP3"（会消耗 CPU），或提前批量转成 mp3。

生态与入口

• 官方文档：功能说明与配置项介绍
• FAQ 问题集合：常见问题与报错日志对照解法
• 插件源码：Python 插件示例实现，自定义口令可通过exec#调用
• 示例配置：全部配置项及其含义
• 第三方主题（pure、Tailwind 等）与配套应用（微信小程序、安卓 TV 应用）清单见 README

它适合家里有小爱音箱、有自建音乐库、不想依赖在线流媒体订阅的人。另需知悉：原作者已公告停止维护并推荐迁移到社区接力版本，后续新功能以社区版为准。

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