hanxi/xiaomusic repository overview

⁠XiaoMusic: 无限听歌，解放小爱音箱

🎵 使用小爱音箱播放音乐，音乐使用 yt-dlp 下载

🏠 GitHub⁠ • 📖 文档⁠ • 💬 FAQ⁠ • 💭 讨论区⁠

⁠👋 快速入门指南

已经支持在 web 设置页面配置其他参数，不再需要设置环境变量， docker compose 配置如下（选一个即可）：

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

🔥 国内：

services:
  xiaomusic:
    image: docker.hanxi.cc/hanxi/xiaomusic
    container_name: xiaomusic
    restart: always
    ports:
      - 58090:8090
    volumes:
      - /xiaomusic_music:/app/music
      - /xiaomusic_conf:/app/conf

测试版：

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

对应的 docker 启动命令如下:

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

🔥 国内：

docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf docker.hanxi.cc/hanxi/xiaomusic

测试版：

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

• 其中 conf 目录为配置文件存放目录，music 目录为音乐存放目录，建议分开配置为不同的目录。
• /xiaomusic_music 和 /xiaomusic_conf 是 docker 所在的主机的目录，可以修改为其他目录。如果报错找不到 /xiaomusic_music 目录，可以先执行 mkdir -p /xiaomusic_{music,conf} 命令新建目录。
• /app/music 和 /app/conf 是 docker 容器里的目录，不要去修改。
• 58090 是 NAS 本地端口的。8090 是容器端口，不要去修改。
• 后台访问地址为： http://NAS_IP:58090

遇到问题可以去 web 设置页面底部点击【下载日志文件】按钮，然后搜索一下日志文件内容确保里面没有账号密码信息后(有就删除这些敏感信息)，然后在提 issues 反馈问题时把下载的日志文件带上。

⁠🎤 功能特性

⁠🤐 支持语音口令

⁠基础播放控制

• 播放歌曲 - 播放本地的歌曲
• 播放歌曲+歌名 - 例如：播放歌曲周杰伦晴天
• 上一首 / 下一首 - 切换歌曲
• 关机 / 停止播放 - 停止播放

⁠播放模式

• 单曲循环 - 重复播放当前歌曲
• 全部循环 - 循环播放所有歌曲
• 随机播放 - 随机顺序播放

⁠歌单管理

• 播放歌单+目录名 - 例如：播放歌单其他
• 播放歌单第几个+列表名 - 详见 #158⁠
• 播放歌单收藏 - 播放收藏歌单

⁠收藏功能

• 加入收藏 - 将当前播放的歌曲加入收藏歌单
• 取消收藏 - 将当前播放的歌曲从收藏歌单移除

⁠📦 安装方式

⁠方式一：Docker Compose（推荐）

详见 👋 快速入门指南⁠

⁠方式二：Pip 安装

# 安装
pip install -U xiaomusic

# 查看帮助
xiaomusic --help

# 启动（使用配置文件）
xiaomusic --config config.json

# 启动（使用默认端口 8090）
xiaomusic

⁠👨‍💻 开发指南

⁠🔩 开发环境运行

1. 下载依赖

   ./install_dependencies.sh
   

   Copy

2. 安装环境

   pdm install
   

   Copy

3. 启动服务

   pdm run xiaomusic.py
   

   Copy

   默认监听端口 8090，使用其他端口请自行修改。

4. 查看 API 文档

   访问 http://localhost:8090/docs⁠ 查看接口文档。

⁠🚦 代码提交规范

提交前请执行以下命令检查代码和格式化代码：

pdm lintfmt

⁠🐳 本地编译 Docker Image

docker build -t xiaomusic .

⁠🛠️ 技术栈

• 后端：Python + FastAPI 框架
• 容器化：Docker
• 前端：jQuery

⁠📱 设备支持

⁠已测试支持的设备

⁠🎵 支持音乐格式

• mp3 - 标准音频格式
• flac - 无损音频格式
• wav - 无损音频格式
• ape - 无损音频格式
• ogg - 开源音频格式
• m4a - AAC 音频格式

⁠🌏 网络歌单功能

可以配置一个 json 格式的歌单，支持电台和歌曲，也可以直接用别人分享的链接。同时配备了 m3u 文件格式转换工具，可以很方便地把 m3u 电台文件转换成网络歌单格式的 json 文件。

详细用法见 #78⁠

⁠⚠️ 安全提醒

⁠💬 社区与支持

⁠📢 讨论区

💬 GitHub Issues⁠ • 🎮 QQ频道⁠ • 👥 QQ交流群⁠ • 💬 微信群⁠

⁠🤝 如何贡献

我们欢迎所有形式的贡献，包括但不限于：

• 🐛 报告 Bug：在 Issues⁠ 中提交问题
• 💡 功能建议：分享你的想法和建议
• 📝 改进文档：帮助完善文档和教程
• 🎨 前端美化：优化 Web 控制台界面
• 🔧 代码贡献：提交 Pull Request

⁠📚 相关资源

⁠👉 更多教程

更多功能见 📝 文档汇总⁠

⁠🎨 第三方主题

• pure 主题 xiaomusicUI⁠
• 移动端的播放器主题⁠
• Tailwind主题⁠
• SoundScape主题⁠
• 第三方主题⁠

⁠📱 配套应用

• 微信小程序: 卯卯音乐⁠
• 手机APP: 风花雪乐⁠
• JS在线播放插件⁠
• 手机APP: HMusic⁠
• 安卓TV: 肉肉音乐TV⁠

⁠❤️ 致谢

核心依赖

• xiaomi⁠ - 小米智能设备
• xiaogpt⁠ - 项目灵感来源
• MiService⁠ - 小米服务接口
• yt-dlp⁠ - 音乐下载工具

开发工具

• PDM⁠ - Python 包管理
• FastAPI⁠ - Web 框架
• Umami⁠ - 统计分析
• Sentry⁠ - 报错监控

参考资料

• 实现原理⁠
• awesome-xiaoai⁠

特别感谢

• 所有帮忙调试和测试的朋友
• 所有反馈问题和建议的朋友
• 所有贡献代码和文档的开发者

⁠🚨 免责声明

本项目仅供学习和研究目的，不得用于任何商业活动。用户在使用本项目时应遵守所在地区的法律法规，对于违法使用所导致的后果，本项目及作者不承担任何责任。 本项目可能存在未知的缺陷和风险（包括但不限于设备损坏和账号封禁等），使用者应自行承担使用本项目所产生的所有风险及责任。 作者不保证本项目的准确性、完整性、及时性、可靠性，也不承担任何因使用本项目而产生的任何损失或损害责任。 使用本项目即表示您已阅读并同意本免责声明的全部内容。

⁠Star History

⁠License

MIT⁠ License © 2024 涵曦