XiaoMusic: Unleash Unlimited Music on Your XiaoAI Speaker

Have you ever wished your XiaoAI speaker could do more than just play the same old tracks? Imagine having the freedom to enjoy any song you want—whether it’s stored locally on your device or streamed from the vast expanse of the internet—all with a simple voice command. That’s where XiaoMusic comes in. This open-source project transforms your XiaoAI speaker into a versatile music hub, giving you unlimited playback options and seamless control. In this comprehensive guide, we’ll dive deep into XiaoMusic, exploring its features, installation methods, voice command capabilities, and more. By the end, you’ll be ready to unlock the full potential of your XiaoAI speaker and enjoy music like never before.

What is XiaoMusic?

XiaoMusic is a powerful, open-source tool designed to enhance the functionality of Xiaomi’s XiaoAI speakers. With it, you can play music using intuitive voice commands, tapping into both your local music library and online sources. Whether you’re a casual listener or a dedicated audiophile, XiaoMusic offers a range of features to elevate your listening experience. From downloading tracks with yt-dlp to managing playlists and favorites, this tool liberates your speaker from its default limitations, making it a true entertainment powerhouse.

Key Features of XiaoMusic

What makes XiaoMusic stand out? Here’s a rundown of its core capabilities:

  • Voice-Controlled Playback: Command your speaker to play, pause, skip, or shuffle music with ease.
  • Local Music Support: Play files in formats like MP3, FLAC, WAV, APE, OGG, and M4A from your device.
  • Online Music Downloads: Fetch songs from the internet effortlessly using yt-dlp integration.
  • Playlist Management: Create, edit, and play custom playlists, including a favorites list.
  • Broad Device Compatibility: Works with a wide range of XiaoAI speaker models.
  • Web-Based Configuration: Manage settings and your music library through an intuitive web interface.

Available under the MIT license, XiaoMusic is accessible via Docker Hub and PyPI, making it easy to install and customize for tech-savvy users and beginners alike.

Why Choose XiaoMusic?

If you own a XiaoAI speaker, you’ve likely noticed its music playback options are somewhat restricted out of the box. XiaoMusic breaks those barriers, offering flexibility and control that Xiaomi’s native software can’t match. Whether you’re hosting a party, relaxing at home, or entertaining kids with audio stories, XiaoMusic adapts to your needs. Plus, its open-source nature means a community of developers is constantly improving it, ensuring you get the latest features and fixes.

How to Install XiaoMusic

Getting started with XiaoMusic is straightforward, with two main installation methods: Docker and pip. Below, we’ll walk you through both options step-by-step, so you can choose the one that fits your setup—be it a NAS, server, or personal computer.

Method 1: Installing XiaoMusic with Docker

Docker is a fantastic choice for running XiaoMusic, especially if you’re using a NAS or server. It encapsulates the application in a container, ensuring consistency and ease of deployment. Here’s how to set it up:

Prerequisites

  • Docker Installed: Ensure Docker is running on your system. Most NAS devices (e.g., Synology, QNAP) support Docker via their app stores.
  • Basic Terminal Knowledge: You’ll need to run a few commands, but we’ll explain each one.

Step-by-Step Docker Installation

  1. Create Storage Directories
    First, set up two directories on your host machine—one for music files and another for configuration data. Open your terminal and run:

    mkdir -p /xiaomusic_music
mkdir -p /xiaomusic_conf
    • /xiaomusic_music: Store your music files here or let XiaoMusic download tracks to this folder.
    • /xiaomusic_conf: This holds your configuration settings, like account details and playlists.

    Pro Tip: Check that these directories have read/write permissions for the Docker container.

  2. Launch the Docker Container
    Run the following command to download and start XiaoMusic:

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

    Here’s what each part means:

    • -p 58090:8090: Maps port 58090 on your host to port 8090 in the container, allowing web interface access.
    • -e XIAOMUSIC_PUBLIC_PORT=58090: Sets the public port environment variable to 58090.
    • -v /xiaomusic_music:/app/music: Links your music directory to the container.
    • -v /xiaomusic_conf:/app/conf: Links your config directory to the container.
    • hanxi/xiaomusic: Specifies the official XiaoMusic Docker image.

    Docker will pull the image from Docker Hub and start the container.

  3. Access the Web Interface
    Open a browser and go to http://your-nas-ip:58090 (replace your-nas-ip with your device’s IP address). You’ll see the XiaoMusic web interface.

  4. Set Up Your Xiaomi Account
    In the web interface, enter your Xiaomi account username and password, then save the settings. This connects XiaoMusic to your XiaoAI speaker by fetching your device list.

Alternative: Docker Compose

For a more organized setup, use Docker Compose. Create a file named docker-compose.yml with this content:

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

Save it, then run:

docker-compose up -d

This starts XiaoMusic in the background, with automatic restarts if it crashes.

Method 2: Installing XiaoMusic with pip

Prefer running XiaoMusic directly on your machine? Use pip, Python’s package manager. Here’s how:

Prerequisites

  • Python Installed: You’ll need Python 3.x and pip on your system.

Step-by-Step pip Installation

  1. Install XiaoMusic
    Open your terminal and run:

    pip install -U xiaomusic

    This fetches the latest version from PyPI.

  2. Create a Configuration File
    XiaoMusic needs a config.json file. Check the project repository for a sample (config-example.json) and customize it as needed.

  3. Start XiaoMusic
    Run:

    xiaomusic --config config.json

    It defaults to port 8090. To change the port, add --port [number], like --port 8080.

  4. Access the Web Interface
    Go to http://localhost:8090 in your browser to configure it further.

Configuring XiaoMusic via the Web Interface

Once installed, configure XiaoMusic to link it with your XiaoAI speaker:

  1. Open the Web Interface
    Use http://your-nas-ip:58090 (Docker) or http://localhost:8090 (pip), depending on your setup.

  2. Enter Xiaomi Account Details
    Input your Xiaomi username and password. This step authenticates XiaoMusic with your account and retrieves your speaker list.

  3. Save and Apply
    Hit “Save” to store your settings. XiaoMusic will connect to your speaker, ready for voice commands.

Security Note: Keep your Xiaomi account secure. Use a strong password and avoid reusing it for sensitive devices.

Mastering Voice Commands with XiaoMusic

XiaoMusic’s voice command system is its crown jewel, letting you control playback hands-free. Here’s a detailed list of commands to get you started:

  • Play Song: “Play song” starts playback from your local library—randomly or from your last position.
  • Play Specific Song: “Play song [song name]” (e.g., “Play song Taylor Swift’s Shake It Off”) plays that track, downloading it if needed.
  • Next Song: “Next song” skips to the next track.
  • Previous Song: “Previous song” rewinds to the prior track.
  • Pause/Stop: “Stop playback” or “Turn off” halts the music.
  • Shuffle: “Shuffle” randomizes your library’s playback order.
  • Loop: “Loop” repeats the current song endlessly.
  • All Loop: “All loop” cycles through your entire library or playlist.
  • Refresh List: “Refresh list” updates your library after adding new files.
  • Play Playlist: “Play playlist [name]” (e.g., “Play playlist Workout Vibes”) starts a specific playlist.
  • Add to Favorites: “Add to favorites” saves the current song to your favorites.
  • Remove from Favorites: “Remove from favorites” deletes the current song from favorites.
  • Play Favorites: “Play favorites” launches your favorites playlist.
  • Search and Play: “Search and play [keyword]” (e.g., “Search and play jazz”) finds and plays matching songs.
  • Local Search: “Local search and play [keyword]” searches only your local files.

Bonus for Kids: Try “Play song Peppa Pig stories” to stream kid-friendly audio content.

These commands make XiaoMusic incredibly user-friendly, turning your speaker into a voice-activated jukebox.

Supported Devices and Music Formats

Compatible XiaoAI Speaker Models

XiaoMusic supports a broad array of XiaoAI speakers. Here’s a list of confirmed models:

  • L06A: XiaoAI Speaker
  • L07A: Redmi XiaoAI Speaker Play
  • S12/S12A/MDZ-25-DA: Xiaomi AI Speaker
  • LX5A: XiaoAI Speaker with Universal Remote
  • LX05: XiaoAI Speaker Play (2019)
  • L15A: Xiaomi AI Speaker (Second Gen)
  • L16A: Xiaomi Sound
  • L17A: Xiaomi Sound Pro
  • LX06: XiaoAI Speaker Pro
  • LX01: XiaoAI Speaker Mini
  • L05B: XiaoAI Speaker Play
  • L05C: Xiaomi XiaoAI Speaker Play Enhanced
  • L09A: Xiaomi Speaker Art
  • LX04, X10A, X08A: Touchscreen models
  • X08C, X08E, X8F: Additional touchscreen variants
  • M01/XMYX01JY: Xiaomi XiaoAI Speaker HD (needs special config)
  • OH2P: Xiaomi Smart Speaker Pro
  • OH2: Xiaomi Smart Speaker

Not sure about your model? Visit the GitHub page or test compatibility mode for touchscreen devices.

Supported Audio Formats

XiaoMusic handles these formats:

  • MP3: Universally supported, perfect for all devices.
  • FLAC: Lossless quality, but unsupported on L05B, L05C, LX06, L16A.
  • WAV: Uncompressed audio.
  • APE: Lossless, high-fidelity option.
  • OGG: Open-source format.
  • M4A: Common for AAC files.

Tip: If a format doesn’t work, convert to MP3 using tools like FFmpeg for guaranteed compatibility.

Exploring Network Playlists

Take your music experience further with network playlists, which let you play online radio stations or custom song lists via JSON files.

Creating a Network Playlist

  1. Build a JSON File
    Here’s a sample:

    {
  "name": "Chill Evening Mix",
  "items": [
    {
      "type": "radio",
      "name": "Jazz FM",
      "url": "http://example.com/jazzstream"
    },
    {
      "type": "song",
      "name": "Billie Eilish - Bad Guy",
      "url": "http://example.com/billie.mp3"
    }
  ]
}
    • name: Playlist title.
    • items: List of tracks or streams with type, name, and url.

  2. Store the File
    Save it in /xiaomusic_music or a path accessible to XiaoMusic.

  3. Configure It
    In the web interface, point XiaoMusic to your JSON file.

  4. Play It
    Say “Play playlist Chill Evening Mix” to enjoy your curated list.

Converting M3U Playlists

Got an M3U file? Use XiaoMusic’s conversion tool (see the docs) to turn it into JSON, streamlining the process.

This feature is ideal for managing large collections or streaming live content.

Security Best Practices

XiaoMusic is powerful, but security matters:

  • Protect the Web Interface: If exposed online, use a strong, unique password.
  • Secure Your Xiaomi Account: Don’t link it to sensitive devices (e.g., cameras) to avoid risks if compromised.
  • Stay Local: Run XiaoMusic on your home network unless remote access is essential.

The project is for learning purposes—use it responsibly and follow local laws.

Troubleshooting Tips

Running into issues? Try these:

  • Installation Fails: Check Docker/pip logs or permissions on your directories.
  • No Sound: Verify your speaker model and file format compatibility.
  • Voice Commands Not Working: Ensure your speaker is linked via the web interface.

Still stuck? Check the FAQ on GitHub.

Join the XiaoMusic Community

Need help or want to contribute? Connect with others:

  • QQ Group: Join via this link.
  • GitHub Issues: Post questions or bugs here.

The community is active and eager to assist.

Conclusion: Elevate Your XiaoAI Experience

XiaoMusic redefines what your XiaoAI speaker can do, blending local playback, online streaming, and voice control into one seamless package. Whether you’re spinning your favorite tracks, exploring new music, or setting up playlists for every mood, XiaoMusic delivers. Easy to install via Docker or pip, packed with features, and backed by a vibrant community, it’s a game-changer for XiaoAI owners.

Ready to dive in? Install XiaoMusic today and turn your speaker into the ultimate music companion. Enjoy the freedom of unlimited playback—your ears will thank you!