From d88b34ea97a8bb2ad1d1ca4355874a48c75b5270 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B6=B5=E6=9B=A6?= Date: Thu, 22 Jan 2026 09:47:27 +0800 Subject: [PATCH] Revise README for better clarity and structure Updated README to enhance clarity and organization, including new sections for features, installation methods, community support, and project appreciation. --- README.md | 333 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 205 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 115c040..a21c4ad 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,25 @@ [![Visitors](https://api.visitorbadge.io/api/daily?path=hanxi%2Fxiaomusic&label=daily%20visitor&countColor=%232ccce4&style=flat)](https://visitorbadge.io/status?path=hanxi%2Fxiaomusic) [![Visitors](https://api.visitorbadge.io/api/visitors?path=hanxi%2Fxiaomusic&label=total%20visitor&countColor=%232ccce4&style=flat)](https://visitorbadge.io/status?path=hanxi%2Fxiaomusic) -使用小爱音箱播放音乐，音乐使用 yt-dlp 下载。 +--- - +

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

-文档: +

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

+ +--- > [!TIP] -> 初次安装遇到问题请查阅 [💬 FAQ问题集合](https://github.com/hanxi/xiaomusic/issues/99) ，一般遇到的问题都已经有解决办法。 +> **新手指南**：初次安装遇到问题请查阅 [💬 FAQ问题集合](https://github.com/hanxi/xiaomusic/issues/99)，一般遇到的问题都已经有解决办法。 -## 👋 最简配置运行 +## 👋 快速入门指南 已经支持在 web 设置页面配置其他参数，不再需要设置环境变量， docker compose 配置如下（选一个即可）： @@ -126,145 +135,160 @@ docker run -p 58090:8090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/ > - Powered by DartNode - Free VPS for Open Source +## 🎤 功能特性 + ### 🤐 支持语音口令 -- 【播放歌曲】，播放本地的歌曲 -- 【播放歌曲+歌名】，比如：播放歌曲周杰伦晴天 -- 【上一首】 -- 【下一首】 -- 【单曲循环】 -- 【全部循环】 -- 【随机播放】 -- 【关机】，【停止播放】，两个效果是一样的。 -- 【播放歌单+目录名】，比如：播放歌单其他。 -- 【加入收藏】，把当前播放的歌曲加入收藏歌单。 -- 【取消收藏】，把当前播放的歌曲从收藏歌单里移除。 -- 【播放歌单收藏】，这个用于播放收藏歌单。 -- 【播放歌单第几个+列表名】，具体见： -- 【搜索播放+关键词】，会搜索关键词作为临时搜索列表播放，比如说【搜索播放林俊杰】，会播放所有林俊杰的歌。 +#### 基础播放控制 +- **播放歌曲** - 播放本地的歌曲 +- **播放歌曲+歌名** - 例如：播放歌曲周杰伦晴天 +- **上一首** / **下一首** - 切换歌曲 +- **关机** / **停止播放** - 停止播放 + +#### 播放模式 +- **单曲循环** - 重复播放当前歌曲 +- **全部循环** - 循环播放所有歌曲 +- **随机播放** - 随机顺序播放 + +#### 歌单管理 +- **播放歌单+目录名** - 例如：播放歌单其他 +- **播放歌单第几个+列表名** - 详见 [#158](https://github.com/hanxi/xiaomusic/issues/158) +- **播放歌单收藏** - 播放收藏歌单 + +#### 收藏功能 +- **加入收藏** - 将当前播放的歌曲加入收藏歌单 +- **取消收藏** - 将当前播放的歌曲从收藏歌单移除 + +#### 搜索播放 +- **搜索播放+关键词** - 搜索关键词作为临时搜索列表播放，例如：搜索播放林俊杰 > [!TIP] -> 隐藏玩法: 对小爱同学说播放歌曲小猪佩奇的故事，会先下载小猪佩奇的故事，然后再播放小猪佩奇的故事。 +> **隐藏玩法**：对小爱同学说"播放歌曲小猪佩奇的故事"，会先下载小猪佩奇的故事，然后再播放。 -## 🛠️ pip 方式安装运行 +## 📦 安装方式 + +### 方式一：Docker Compose（推荐） + +详见 [👋 快速入门指南](#-快速入门指南) + +### 方式二：Pip 安装 ```shell -> pip install -U xiaomusic -> xiaomusic --help - __ __ _ __ __ _ - \ \/ / (_) __ _ ___ | \/ | _ _ ___ (_) ___ - \ / | | / _` | / _ \ | |\/| | | | | | / __| | | / __| - / \ | | | (_| | | (_) | | | | | | |_| | \__ \ | | | (__ - /_/\_\ |_| \__,_| \___/ |_| |_| \__,_| |___/ |_| \___| - XiaoMusic v0.3.69 by: github.com/hanxi +# 安装 +pip install -U xiaomusic -usage: xiaomusic [-h] [--port PORT] [--hardware HARDWARE] [--account ACCOUNT] - [--password PASSWORD] [--cookie COOKIE] [--verbose] - [--config CONFIG] [--ffmpeg_location FFMPEG_LOCATION] +# 查看帮助 +xiaomusic --help -options: - -h, --help show this help message and exit - --port PORT 监听端口 - --hardware HARDWARE 小爱音箱型号 - --account ACCOUNT xiaomi account - --password PASSWORD xiaomi password - --cookie COOKIE xiaomi cookie - --verbose show info - --config CONFIG config file path - --ffmpeg_location FFMPEG_LOCATION - ffmpeg bin path -> xiaomusic --config config.json +# 启动（使用配置文件） +xiaomusic --config config.json + +# 启动（使用默认端口 8090） +xiaomusic ``` -其中 `config.json` 文件可以参考 `config-example.json` 文件配置。见 +> [!NOTE] +> `config.json` 文件可以参考 `config-example.json` 文件配置。详见 [#94](https://github.com/hanxi/xiaomusic/issues/94) -不修改默认端口 8090 的情况下，只需要执行 `xiaomusic` 即可启动。 +## 👨‍💻 开发指南 -## 🔩 开发环境运行 +### 🔩 开发环境运行 -- 使用 install_dependencies.sh 下载依赖 -- 使用 pdm 安装环境 -- 默认监听了端口 8090 , 使用其他端口自行修改。 +1. **下载依赖** + ```shell + ./install_dependencies.sh + ``` -```shell -pdm run xiaomusic.py -```` +2. **安装环境** + ```shell + pdm install + ``` -如果是开发前端界面，可以通过 -查看有什么接口。目前的 web 控制台非常简陋，欢迎有兴趣的朋友帮忙实现一个漂亮的前端，需要什么接口可以随时提需求。 +3. **启动服务** + ```shell + pdm run xiaomusic.py + ``` + 默认监听端口 8090，使用其他端口请自行修改。 + +4. **查看 API 文档** + + 访问 查看接口文档。 + +> [!NOTE] +> 目前的 web 控制台非常简陋，欢迎有兴趣的朋友帮忙实现一个漂亮的前端，需要什么接口可以随时提需求。 ### 🚦 代码提交规范 -提交前请执行 +提交前请执行以下命令检查代码和格式化代码： -``` +```shell pdm lintfmt ``` -用于检查代码和格式化代码。 - -### 本地编译 Docker Image +### 🐳 本地编译 Docker Image ```shell docker build -t xiaomusic . ``` -### 技术栈 +### 🛠️ 技术栈 -- 后端代码使用 Python 语言编写。 -- HTTP 服务使用的是 FastAPI 框架，~~早期版本使用的是 Flask~~。 -- 使用了 Docker ，在 NAS 上安装更方便。 -- 默认的前端主题使用了 jQuery 。 +- **后端**：Python + FastAPI 框架 +- **容器化**：Docker +- **前端**：jQuery -## 已测试支持的设备 +## 📱 设备支持 -| 型号 | 名称 | -| ---- | ---------------------------------------------------------------------------------------------- | -| L06A | [小爱音箱](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l06a) | -| L07A | [Redmi小爱音箱 Play](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l7a) | -| S12/S12A/MDZ-25-DA | [小米AI音箱](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.s12) | -| LX5A | [小爱音箱 万能遥控版](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx5a) | -| LX05 | [小爱音箱Play（2019款）](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx05) | -| L15A | [小米AI音箱（第二代）](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l15a#/) | -| L16A | [Xiaomi Sound](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l16a) | -| L17A | [Xiaomi Sound Pro](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l17a) | -| LX06 | [小爱音箱Pro](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx06) | -| LX01 | [小爱音箱mini](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx01) | -| L05B | [小爱音箱Play](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l05b) | -| L05C | [小米小爱音箱Play 增强版](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l05c) | -| L09A | [小米音箱Art](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l09a) | -| LX04 X10A X08A | 已经支持的触屏版 | -| X08C X08E X8F | 已经支持 | -| M01/XMYX01JY | 小米小爱音箱HD | -| OH2P | XIAOMI 智能音箱 Pro | -| OH2 | XIAOMI 智能音箱 | +### 已测试支持的设备 -型号与产品名称对照可以在这里查询 +| 型号 | 设备名称 | +|------|---------| +| **L06A** | [小爱音箱](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l06a) | +| **L07A** | [Redmi小爱音箱 Play](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l7a) | +| **S12/S12A/MDZ-25-DA** | [小米AI音箱](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.s12) | +| **LX5A** | [小爱音箱 万能遥控版](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx5a) | +| **LX05** | [小爱音箱Play（2019款）](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx05) | +| **L15A** | [小米AI音箱（第二代）](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l15a#/) | +| **L16A** | [Xiaomi Sound](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l16a) | +| **L17A** | [Xiaomi Sound Pro](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l17a) | +| **LX06** | [小爱音箱Pro](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx06) | +| **LX01** | [小爱音箱mini](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.lx01) | +| **L05B** | [小爱音箱Play](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l05b) | +| **L05C** | [小米小爱音箱Play 增强版](https://home.mi.com/baike/index.html#/detail?model=xiaomi.wifispeaker.l05c) | +| **L09A** | [小米音箱Art](https://home.mi.com/webapp/content/baike/product/index.html?model=xiaomi.wifispeaker.l09a) | +| **LX04/X10A/X08A** | 触屏版音箱 | +| **X08C/X08E/X8F** | 触屏版音箱 | +| **M01/XMYX01JY** | 小米小爱音箱HD | +| **OH2P** | XIAOMI 智能音箱 Pro | +| **OH2** | XIAOMI 智能音箱 | > [!NOTE] -> 如果你的设备支持播放，请反馈给我添加到支持列表里，谢谢。 -> 目前应该所有设备类型都已经支持播放，有问题可随时反馈。 +> - 型号与产品名称对照可在 [小米IoT平台](https://home.miot-spec.com/s/xiaomi.wifispeaker) 查询 +> - 如果你的设备支持播放，请反馈给我添加到支持列表里，谢谢 +> - 目前应该所有设备类型都已经支持播放，有问题可随时反馈 -## 🎵 支持音乐格式 +### 🎵 支持音乐格式 -- mp3 -- flac -- wav -- ape -- ogg -- m4a +- **mp3** - 标准音频格式 +- **flac** - 无损音频格式 +- **wav** - 无损音频格式 +- **ape** - 无损音频格式 +- **ogg** - 开源音频格式 +- **m4a** - AAC 音频格式 > [!NOTE] -> 本地音乐会搜索目录下上面格式的文件，下载的歌曲是 mp3 格式的。 -> 已知 L05B L05C LX06 L16A 不支持 flac 格式。 -> 如果格式不能播放可以打开【转换为MP3】和【型号兼容模式】选项。具体见 +> - 本地音乐会搜索目录下上面格式的文件，下载的歌曲是 mp3 格式 +> - 已知 L05B、L05C、LX06、L16A 不支持 flac 格式 +> - 如果格式不能播放可以打开【转换为MP3】和【型号兼容模式】选项，详见 [#153](https://github.com/hanxi/xiaomusic/issues/153#issuecomment-2328168689) ## 🌏 网络歌单功能 -可以配置一个 json 格式的歌单，支持电台和歌曲，也可以直接用别人分享的链接，同时配备了 m3u 文件格式转换工具，可以很方便的把 m3u 电台文件转换成网络歌单格式的 json 文件，具体用法见 +可以配置一个 json 格式的歌单，支持电台和歌曲，也可以直接用别人分享的链接。同时配备了 m3u 文件格式转换工具，可以很方便地把 m3u 电台文件转换成网络歌单格式的 json 文件。 + +详细用法见 [#78](https://github.com/hanxi/xiaomusic/issues/78) > [!NOTE] -> 欢迎有想法的朋友们制作更多的歌单转换工具。 +> 欢迎有想法的朋友们制作更多的歌单转换工具，一起完善项目功能！ ## ⚠️ 安全提醒 @@ -273,38 +297,72 @@ docker build -t xiaomusic . > 1. 如果配置了公网访问 xiaomusic ，请一定要开启密码登陆，并设置复杂的密码。且不要在公共场所的 WiFi 环境下使用，否则可能造成小米账号密码泄露。 > 2. 强烈不建议将小爱音箱的小米账号绑定摄像头，代码难免会有 bug ，一旦小米账号密码泄露，可能监控录像也会泄露。 -## 📢 讨论区 +## 💬 社区与支持 -- -- [点击链接加入QQ频道【xiaomusic】](https://pd.qq.com/s/e2jybz0ss) -- [点击链接加入群聊【xiaomusic官方交流群3】 1072151477](https://qm.qq.com/q/lxIhquqbza) -- [微信群二维码](https://github.com/hanxi/xiaomusic/issues/86) +### 📢 讨论区 -## ❤️ 感谢 +

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

+ +### 🤝 如何贡献 + +我们欢迎所有形式的贡献，包括但不限于： + +- 🐛 **报告 Bug**：在 [Issues](https://github.com/hanxi/xiaomusic/issues) 中提交问题 +- 💡 **功能建议**：分享你的想法和建议 +- 📝 **改进文档**：帮助完善文档和教程 +- 🎨 **前端美化**：优化 Web 控制台界面 +- 🔧 **代码贡献**：提交 Pull Request + +> [!TIP] +> 提交代码前请确保运行 `pdm lintfmt` 检查代码规范 + +## 📚 相关资源 + +### 👉 更多教程 + +更多功能见 [📝 文档汇总](https://github.com/hanxi/xiaomusic/issues/211) + +### 🎨 第三方主题 -- [xiaomi](https://www.mi.com/) -- [PDM](https://pdm.fming.dev/latest/) -- [xiaogpt](https://github.com/yihong0618/xiaogpt) -- [MiService](https://github.com/yihong0618/MiService) -- [实现原理](https://github.com/yihong0618/gitblog/issues/258) -- [yt-dlp](https://github.com/yt-dlp/yt-dlp) -- [awesome-xiaoai](https://github.com/zzz6519003/awesome-xiaoai) -- [微信小程序: 卯卯音乐](https://github.com/F-loat/xiaoplayer) - [pure 主题 xiaomusicUI](https://github.com/52fisher/xiaomusicUI) - [移动端的播放器主题](https://github.com/52fisher/XMusicPlayer) - [Tailwind主题](https://github.com/clarencejh/xiaomusic) - [SoundScape主题](https://github.com/jhao0413/SoundScape) -- [一个第三方的主题](https://github.com/DarrenWen/xiaomusicui) -- [Umami 统计](https://github.com/umami-software/umami) -- [Sentry 报错监控](https://github.com/getsentry/sentry) +- [第三方主题](https://github.com/DarrenWen/xiaomusicui) + +### 📱 配套应用 + +- [微信小程序: 卯卯音乐](https://github.com/F-loat/xiaoplayer) +- [风花雪乐(风花雪月) - 支持xiaomusic的手机App](https://github.com/jokezc/mi_music) - [JS在线播放插件](https://github.com/boluofan/xiaomusic-online) -- [风花雪乐(风花雪月),支持xiaomusic的手机App](https://github.com/jokezc/mi_music) + +### ❤️ 致谢 + +**核心依赖** +- [xiaomi](https://www.mi.com/) - 小米智能设备 +- [xiaogpt](https://github.com/yihong0618/xiaogpt) - 项目灵感来源 +- [MiService](https://github.com/yihong0618/MiService) - 小米服务接口 +- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - 音乐下载工具 + +**开发工具** +- [PDM](https://pdm.fming.dev/latest/) - Python 包管理 +- [FastAPI](https://fastapi.tiangolo.com/) - Web 框架 +- [Umami](https://github.com/umami-software/umami) - 统计分析 +- [Sentry](https://github.com/getsentry/sentry) - 报错监控 + +**参考资料** +- [实现原理](https://github.com/yihong0618/gitblog/issues/258) +- [awesome-xiaoai](https://github.com/zzz6519003/awesome-xiaoai) + +**特别感谢** - 所有帮忙调试和测试的朋友 - 所有反馈问题和建议的朋友 - -### 👉 其他教程 - -更多功能见 [📝 文档汇总](https://github.com/hanxi/xiaomusic/issues/211) +- 所有贡献代码和文档的开发者 ## 🚨 免责声明 @@ -317,12 +375,31 @@ docker build -t xiaomusic . [![Star History Chart](https://api.star-history.com/svg?repos=hanxi/xiaomusic&type=Date)](https://star-history.com/#hanxi/xiaomusic&Date) -## 赞赏 +## 💖 支持项目 -- :moneybag: 爱发电 -- 点个 Star :star: -- 谢谢 :heart: -- ![喝杯奶茶](https://i.v2ex.co/7Q03axO5l.png) +如果这个项目对你有帮助，欢迎通过以下方式支持： + +### ⭐ Star 项目 +点击右上角的 ⭐ Star 按钮，让更多人发现这个项目 + +### 💰 赞赏支持 +- [💝 爱发电](https://afdian.com/a/imhanxi) - 持续支持项目发展 +- 扫码请作者喝杯奶茶 ☕ + +

+ 赞赏码 +

+ +### 🎁 其他支持方式 +- 分享给更多需要的朋友 +- 提交 Bug 报告和功能建议 +- 贡献代码和文档 + +--- + +

+ 感谢你的支持！❤️ +

## License