XiaoMusic：彻底解放小爱音箱音乐播放限制的开源工具

XiaoMusic是一款专为小米小爱音箱设计的开源音乐增强工具，通过语音控制实现智能音乐播放和自动下载功能。该项目彻底解放了小爱音箱的音乐播放限制，让你能够自由播放任何想听的歌曲，打造专属的个人音乐库。

快速安装与配置

Docker一键部署

最简单的安装方式是使用Docker，只需一条命令即可完成部署：

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

部署完成后，访问 http://你的IP地址:58090 即可进入管理界面。

配置文件设置

复制配置文件示例并进行个性化设置：

cp config-example.json config.json

编辑配置文件，设置小米账号、密码以及音乐保存路径等关键参数。

核心功能使用指南

语音控制播放

配置完成后，直接对小爱音箱说出口令即可控制音乐播放：

• "播放歌曲周杰伦" - 搜索并播放周杰伦的歌曲
• "下一首" - 切换到下一首歌曲
• "单曲循环" - 设置单曲循环模式
• "关机" - 停止播放音乐

支持的口令非常丰富，完整列表可以参考项目文档中的语音指令说明。

自动音乐下载

XiaoMusic集成了yt-dlp工具，能够自动下载播放的歌曲并保存到本地。当你第一次播放某首歌曲时，系统会自动从网络获取并下载，后续播放就直接使用本地文件，确保播放流畅。

个性化主题定制

项目提供了多种Web界面主题，满足不同用户的审美需求：

• 默认主题 - 功能齐全的基础界面
• Pure主题 - 简洁现代的UI设计
• Tailwind主题 - 响应式设计的现代界面
• XPlayer主题 - 专业的音乐播放器界面

你可以在设置中随时切换主题，或者根据需要自定义界面样式。

高级功能配置

自定义语音指令

通过修改配置文件，你可以添加自定义的语音指令：

"user_key_word_dict": {
    "测试自定义口令": "exec#code1(\"hello\")",
    "测试链接": "exec#httpget(\"https://example.com\")"
}

这让你能够扩展小爱音箱的功能，实现更多个性化操作。

网络歌单支持

XiaoMusic支持配置网络歌单，可以导入别人分享的歌单链接，或者使用m3u文件转换工具创建自己的歌单。

常见问题解决

设备兼容性问题

目前支持大多数小爱音箱型号，包括：

• 小爱音箱Play系列
• 小米AI音箱
• 小爱音箱Pro
• 触屏版音箱等

如果遇到播放问题，可以尝试启用"型号兼容模式"选项。

音乐格式支持

支持MP3、FLAC、WAV、APE、OGG、M4A等多种音频格式。如果某些格式无法播放，可以开启"转换为MP3"选项，系统会自动进行格式转换。

网络连接问题

确保小爱音箱和运行XiaoMusic的设备在同一个局域网内。如果无法连接，检查防火墙设置和端口配置。

实用技巧分享

1. 批量导入音乐 - 将已有的音乐文件直接复制到music目录，然后说"刷新列表"更新歌单
2. 收藏功能 - 听到喜欢的歌曲时说"加入收藏"，后续可以通过"播放列表收藏"快速播放
3. 定时关机 - 使用"分钟后关机"指令设置自动关机时间
4. 多设备支持 - 可以同时控制多个小爱音箱设备

安全使用建议

为了保障账号安全，建议：

• 仅在可信的网络环境中使用
• 设置复杂的登录密码
• 定期检查日志文件
• 不要将重要的小米账号用于此项目

XiaoMusic为小爱音箱用户带来了前所未有的音乐播放自由，通过简单的配置就能享受智能语音控制的便捷体验。无论是想听经典老歌还是最新热门单曲，都能通过简单的语音指令实现，真正让智能音箱成为你的私人音乐管家。