Skip to content
Get packs

XiaoMusic

Plays music through Xiaomi Xiaoai speakers, with songs downloaded via yt-dlp.

GitHub Download v0.6.1
Stars
10k
Forks
1.2k
Licence
MIT
Language
Python
Last update
5 months ago
Type
App

This repository is archived and no longer maintained.

What it is

XiaoMusic lets you play music on a Xiaomi Xiaoai smart speaker, including songs you download with yt-dlp. It runs as a small web service on your own machine or NAS, and you control playback with voice commands to the speaker. The project's README says it is no longer maintained and points users to a successor project, songloft.

  • Play local mp3, flac, wav, ape, ogg or m4a files on a supported Xiaomi speaker by voice
  • Organize songs into playlists and play them by voice command
  • Use a web settings page to configure the service instead of environment variables
  • Play online playlists or radio stations defined in a JSON file

Great for

  • Owners of supported Xiaomi Xiaoai speakers who want their own music library on the speaker
  • People with a NAS or home server who can run Docker
  • Users comfortable with voice commands and a basic web settings page

Not ideal for

  • Anyone wanting an actively maintained project, since the README says maintenance has stopped and no new bug fixes will be made
  • People who do not own a supported Xiaomi speaker, since the feature depends on the device
  • Users who are uncomfortable entering a Xiaomi account password into a self-hosted service, given the README's security warnings

How to get it

  1. 1

    Install with a package manager

    You'll need: Docker or Python with pip · A supported Xiaomi Xiaoai speaker and a Xiaomi account

    Install with pip

    pip install -U xiaomusic

    Run with default port 8090

    xiaomusic
  2. 2

    Run it

    • Install with pip or start the Docker container using the README command
    • Open the web page at the address shown in the README (for Docker, http://NAS_IP:58090)
    • Enter your Xiaomi account and password in the web settings and save to load your device list
    • Add music to the music directory and try a voice command such as playing a song
  3. 3

    Get the most out of it

    • Use the web settings page for configuration, as the README says environment variables are no longer needed
    • Set a strong password if you expose the service to the internet, per the README's security notice
    • Use the JSON online playlist format to add internet radio or shared song links
    • Try the README's note that the 'convert to MP3' and 'model compatibility mode' options help with unsupported formats

Downloads

Source code (.zip)main branch · straight from GitHubRelease v0.6.13 files incl. xiaomusic-v0.6.1-armv7.tarOfficial website & docsxdocs.hanxi.cc/

Strengths

  • Brings a home music library to a supported Xiaomi speaker through voice control
  • Runs via Docker Compose or pip, with a web settings page for configuration
  • Released under the MIT license

Trade-offs

  • The README says the project is no longer maintained and will not receive new features or bug fixes
  • Requires a Xiaomi account login, and the README warns about account exposure risk on public Wi-Fi or public internet access

How it compares

ProjectStarsTypeLevelUpdatedBest for
xiaomusic (this)10kAppintermediate5 months agoOwners of supported Xiaomi Xiaoai speakers who want their own music library on the speaker
YesPlayMusic33.5kAppbeginner27 days agoExisting NetEase Cloud Music users who want a different player interface
koel17.3kAppintermediate4 days agoPeople who want to listen to their own music library from a browser
dashy26.9kAppbeginner6 days agoPeople running a homelab or home server who want one page for all their services
dockge24.7kAppbeginner14 days agoPeople who run Docker Compose stacks on a home server or small Linux machine
winboat23.3kAppintermediate1 months agoLinux users who need a specific Windows-only application for occasional use

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.