# wbndmqaq/astrbot_plugin_music_hub architecture

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

- Interactive diagram: https://gitdiagram.com/wbndmqaq/astrbot_plugin_music_hub
- Repository: https://github.com/wbndmqaq/astrbot_plugin_music_hub

## Overview

Music Hub is an AstrBot music-request plugin for QQ Music, KuGou, and NetEase Cloud Music. Its main workflow routes a chat request through handlers and MusicService, searches one or more source clients, presents selectable results, resolves a playable stream, and delivers audio using platform-appropriate channels. Separate branches provide discovery and account features, scheduled subscriptions, and a password-protected WebUI. The README documents the major capabilities and service boundaries; several subsystem implementations were not sampled, so their internal call links are shown only where documented.

Main entry points: [`core/service.py`](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/service.py) (MusicService), [`core/search.py`](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/search.py) (Search orchestration), [`handlers`](https://github.com/wbndmqaq/astrbot_plugin_music_hub/tree/main/handlers) (Command handlers), [`core/api/registry.py`](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/registry.py) (Client registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Chat interaction"]
  node_handlers["Command handlers"]
  node_service["MusicService<br/>[service.py]"]
end

subgraph group_music["Music services"]
  node_search["Search orchestration<br/>[search.py]"]
  node_matching["Result matching<br/>[matching.py]"]
  node_sources["Source selection<br/>[sources.py]"]
  node_api_registry["Client registry<br/>[registry.py]"]
  node_ncm["NetEase client<br/>[ncm.py]"]
  node_kg["KuGou client<br/>[kg.py]"]
  node_qq["QQ Music client<br/>[qq.py]"]
  node_catalog["Discovery catalog<br/>[catalog.py]"]
end

subgraph group_delivery["Presentation and delivery"]
  node_render["Cards and rendering<br/>[cards.py]"]
  node_delivery["Audio delivery<br/>[delivery.py]"]
  node_media["Media processing<br/>[media.py]"]
end

subgraph group_operations["Accounts and operations"]
  node_login["QR login flows<br/>[login.py]"]
  node_queue["Request queue<br/>[queue.py]"]
  node_subs["Subscriptions<br/>[subs.py]"]
  node_scheduler["Scheduled tasks<br/>[scheduler.py]"]
  node_state[("Session and history<br/>[registry.py]")]
end

subgraph group_management["Management UI"]
  node_webui["Web management<br/>[_server.py]"]
  node_web_auth["Web authentication<br/>[_auth.py]"]
end

node_user(("Chat user"))
node_external_apis{{"Music APIs"}}
node_platform{{"Chat platform"}}
node_browser(("Administrator"))

node_user -->|"issues commands"| node_handlers
node_handlers -->|"calls service"| node_service
node_service -->|"delegates search"| node_search
node_service -->|"uses clients"| node_api_registry
node_service -->|"delegates delivery"| node_delivery
node_service -->|"reads and writes"| node_state
node_search -->|"groups results"| node_matching
node_search -->|"selects sources"| node_sources
node_search -->|"searches"| node_ncm
node_search -->|"searches"| node_kg
node_search -->|"searches"| node_qq
node_api_registry -->|"creates client"| node_ncm
node_api_registry -->|"creates client"| node_kg
node_api_registry -->|"creates client"| node_qq
node_ncm -->|"requests music data"| node_external_apis
node_kg -->|"requests music data"| node_external_apis
node_qq -->|"requests music data"| node_external_apis
node_handlers -->|"requests discovery"| node_catalog
node_catalog -->|"adapts source data"| node_ncm
node_catalog -->|"adapts source data"| node_kg
node_catalog -->|"adapts source data"| node_qq
node_handlers -->|"builds displays"| node_render
node_service -->|"builds display data"| node_render
node_delivery -->|"downloads and compresses"| node_media
node_delivery -->|"sends audio"| node_platform
node_handlers -->|"starts login"| node_login
node_service -->|"manages requests"| node_queue
node_service -->|"manages subscriptions"| node_subs
node_service -->|"starts scheduled tasks"| node_scheduler
node_scheduler -->|"triggers pushes"| node_subs
node_browser -->|"manages plugin"| node_webui
node_webui -->|"authenticates sessions"| node_web_auth
node_webui -->|"uses plugin services"| node_service

click node_handlers "https://github.com/wbndmqaq/astrbot_plugin_music_hub/tree/main/handlers"
click node_service "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/service.py"
click node_search "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/search.py"
click node_matching "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/matching.py"
click node_sources "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/sources.py"
click node_api_registry "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/registry.py"
click node_ncm "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/ncm.py"
click node_kg "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/kg.py"
click node_qq "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/qq.py"
click node_catalog "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/catalog.py"
click node_render "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/cards.py"
click node_delivery "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/delivery.py"
click node_media "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/media.py"
click node_login "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/login.py"
click node_queue "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/queue.py"
click node_subs "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/subs.py"
click node_scheduler "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/scheduler.py"
click node_state "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/registry.py"
click node_webui "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/webui/_server.py"
click node_web_auth "https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/webui/_auth.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_handlers,node_service,node_user toneBlue
class node_search,node_matching,node_sources,node_api_registry,node_ncm,node_kg,node_qq,node_catalog toneAmber
class node_render,node_delivery,node_media,node_external_apis toneMint
class node_login,node_queue,node_subs,node_scheduler,node_state toneRose
class node_webui,node_web_auth,node_platform,node_browser toneIndigo
```

## Components

### Chat interaction

- [Command handlers](https://github.com/wbndmqaq/astrbot_plugin_music_hub/tree/main/handlers): `handlers`
- [MusicService](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/service.py): `core/service.py`

### Music services

- [Search orchestration](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/search.py): `core/search.py`
- [Result matching](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/matching.py): `core/matching.py`
- [Source selection](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/sources.py): `core/sources.py`
- [Client registry](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/registry.py): `core/api/registry.py`
- [NetEase client](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/ncm.py): `core/api/ncm.py`
- [KuGou client](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/kg.py): `core/api/kg.py`
- [QQ Music client](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/api/qq.py): `core/api/qq.py`
- [Discovery catalog](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/catalog.py): `core/catalog.py`

### Presentation and delivery

- [Cards and rendering](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/cards.py): `core/cards.py`
- [Audio delivery](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/delivery.py): `core/delivery.py`
- [Media processing](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/media.py): `core/media.py`

### Accounts and operations

- [QR login flows](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/login.py): `core/login.py`
- [Request queue](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/queue.py): `core/queue.py`
- [Subscriptions](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/subs.py): `core/subs.py`
- [Scheduled tasks](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/scheduler.py): `core/scheduler.py`
- [Session and history](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/registry.py): `core/registry.py`

### Management UI

- [Web management](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/webui/_server.py): `core/webui/_server.py`
- [Web authentication](https://github.com/wbndmqaq/astrbot_plugin_music_hub/blob/main/core/webui/_auth.py): `core/webui/_auth.py`

### Other components

- **Chat user**
- **Music APIs**
- **Chat platform**
- **Administrator**

## Connections

- Chat user → Command handlers: issues commands (evidence: `README.md`)
- Command handlers → MusicService: calls service (evidence: `README.md`)
- MusicService → Search orchestration: delegates search (evidence: `README.md`)
- MusicService → Client registry: uses clients (evidence: `README.md`)
- MusicService → Audio delivery: delegates delivery (evidence: `README.md`)
- MusicService → Session and history: reads and writes (evidence: `README.md`)
- Search orchestration → Result matching: groups results (evidence: `core/search.py`)
- Search orchestration → Source selection: selects sources (evidence: `core/search.py`)
- Search orchestration → NetEase client: searches (evidence: `README.md`)
- Search orchestration → KuGou client: searches (evidence: `README.md`)
- Search orchestration → QQ Music client: searches (evidence: `README.md`)
- Client registry → NetEase client: creates client (evidence: `core/api/registry.py`)
- Client registry → KuGou client: creates client (evidence: `core/api/registry.py`)
- Client registry → QQ Music client: creates client (evidence: `core/api/registry.py`)
- NetEase client → Music APIs: requests music data (evidence: `README.md`)
- KuGou client → Music APIs: requests music data (evidence: `README.md`)
- QQ Music client → Music APIs: requests music data (evidence: `README.md`)
- Command handlers → Discovery catalog: requests discovery (evidence: `README.md`)
- Discovery catalog → NetEase client: adapts source data (evidence: `README.md`)
- Discovery catalog → KuGou client: adapts source data (evidence: `README.md`)
- Discovery catalog → QQ Music client: adapts source data (evidence: `README.md`)
- Command handlers → Cards and rendering: builds displays (evidence: `README.md`)
- MusicService → Cards and rendering: builds display data (evidence: `README.md`)
- Audio delivery → Media processing: downloads and compresses (evidence: `core/delivery.py`)
- Audio delivery → Chat platform: sends audio (evidence: `README.md`)
- Command handlers → QR login flows: starts login (evidence: `README.md`)
- MusicService → Request queue: manages requests (evidence: `README.md`)
- MusicService → Subscriptions: manages subscriptions (evidence: `README.md`)
- MusicService → Scheduled tasks: starts scheduled tasks (evidence: `README.md`)
- Scheduled tasks → Subscriptions: triggers pushes (evidence: `README.md`)
- Administrator → Web management: manages plugin (evidence: `README.md`)
- Web management → Web authentication: authenticates sessions (evidence: `core/webui/_server.py`)
- Web management → MusicService: uses plugin services (evidence: `README.md`)
