15 分钟让 小爱音箱 播放本地音乐：XiaoMusic 离线音乐播放与语音控制指南

15 分钟让 小爱音箱 播放本地音乐XiaoMusic 离线音乐播放与语音控制指南【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic断网的周六下午我对客厅的音箱喊了一句“放首歌”对面回的是“无法连接服务”。那一刻最想听的其实是自己存着的本地歌。后来我装上了 XiaoMusic它让小爱音箱能离线播放本地音乐相当于把音箱变成了一个语音控制音乐库——说一句话歌就放出来不依赖在线服务。项目定位MIT 协议的小爱音箱本地音乐服务XiaoMusic 是一个 MIT 协议开源的项目做的事情很直白一套小爱音箱本地音乐播放方案让小米的音箱去放存在自己机器里的歌。官方已测试支持的设备有 20 多款包括小米 AI 音箱 S12、小爱音箱 Play 增强版 L05C、小爱音箱 Pro LX06、Xiaomi Sound L16A 这些型号。核心能力是离线播放本地音乐、语音指令控制、mp3 / flac / wav / ape / ogg / m4a 多格式支持外加 JS 和 Python 插件扩展库里没有的歌还能用 yt-dlp 下载进来。整套东西跑在 NAS 或局域网里任何能开 Docker 的机器上。小爱音箱 Docker 部署从零到第一次放歌的四步第一步拉取项目代码Docker 部署时克隆下来主要是参考示例配置容器直接拉镜像git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic cd xiaomusic第二步写 docker-compose.yml只保留必要字段services: xiaomusic: image: hanxi/xiaomusic container_name: xiaomusic restart: always ports: - 58090:8090 volumes: - /xiaomusic_music:/app/music - /xiaomusic_conf:/app/conf/xiaomusic_music 是主机上放音乐库的目录/xiaomusic_conf 是放配置的目录两个路径都可以改成自己的位置。第三步启动容器docker-compose up -d第四步浏览器配置。打开 http://服务器IP:58090做四件事填小米账号和密码保存在设备列表里选中目标小爱音箱指定音乐目录就是上面挂载进容器的那个目录保存并重启服务确认音乐库扫描完成。首次配置完成后界面里能看到设备、播放列表和播放控制区之后基本以语音为主、网页为辅。日常使用语音控制音乐库指令示例跑起来之后网页几乎不用碰只需要对音箱说“播放歌曲周杰伦晴天”——播放指定歌曲“播放歌曲小猪佩奇的故事”——库里没有会先下载再播放“随机播放” / “单曲循环” / “全部循环”——切换播放模式“上一首” / “下一首”——切歌“播放歌单中文流行”——按文件夹名或自定义歌单名整目录播放“加入收藏” / “取消收藏”——管理收藏列表“30 分钟后关机”——定时自动停止。这些口令都可以改。key_word_dict 配置项里# 前面是内置命令后面跟参数{ key_word_dict: { 播放我的最爱: play_music_list#我的最爱, 晚安音乐: play_music_list#睡眠音乐, 晨间唤醒: play_music_list#晨间音乐 } }这样喊一句“晚安音乐”音箱就播“睡眠音乐”歌单。其余口令条目参考仓库里 config-example.json 的完整样例命令细节见 官方文档。把功能用透分组、定时与歌单设备分组与定时播放多台音箱的话在配置里用 group_list 项分组格式是“did1:组名1,did2:组名1”之后可以整组下发播放。常见的搭配是客厅和厨房的音箱归“家庭背景”组来客人时一次播整组工作日设一条“0 7 * * 1-5”的定时任务卧室音箱播“晨间音乐”歌单早上不用摸手机周末“0 14 * * 6,0”让客厅播轻音乐晚上 22 点播助眠歌单再配一个定时停止睡前不用起身关灯关音箱。网络歌单 JSON 导入与插件扩展插件机制一句话同时支持 JS 和 Python仓库 plugins/ 目录里有现成的 HTTP 请求、自定义口令等样例想加新功能照着样例写就行。普通用户更常用的是网络歌单三步开启准备一份 JSON 格式歌单仓库自带 m3u 转换工具电台的 m3u 文件可以直接转成歌单格式把 JSON 链接填进 music_list_url 配置项或者把内容直接贴进 music_list_json刷新列表之后语音喊“播放歌单 XX”即可直接播放。界面主题选择仓库里提供了多种界面Pure 主题是简洁的列表加设备控制面板Tailwind 主题是响应式布局适合多设备访问移动端播放器是手机端播放界面。装完用默认界面就够按喜好再换。音乐库目录结构建议本地音乐怎么整理音乐库扫描是按目录来的按“类型—歌手”两级来放歌单会更清楚/music ├── 中文流行 │ ├── 周杰伦 │ ├── 林俊杰 │ └── 陈奕迅 ├── 英文经典 │ ├── Taylor Swift │ └── Coldplay ├── 轻音乐 │ └── 钢琴曲 └── 播客节目两条命名和元数据建议一是文件名尽量用“歌手 - 歌名”格式列表好读也能避免重名二是音频文件的标签标题、歌手、专辑保持完整系统靠标签做模糊匹配标签越全语音点播命中越准文件名里少用特殊字符。网页的歌单区域会把文件夹、系统歌单、网络歌单都放在折叠面板里一眼能看到哪些歌单可以用语音唤起。遇到问题怎么办没声音、没反应、点不到歌如果你发现网页播放列表正常、音箱却没声音先检查配置里填的 IP 有没有带端口号、音箱和服务机器是否在同一局域网通常是因为地址写错比如把 58090 也填了进去改成纯 IP 重新保存就能出声。如果你发现语音被识别了但没触发播放先检查该口令在不在 active_cmd 列表里再看网页收到的指令原文通常是因为实际说的话带了前缀或后缀和口令不完全一致往 key_word_dict 里补一个变体就能覆盖。如果你发现个别歌点不到、其余都正常先检查文件格式和音箱型号通常是因为该型号不支持对应格式L05B、L05C、LX06、L16A 不支持 flac 等在设置里打开“转换为 MP3”就能解决。如果你发现网页里根本看不到设备先检查小米账号密码是否已保存通常是因为账号没填或填错重新输入保存后设备列表才会生成。安全与数据备份提醒如果开了公网访问一定开启密码登录并设置复杂密码不要在公共场所的 WiFi 环境下使用避免小米账号信息被抓包不建议用绑定了摄像头的小米账号账号一旦泄露监控录像也可能跟着泄露。数据方面音乐文件、配置目录含 key_word_dict 等自定义口令、收藏和播放历史都值得备份。做法很简单定期把 music 和 conf 两个挂载目录复制到外置存储或另一块磁盘整份配置和歌单就都保住了不需要额外工具。去哪找更多信息文档与示例配置官方文档完整配置项与命令对照config-example.json全量示例配置可直接当模板plugins/JS 与 Python 插件样例源码README.md支持设备列表、格式说明与安全提醒docs/issues/单个 issue 的排查记录常见问题大多有答案回到开头那个断网的周六下午现在网络再断客厅音箱喊一句“放首歌”照样有回应放的还是自己库里的歌。搭好之后音箱就不再只是一个需要联网才能说话的盒子了。想试的话翻到上面的部署章节十五分钟能跑起来。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考