Xiaomusic：让小爱同学变身全能音乐管家的开源神器

Xiaomusic是一款基于Python开发的智能音乐播放系统，能让你的小爱同学轻松播放通过yt-dlp下载的多平台音乐资源，打造专属智能音箱音乐播放体验。

一、核心价值：为什么选择Xiaomusic？

1.1 打破音乐壁垒的黑科技

传统智能音箱受限于平台版权，曲库往往不尽如人意。Xiaomusic通过创新的多平台音乐下载工具，让你告别"想听的歌找不到"的尴尬。无论是热门流行曲还是冷门老歌，都能通过yt-dlp技术轻松获取，让小爱同学的曲库瞬间扩容N倍！

1.2 极简操作，小白也能秒上手

无需复杂设置，三步即可让小爱音箱焕发新生。直观的Web控制面板，让你轻松管理音乐播放、设备连接和下载任务，真正实现"装完即用"的丝滑体验。

二、场景化部署：哪种方式适合你？

2.1 部署方式选择器

部署方式	新手友好度	适用场景	操作难度
Docker镜像	🌟🌟🌟🌟🌟	快速体验、服务器部署	简单
Docker Compose	🌟🌟🌟🌟	生产环境、多服务协同	中等
Python源码安装	🌟🌟🌟	开发调试、自定义功能	较难
pip直接安装	🌟🌟🌟🌟	本地使用、快速更新	中等

2.2 3步完成Docker极速部署（新手首选）

🔥 最简单的方式，5分钟就能用！

1. 拉取官方镜像

   docker pull xiaomusic:latest
   

   ⚠️ 如果拉取缓慢，可以尝试国内镜像源

2. 启动容器

   docker run -p 5000:5000 xiaomusic
   

   📌 端口映射格式：主机端口:容器端口，如果5000端口被占用，可以修改主机端口

3. 访问Web界面 打开浏览器输入 http://localhost:5000，开始你的音乐之旅！

2.3 Docker Compose部署避坑指南

对于需要持久化配置的场景，Docker Compose是更好的选择：

1. 创建docker-compose.yml文件

   version: '3'
   services:
     xiaomusic:
       image: xiaomusic:latest
       ports:
         - "5000:5000"
       volumes:
         - ./config.json:/app/config.json
         - ./music:/app/music
   

   📌 重要：通过volumes挂载配置文件和音乐目录，避免容器重启后数据丢失

2. 启动服务

   docker-compose up -d
   

3. 查看运行状态

   docker-compose ps
   

2.4 环境检测脚本：部署前的自查清单

在开始部署前，运行以下命令检查环境是否符合要求：

# 检查Python版本（需要3.7+）
python --version

# 检查Docker是否安装
docker --version

# 检查网络连接
ping -c 3 github.com

如果发现问题，请先解决环境依赖再进行部署。

2.5 Python源码安装全攻略

对于开发者或需要自定义功能的用户：

1. 克隆仓库

   git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic
   cd xiaomusic
   

2. 创建虚拟环境

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate     # Windows
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 启动应用

   python xiaomusic.py
   

三、个性化调校中心：打造你的专属音乐系统

3.1 基础配置三步曲

1. 复制配置文件模板

   cp config-example.json config.json
   

2. 关键配置项说明 📌 device_ip: 小爱音箱的IP地址，必须在同一局域网 📌 music_path: 音乐文件存储路径，建议使用绝对路径 📌 download_quality: 下载音质选择，可选"high"、"medium"、"low"

3. 测试配置是否生效

   python check_config.py
   

3.2 插件系统：扩展你的音乐体验

Xiaomusic提供丰富的插件系统，位于plugins/目录下：

• httpget.py: HTTP请求插件，支持自定义API调用
• httppost.py: 表单提交插件，可对接外部服务
• code1.py: 示例插件，可作为开发新插件的模板

安装插件只需将插件文件放入plugins目录，然后在配置文件中启用即可。

四、高级应用：解锁更多隐藏功能

4.1 音乐库管理技巧

Xiaomusic的音乐文件列表界面让你轻松管理所有音乐：

实用技巧：

• 双击歌曲快速播放
• 右键点击可添加到收藏或播放列表
• 使用顶部搜索框快速定位歌曲

4.2 多设备协同播放

通过控制面板的设备切换功能，可以在多个小爱音箱间无缝切换播放：

设置方法：

1. 在配置文件中添加多个设备IP
2. 在Web界面右上角选择目标设备
3. 点击"同步播放"实现多设备协同

4.3 问题速查索引

错误类型	可能原因	解决方案
连接设备失败	网络不通或IP错误	检查设备是否在线，核实IP地址
下载失败	网络问题或资源受限	检查网络连接，尝试更换下载源
播放无声音	音量设置或设备问题	检查设备音量，重启小爱音箱
界面无法访问	端口冲突或服务未启动	检查端口占用情况，重启服务

结语

Xiaomusic让你的小爱同学不再受限于官方曲库，通过强大的多平台音乐下载工具和直观的Web管理界面，打造真正属于你的智能音乐中心。无论你是技术小白还是开发大神，都能找到适合自己的部署方式，开启智能音箱的全新音乐体验！

现在就选择一种部署方式，让你的小爱音箱焕发新生吧！