项目简介

XiaoMusic 是一个开源项目，通过 yt-dlp 下载音乐并让小爱音箱实现无限本地播放，支持自定义歌单、语音控制、网络歌单等功能，适用于多种型号的小爱音箱。

GitHub 仓库: https://github.com/hanxi/xiaomusic
文档地址: https://xdocs.hanxi.cc/

核心功能

支持多种音乐格式：mp3、flac、wav、ape、ogg、m4a
语音控制播放（支持中文指令）
网络歌单功能（支持 json 和 m3u 格式）
多设备支持（已测试 20+ 小爱音箱型号）
Docker 容器化部署

工作原理

XiaoMusic 通过小米云服务协议（MiNA/MiIO）建立与音箱的通信桥梁，当用户给出语音指令时，系统会先在本机音乐库（music_path）中检索匹配，若未找到则通过 yt-dlp 自动下载，最终将音频流地址通过小米协议推送给指定音箱设备播放。

安装

Docker 部署

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

国内用户可使用镜像：

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

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

国内镜像版本：

services:
  xiaomusic:
    image: docker.hanxi.cc/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 的 Web 界面。

目录说明

/xiaomusic_music: 主机音乐存储目录
/xiaomusic_conf: 主机配置文件目录
/app/music: 容器内音乐目录（不要修改）
/app/conf: 容器内配置目录（不要修改）

语音控制命令

支持的语音命令有：

播放歌曲
播放歌曲+歌名
上一首/下一首
单曲循环/全部循环/随机播放
关机/停止播放
刷新列表
播放列表+列表名
加入收藏/取消收藏
播放列表收藏
播放本地歌曲+歌名
播放列表第几个+列表名
搜索播放+关键词
本地搜索播放+关键词

技术细节

支持音乐格式: mp3, flac, wav, ape, ogg, m4a
后端技术: Python + FastAPI
前端: jQuery
支持设备: 多种小爱音箱型号（详见文档）

支持设备

型号	名称
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	X08A
X08C	X08C
X08E	X08E
X8F	X8F
M01/XMYX01JY	小米小爱音箱 HD
OH2P	XIAOMI 智能音箱 Pro
OH2	XIAOMI 智能音箱