xiaomusic README

The project's README from github.com/hanxi/xiaomusic. As one markdown file: README.md.

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

[!IMPORTANT] 📢 项目停止维护通知

因个人精力有限，需将重心转移到其他项目，本项目将停止维护，不再接受新功能开发与 bug 修复，已有 issue 与 PR 也不再处理。

后续推荐使用社区接力项目：songloft-org/songloft，欢迎大家迁移、参与共建。

衷心感谢一路以来所有用户的支持与陪伴 ❤️

GitHub License Docker Image Version Docker Pulls PyPI - Version PyPI - Downloads Python Version from PEP 621 TOML GitHub Release Visitors Visitors

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

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

[!TIP] 新手指南：初次安装遇到问题请查阅 💬 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

[!NOTE] docker 和 docker compose 二选一即可，启动成功后，在 web 页面可以配置其他参数，带有 * 号的配置是必须要配置的，其他的用不上时不用修改。初次配置时需要在页面上输入小米账号和密码保存后才能获取到设备列表。

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

[!TIP] 作者新写了一个更简洁的个人音乐服务器，支持更强的插件扩展 https://github.com/mimusic-org/mimusic

[!TIP]

[!TIP]

[!TIP]

[!TIP]

  • 免费主机
  • Powered by DartNode - Free VPS for Open Source

🎤 功能特性

🤐 支持语音口令

基础播放控制

播放模式

歌单管理

收藏功能

[!TIP] 隐藏玩法：对小爱同学说"播放歌曲小猪佩奇的故事"，会先下载小猪佩奇的故事，然后再播放。

📦 安装方式

方式一：Docker Compose（推荐）

详见 👋 快速入门指南

方式二：Pip 安装

# 安装
pip install -U xiaomusic

# 查看帮助
xiaomusic --help

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

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

[!NOTE] config.json 文件可以参考 config-example.json 文件配置。详见 #94

👨‍💻 开发指南

🔩 开发环境运行

  1. 下载依赖

    ./install_dependencies.sh

  2. 安装环境

    pdm install

  3. 启动服务

    pdm run xiaomusic.py

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

  4. 查看 API 文档

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

[!NOTE] 目前的 web 控制台非常简陋，欢迎有兴趣的朋友帮忙实现一个漂亮的前端，需要什么接口可以随时提需求。

🚦 代码提交规范

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

pdm lintfmt

🐳 本地编译 Docker Image

docker build -t xiaomusic .

🛠️ 技术栈

📱 设备支持

已测试支持的设备

型号 设备名称
L06A 小爱音箱
L07A Redmi小爱音箱 Play
S12/S12A/MDZ-25-DA 小米AI音箱
LX5A 小爱音箱 万能遥控版
LX05 小爱音箱Play（2019款）
L15A 小米AI音箱（第二代）
L16A Xiaomi Sound
L17A Xiaomi Sound Pro
LX06 小爱音箱Pro
LX01 小爱音箱mini
L05B 小爱音箱Play
L05C 小米小爱音箱Play 增强版
L09A 小米音箱Art
LX04/X10A/X08A 触屏版音箱
X08C/X08E/X8F 触屏版音箱
M01/XMYX01JY 小米小爱音箱HD
OH2P XIAOMI 智能音箱 Pro
OH2 XIAOMI 智能音箱

[!NOTE]

  • 型号与产品名称对照可在 小米IoT平台 查询
  • 如果你的设备支持播放，请反馈给我添加到支持列表里，谢谢
  • 目前应该所有设备类型都已经支持播放，有问题可随时反馈

🎵 支持音乐格式

[!NOTE]

  • 本地音乐会搜索目录下上面格式的文件，下载的歌曲是 mp3 格式
  • 已知 L05B、L05C、LX06、L16A 不支持 flac 格式
  • 如果格式不能播放可以打开【转换为MP3】和【型号兼容模式】选项，详见 #153

🌏 网络歌单功能

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

详细用法见 #78

[!NOTE] 欢迎有想法的朋友们制作更多的歌单转换工具，一起完善项目功能！

⚠️ 安全提醒

[!IMPORTANT]

  1. 如果配置了公网访问 xiaomusic ，请一定要开启密码登陆，并设置复杂的密码。且不要在公共场所的 WiFi 环境下使用，否则可能造成小米账号密码泄露。
  2. 强烈不建议将小爱音箱的小米账号绑定摄像头，代码难免会有 bug ，一旦小米账号密码泄露，可能监控录像也会泄露。

💬 社区与支持

📢 讨论区

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

🤝 如何贡献

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

[!TIP] 提交代码前请确保运行 pdm lintfmt 检查代码规范

📚 相关资源

👉 更多教程

更多功能见 📝 文档汇总

🎨 第三方主题

📱 配套应用

❤️ 致谢

核心依赖

开发工具

参考资料

特别感谢

🚨 免责声明

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

Star History

Star History Chart

License

MIT License © 2024 涵曦

xiaomusic (hanxi/xiaomusic)

Searching Database…

10K ·GitHub
Xiaomusic
archived
这是什么？一个自托管的服务，用来在小米小爱智能音箱上播放音乐：它把你的音乐库提供给音箱，还能按需用 yt-dlp 下载新歌。你可以通过语音和网页控制台来操作它。
这是装在音箱上的应用吗？它到底运行在哪里？都不是——这是你自己搭建的服务端，通常以 Docker 方式跑在 NAS 或家庭服务器上。音箱只是照指令播放；所有设置都在网页管理页面完成（后端是 Python/FastAPI，前端是 jQuery）。
安装麻烦吗？是不是只能用 Docker？推荐用 Docker Compose（用 pip 安装也可以）。启动后打开网页——示例配置把主机的 58090 端口映射到容器的 8090 端口——首次运行时在页面上输入你的小米账号和密码，就能获取你的设备列表。
必须要有小米账号才能用吗？是的，绑定音箱需要小米账号，此外还需要音箱本身，以及一台长期开机的机器来跑 Docker（走 pip 方式则是 Python）。音乐和配置存放在两个独立的主机目录中，挂载进容器即可。
这个项目还在维护吗？不维护了——项目已归档：作者停止了维护，不再有新功能或漏洞修复，开放的 issue 和 PR 也不再处理。README 指向社区接替项目 songloft-org/songloft，供用户迁移。
我的音箱能用吗？目标用户是小米小爱音箱的拥有者：经过测试的机型约有 20 款，从小爱音箱、mini 音箱、Redmi 小爱音箱 Play，到小米 AI 音箱（第二代）、Xiaomi Sound / Sound Pro、带屏型号以及 Xiaomi 智能音箱 Pro 都在列。
对音箱我具体能说些什么？基础指令有：按歌名点歌（比如“播放歌曲周杰伦晴天”）、播放本地歌曲、切上一首/下一首、停止播放。还支持循环和随机播放模式、按文件夹名的歌单指令，以及一个可以添加和删除歌曲的收藏列表。
音乐从哪来？我需要自己准备文件吗？既可以把自己的 mp3、flac、wav、ape、ogg 或 m4a 文件放进音乐文件夹，也可以直接点歌：系统会用 yt-dlp 下载（保存为 mp3）到该文件夹，然后播放。还可以通过 JSON 网络歌单在线收听电台。
无损 FLAC 在所有音箱上都能播吗？不一定——已知 L05B、L05C、LX06 和 L16A 这几款机型无法播放 flac。如果某种格式播不了，可以在设置页面开启“转换为 MP3”和机型兼容模式选项。
除了普通歌曲，还有什么好玩的功能？有：说“播放歌曲小猪佩奇的故事”，它就会下载并播放小猪佩奇的故事。你还可以加载带电台的 JSON 网络歌单（需配合一个 m3u 转换工具），以及安装 pure、Tailwind、SoundScape 等第三方网页主题。
What are similar projects?linksift, ISpotify, stemdeck, EchoMuse, reclip, AlgerMusicPlayer, ha_xiaomi_home, spotify-downloader
Which topics is it in?xiaomi, nas, smart-home, yt-dlp, music-player, downloader, iot, music, fastapi, audio, vue, deprecated
Creator
hanxi
Size
23.4 MB
Stars
10K
Updated
CommitJun 09Releasev0.6.1Jun 09
Age
3y
Commits · 90 Days