# hanxi/xiaomusic architecture

> Architecture diagram of the GitHub repository hanxi/xiaomusic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanxi/xiaomusic
- Repository: https://github.com/hanxi/xiaomusic

## Overview

XiaoMusic is a self-hosted music server for controlling Xiaomi smart speakers. The main path is a spoken or web-panel command, matched by the command handler, executed by the application and device player, and fulfilled from local music or online music sources. The product also exposes web/API controls for music, files, devices, playlists, and plugins, plus authentication and configuration. The graph uses README claims and indexed imports as evidence; several unsampled subsystems are included, but their internal connections are omitted where wiring was not shown.

Main entry points: [`xiaomusic/xiaomusic.py`](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/xiaomusic.py) (Music Service), [`xiaomusic/music_library.py`](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/music_library.py) (Music Library), [`xiaomusic/api/dependencies.py`](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/dependencies.py) (API State and Auth), [`xiaomusic/api/routers/file.py`](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/routers/file.py) (File Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User and API"]
  node_api["FastAPI App<br/>[app.py]"]
  node_api_routes["API Routers"]
  node_file_api["File Controls<br/>[file.py]"]
  node_music_api["Music Controls<br/>[music.py]"]
end

subgraph group_core["Playback Core"]
  node_command["Command Handler<br/>[command_handler.py]"]
  node_appcore["Music Service<br/>[xiaomusic.py]"]
  node_devices["Device Manager<br/>[device_manager.py]"]
  node_player["Speaker Player<br/>[device_player.py]"]
  node_conversation["Voice Conversation<br/>[conversation.py]"]
end

subgraph group_media["Music Sources"]
  node_library["Music Library<br/>[music_library.py]"]
  node_online["Online Music<br/>[online_music.py]"]
  node_music_utils["Audio Processing<br/>[music_utils.py]"]
  node_file_utils["File Utilities<br/>[file_utils.py]"]
  node_network_utils["Network Utilities<br/>[network_utils.py]"]
end

subgraph group_platform["Platform Services"]
  node_config["Configuration<br/>[config.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_api_deps["API State and Auth<br/>[dependencies.py]"]
  node_plugins["JavaScript Plugins"]
  node_events["Event Bus<br/>[events.py]"]
end

node_listener(("Speaker User"))
node_webuser(("Web User"))
node_music_store[("Music Files")]
node_xiaomi["Xiaomi Services"]
node_online_services["Online Music Services"]

node_listener -->|"speaks commands"| node_command
node_command -->|"dispatches commands"| node_appcore
node_appcore -->|"uses devices"| node_devices
node_devices -->|"creates players"| node_player
node_appcore -->|"uses library"| node_library
node_appcore -->|"delegates online"| node_online
node_player -->|"processes audio"| node_music_utils
node_player -->|"uses network"| node_network_utils
node_library -->|"uses file helpers"| node_file_utils
node_library -->|"uses audio helpers"| node_music_utils
node_library -->|"uses network"| node_network_utils
node_library -.->|"indexes local music"| node_music_store
node_online -.->|"retrieves music"| node_online_services
node_webuser -->|"uses web interface"| node_api
node_api -->|"registers routes"| node_api_routes
node_api_routes -->|"routes file requests"| node_file_api
node_api_routes -->|"routes music requests"| node_music_api
node_file_api -->|"uses library"| node_library
node_file_api -->|"uses file helpers"| node_file_utils
node_file_api -->|"uses audio helpers"| node_music_utils
node_music_api -->|"uses dependencies"| node_api_deps
node_api -->|"initializes state"| node_api_deps
node_api_deps -->|"exposes service"| node_appcore
node_api_deps -->|"exposes config"| node_config
node_api_deps -.->|"checks credentials"| node_auth
node_appcore -->|"uses settings"| node_config
node_appcore -->|"initializes event bus"| node_events
node_appcore -->|"initializes plugins"| node_plugins
node_online -.->|"uses plugin manager"| node_plugins
node_devices -.->|"refreshes device info"| node_xiaomi

click node_api "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/app.py"
click node_api_routes "https://github.com/hanxi/xiaomusic/tree/main/xiaomusic/api/routers"
click node_file_api "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/routers/file.py"
click node_music_api "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/routers/music.py"
click node_command "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/command_handler.py"
click node_appcore "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/xiaomusic.py"
click node_devices "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/device_manager.py"
click node_player "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/device_player.py"
click node_conversation "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/conversation.py"
click node_library "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/music_library.py"
click node_online "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/online_music.py"
click node_music_utils "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/music_utils.py"
click node_file_utils "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/file_utils.py"
click node_network_utils "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/network_utils.py"
click node_config "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/config.py"
click node_auth "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/auth.py"
click node_api_deps "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/dependencies.py"
click node_plugins "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/js_plugin_manager.py"
click node_events "https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/events.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_api_routes,node_file_api,node_music_api,node_listener,node_webuser toneBlue
class node_command,node_appcore,node_devices,node_player,node_conversation,node_music_store toneAmber
class node_library,node_online,node_music_utils,node_file_utils,node_network_utils toneMint
class node_config,node_auth,node_api_deps,node_plugins,node_events toneRose
class node_xiaomi,node_online_services toneIndigo
```

## Components

### User and API

- [FastAPI App](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/app.py): `xiaomusic/api/app.py`
- [API Routers](https://github.com/hanxi/xiaomusic/tree/main/xiaomusic/api/routers): `xiaomusic/api/routers`
- [File Controls](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/routers/file.py): `xiaomusic/api/routers/file.py`
- [Music Controls](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/routers/music.py): `xiaomusic/api/routers/music.py`

### Playback Core

- [Command Handler](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/command_handler.py): `xiaomusic/command_handler.py`
- [Music Service](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/xiaomusic.py): `xiaomusic/xiaomusic.py`
- [Device Manager](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/device_manager.py): `xiaomusic/device_manager.py`
- [Speaker Player](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/device_player.py): `xiaomusic/device_player.py`
- [Voice Conversation](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/conversation.py): `xiaomusic/conversation.py`

### Music Sources

- [Music Library](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/music_library.py): `xiaomusic/music_library.py`
- [Online Music](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/online_music.py): `xiaomusic/online_music.py`
- [Audio Processing](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/music_utils.py): `xiaomusic/utils/music_utils.py`
- [File Utilities](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/file_utils.py): `xiaomusic/utils/file_utils.py`
- [Network Utilities](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/utils/network_utils.py): `xiaomusic/utils/network_utils.py`

### Platform Services

- [Configuration](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/config.py): `xiaomusic/config.py`
- [Authentication](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/auth.py): `xiaomusic/auth.py`
- [API State and Auth](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/api/dependencies.py): `xiaomusic/api/dependencies.py`
- [JavaScript Plugins](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/js_plugin_manager.py): `xiaomusic/js_plugin_manager.py`
- [Event Bus](https://github.com/hanxi/xiaomusic/blob/main/xiaomusic/events.py): `xiaomusic/events.py`

### Other components

- **Speaker User**
- **Web User**
- **Music Files**
- **Xiaomi Services**
- **Online Music Services**

## Connections

- Speaker User → Command Handler: speaks commands
- Command Handler → Music Service: dispatches commands (evidence: `xiaomusic/command_handler.py`)
- Music Service → Device Manager: uses devices (evidence: `xiaomusic/xiaomusic.py`)
- Device Manager → Speaker Player: creates players (evidence: `xiaomusic/device_manager.py`)
- Music Service → Music Library: uses library (evidence: `xiaomusic/xiaomusic.py`)
- Music Service → Online Music: delegates online (evidence: `xiaomusic/xiaomusic.py`)
- Speaker Player → Audio Processing: processes audio (evidence: `xiaomusic/device_player.py`)
- Speaker Player → Network Utilities: uses network (evidence: `xiaomusic/device_player.py`)
- Music Library → File Utilities: uses file helpers (evidence: `xiaomusic/music_library.py`)
- Music Library → Audio Processing: uses audio helpers (evidence: `xiaomusic/music_library.py`)
- Music Library → Network Utilities: uses network (evidence: `xiaomusic/music_library.py`)
- Music Library → Music Files: indexes local music
- Online Music → Online Music Services: retrieves music
- Web User → FastAPI App: uses web interface
- FastAPI App → API Routers: registers routes (evidence: `xiaomusic/api/routers/__init__.py`)
- API Routers → File Controls: routes file requests (evidence: `xiaomusic/api/routers/__init__.py`)
- API Routers → Music Controls: routes music requests (evidence: `xiaomusic/api/routers/__init__.py`)
- File Controls → Music Library: uses library (evidence: `xiaomusic/api/routers/file.py`)
- File Controls → File Utilities: uses file helpers (evidence: `xiaomusic/api/routers/file.py`)
- File Controls → Audio Processing: uses audio helpers (evidence: `xiaomusic/api/routers/file.py`)
- Music Controls → API State and Auth: uses dependencies (evidence: `xiaomusic/api/routers/music.py`)
- FastAPI App → API State and Auth: initializes state (evidence: `xiaomusic/api/app.py`)
- API State and Auth → Music Service: exposes service (evidence: `xiaomusic/api/dependencies.py`)
- API State and Auth → Configuration: exposes config (evidence: `xiaomusic/api/dependencies.py`)
- API State and Auth → Authentication: checks credentials
- Music Service → Configuration: uses settings (evidence: `xiaomusic/xiaomusic.py`)
- Music Service → Event Bus: initializes event bus (evidence: `xiaomusic/xiaomusic.py`)
- Music Service → JavaScript Plugins: initializes plugins (evidence: `xiaomusic/xiaomusic.py`)
- Online Music → JavaScript Plugins: uses plugin manager
- Device Manager → Xiaomi Services: refreshes device info
