# 0xhjk/music-dl architecture

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

- Interactive diagram: https://gitdiagram.com/0xhjk/music-dl
- Repository: https://github.com/0xhjk/music-dl

## Overview

Music-dl is a command-line music search and download aggregator. Users search across selected providers, or supply a supported song or playlist URL; results can be filtered, selected, downloaded, and optionally played. Provider add-ons retrieve provider-specific metadata and download information, while shared song handling saves audio and optional lyrics or cover art. The README also documents proxy support, sorting and deduplication, and quality preferences. Edges reflect shown calls and documented capabilities; some add-ons were not excerpted, so their internal behavior is represented conservatively.

Main entry points: [`music_dl/api.py`](https://github.com/0xhjk/music-dl/blob/master/music_dl/api.py) (HTTP API client), [`music_dl/source.py`](https://github.com/0xhjk/music-dl/blob/master/music_dl/source.py) (Source router), [`music_dl/__main__.py`](https://github.com/0xhjk/music-dl/blob/master/music_dl/__main__.py) (Command workflow), [`music_dl/song.py`](https://github.com/0xhjk/music-dl/blob/master/music_dl/song.py) (Song downloads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_command["Command workflow<br/>[__main__.py]"]
end

subgraph group_routing["Source routing"]
  node_source["Source router<br/>[source.py]"]
end

subgraph group_providers["Music providers"]
  node_baidu["Baidu add-on<br/>[baidu.py]"]
  node_kugou["Kugou add-on<br/>[kugou.py]"]
  node_netease["Netease add-on<br/>[netease.py]"]
  node_qq["QQ add-on<br/>[qq.py]"]
  node_migu["Migu add-on<br/>[migu.py]"]
  node_xiami["Xiami add-on<br/>[xiami.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_music_api["HTTP API client<br/>[api.py]"]
  node_song["Song downloads<br/>[song.py]"]
  node_config["Runtime options<br/>[config.py]"]
  node_player["Playlist player<br/>[player.py]"]
  node_exceptions["Domain errors<br/>[exceptions.py]"]
  node_version["Version metadata<br/>[__version__.py]"]
end

node_user(("CLI user"))
node_providers_service{{"Music websites"}}
node_local_files[("Local files")]

node_user -->|"invokes"| node_command
node_command -->|"sets options"| node_config
node_command -->|"searches or resolves"| node_source
node_source -->|"dispatches"| node_baidu
node_source -->|"dispatches"| node_kugou
node_source -->|"dispatches"| node_netease
node_source -->|"dispatches"| node_qq
node_source -->|"dispatches"| node_migu
node_source -->|"dispatches"| node_xiami
node_baidu -->|"requests via"| node_music_api
node_kugou -->|"requests via"| node_music_api
node_netease -->|"requests via"| node_music_api
node_qq -->|"requests via"| node_music_api
node_migu -->|"requests via"| node_music_api
node_xiami -->|"requests via"| node_music_api
node_music_api -->|"sends requests"| node_providers_service
node_command -->|"downloads selected"| node_song
node_song -->|"writes audio and extras"| node_local_files
node_command -->|"starts playback"| node_player
node_player -->|"plays or deletes"| node_local_files
node_song -->|"reads options"| node_config
node_music_api -->|"reads request settings"| node_config

click node_command "https://github.com/0xhjk/music-dl/blob/master/music_dl/__main__.py"
click node_source "https://github.com/0xhjk/music-dl/blob/master/music_dl/source.py"
click node_baidu "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/baidu.py"
click node_kugou "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/kugou.py"
click node_netease "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/netease.py"
click node_qq "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/qq.py"
click node_migu "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/migu.py"
click node_xiami "https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/xiami.py"
click node_music_api "https://github.com/0xhjk/music-dl/blob/master/music_dl/api.py"
click node_song "https://github.com/0xhjk/music-dl/blob/master/music_dl/song.py"
click node_config "https://github.com/0xhjk/music-dl/blob/master/music_dl/config.py"
click node_player "https://github.com/0xhjk/music-dl/blob/master/music_dl/player.py"
click node_exceptions "https://github.com/0xhjk/music-dl/blob/master/music_dl/exceptions.py"
click node_version "https://github.com/0xhjk/music-dl/blob/master/music_dl/__version__.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_command,node_user toneBlue
class node_source,node_local_files toneAmber
class node_baidu,node_kugou,node_netease,node_qq,node_migu,node_xiami toneMint
class node_music_api,node_song,node_config,node_player,node_exceptions,node_version toneRose
class node_providers_service toneIndigo
```

## Components

### CLI workflow

- [Command workflow](https://github.com/0xhjk/music-dl/blob/master/music_dl/__main__.py): `music_dl/__main__.py`

### Source routing

- [Source router](https://github.com/0xhjk/music-dl/blob/master/music_dl/source.py): `music_dl/source.py`

### Music providers

- [Baidu add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/baidu.py): `music_dl/addons/baidu.py`
- [Kugou add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/kugou.py): `music_dl/addons/kugou.py`
- [Netease add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/netease.py): `music_dl/addons/netease.py`
- [QQ add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/qq.py): `music_dl/addons/qq.py`
- [Migu add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/migu.py): `music_dl/addons/migu.py`
- [Xiami add-on](https://github.com/0xhjk/music-dl/blob/master/music_dl/addons/xiami.py): `music_dl/addons/xiami.py`

### Shared runtime

- [HTTP API client](https://github.com/0xhjk/music-dl/blob/master/music_dl/api.py): `music_dl/api.py`
- [Song downloads](https://github.com/0xhjk/music-dl/blob/master/music_dl/song.py): `music_dl/song.py`
- [Runtime options](https://github.com/0xhjk/music-dl/blob/master/music_dl/config.py): `music_dl/config.py`
- [Playlist player](https://github.com/0xhjk/music-dl/blob/master/music_dl/player.py): `music_dl/player.py`
- [Domain errors](https://github.com/0xhjk/music-dl/blob/master/music_dl/exceptions.py): `music_dl/exceptions.py`
- [Version metadata](https://github.com/0xhjk/music-dl/blob/master/music_dl/__version__.py): `music_dl/__version__.py`

### Other components

- **CLI user**
- **Music websites**
- **Local files**

## Connections

- CLI user → Command workflow: invokes (evidence: `README.md`)
- Command workflow → Runtime options: sets options (evidence: `music_dl/__main__.py`)
- Command workflow → Source router: searches or resolves (evidence: `music_dl/__main__.py`)
- Source router → Baidu add-on: dispatches (evidence: `music_dl/source.py`)
- Source router → Kugou add-on: dispatches (evidence: `music_dl/source.py`)
- Source router → Netease add-on: dispatches (evidence: `music_dl/source.py`)
- Source router → QQ add-on: dispatches (evidence: `music_dl/source.py`)
- Source router → Migu add-on: dispatches (evidence: `music_dl/source.py`)
- Source router → Xiami add-on: dispatches (evidence: `music_dl/source.py`)
- Baidu add-on → HTTP API client: requests via (evidence: `music_dl/addons/baidu.py`)
- Kugou add-on → HTTP API client: requests via (evidence: `music_dl/addons/kugou.py`)
- Netease add-on → HTTP API client: requests via (evidence: `music_dl/addons/netease.py`)
- QQ add-on → HTTP API client: requests via (evidence: `music_dl/addons/qq.py`)
- Migu add-on → HTTP API client: requests via (evidence: `music_dl/addons/migu.py`)
- Xiami add-on → HTTP API client: requests via (evidence: `music_dl/addons/xiami.py`)
- HTTP API client → Music websites: sends requests (evidence: `music_dl/api.py`)
- Command workflow → Song downloads: downloads selected (evidence: `music_dl/__main__.py`)
- Song downloads → Local files: writes audio and extras (evidence: `music_dl/song.py`)
- Command workflow → Playlist player: starts playback (evidence: `music_dl/__main__.py`)
- Playlist player → Local files: plays or deletes (evidence: `music_dl/player.py`)
- Song downloads → Runtime options: reads options (evidence: `music_dl/song.py`)
- HTTP API client → Runtime options: reads request settings (evidence: `music_dl/api.py`)
