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

你是否曾经遇到过这样的情况：想通过小爱音箱播放一首自己喜欢的歌曲，却发现受限于音乐平台的版权限制无法播放？XiaoMusic正是为解决这个问题而生。这款开源工具通过智能语音控制，让你能够自由播放任何想听的歌曲，同时自动下载并建立个人音乐库。无论你是技术爱好者还是普通用户，都能轻松配置使用，享受智能语音控制的便捷音乐体验。

🤔 为什么需要XiaoMusic？

传统小爱音箱的三大痛点：

1. 版权限制 - 很多歌曲因为版权问题无法在音乐平台上播放
2. 会员限制 - 热门歌曲需要开通会员才能收听
3. 功能单一 - 无法实现自动下载、个人歌单管理等高级功能

XiaoMusic的解决方案：

• 集成yt-dlp工具自动下载网络音乐
• 建立本地音乐库，实现离线播放
• 支持丰富的语音控制指令
• 提供多种个性化主题界面

🚀 5分钟快速部署指南

Docker一键部署（推荐）

这是最简单快捷的安装方式，只需一条命令：

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

参数说明：

• 58090:8090 - 将容器端口8090映射到主机58090端口
• /xiaomusic_music:/app/music - 音乐文件存储目录
• /xiaomusic_conf:/app/conf - 配置文件存储目录

Docker Compose部署

如果你更喜欢使用docker-compose，可以使用以下配置：

services:
  xiaomusic:
    image: 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

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

🎵 核心功能深度体验

智能语音控制

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

基础播放控制：

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

高级功能指令：

• "刷新列表" - 更新本地音乐库
• "加入收藏" - 将当前歌曲加入收藏列表
• "播放列表收藏" - 播放收藏的歌单

自动音乐下载机制

XiaoMusic集成了yt-dlp工具，能够自动下载播放的歌曲并保存到本地。工作机制如下：

1. 首次播放 - 当播放某首歌曲时，系统自动从网络搜索并下载
2. 本地缓存 - 后续播放直接使用本地文件，确保流畅播放
3. 格式转换 - 支持自动转换为兼容格式

🎨 个性化主题定制

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

主题名称	特点描述	适用场景
默认主题	功能齐全的基础界面	日常使用
Pure主题	简洁现代的UI设计	追求简洁体验
Tailwind主题	响应式设计的现代界面	多设备访问
XPlayer主题	专业的音乐播放器界面	音乐发烧友

⚙️ 高级配置与自定义

配置文件详解

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

cp config-example.json config.json

关键配置项说明：

{
  "account": "你的小米账号",
  "password": "你的小米密码",
  "music_path": "music",
  "convert_to_mp3": false,
  "devices": {}
}

自定义语音指令

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

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

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

🔧 常见问题与解决方案

设备兼容性排查

支持的小爱音箱型号：

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

兼容性问题解决：

• 如果无法播放，尝试启用"型号兼容模式"
• 触屏版设备设置"型号兼容模式"为true

音乐格式支持

支持的音频格式：

• MP3、FLAC、WAV
• APE、OGG、M4A

格式转换建议：

• 对于不支持FLAC格式的设备，开启"转换为MP3"选项

网络连接问题

连接故障排查步骤：

1. 确保小爱音箱和运行XiaoMusic的设备在同一局域网
2. 检查防火墙设置，确保端口58090未被阻止
3. 验证IP地址配置是否正确

💡 实用技巧与隐藏功能

批量音乐导入技巧

想要快速建立个人音乐库？试试这个方法：

1. 将已有的音乐文件直接复制到music目录
2. 对小爱音箱说"刷新列表"更新歌单
3. 立即享受你的专属音乐收藏

收藏功能深度使用

听到喜欢的歌曲时，只需说"加入收藏"，系统会自动将其添加到收藏列表。后续可以通过"播放列表收藏"快速播放所有收藏歌曲。

定时功能应用

• "分钟后关机" - 设置自动关机时间，适合睡前听歌
• 支持精确到分钟的定时设置
• 自动保存定时设置，下次可直接使用

🛡️ 安全使用指南

为了保护你的账号安全，建议遵循以下原则：

• 仅在可信的家庭网络环境中使用
• 设置复杂的登录密码
• 定期检查系统日志
• 避免使用重要的主小米账号

📊 项目技术架构

核心技术栈：

• 后端：Python语言开发
• Web框架：FastAPI（早期版本使用Flask）
• 容器化：Docker部署
• 前端：jQuery基础框架

🎯 最佳实践总结

经过大量用户实践验证，以下配置组合效果最佳：

1. 基础配置 - 小米账号+密码+设备选择
2. 高级配置 - 开启型号兼容模式+格式转换
3. 安全配置 - 设置访问密码+定期更新

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

无论你是技术新手还是资深玩家，XiaoMusic都能为你提供满意的音乐播放解决方案。现在就动手尝试，开启你的智能音乐之旅吧！