# charlespikachu/musicdl architecture

> Architecture diagram of the GitHub repository charlespikachu/musicdl, 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/charlespikachu/musicdl
- Repository: https://github.com/charlespikachu/musicdl

## Overview

musicdl is a Python music and audiobook search/download client with adapters for streaming platforms, third-party music sites, and shared search services. The principal workflow is to configure selected sources, search them concurrently through MusicClient, then use a selected adapter to resolve and download audio. The graph preserves the documented adapter families and highlights the shared client and utility layers. Some adapter internals are unsampled, so their detailed calls and download flow are not expanded.

Main entry points: [`musicdl/modules/sources/__init__.py`](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/__init__.py) (Source registry), [`musicdl/modules/sources/base.py`](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/base.py) (Base client), [`musicdl/modules/sources/kugou.py`](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/kugou.py) (Kugou adapter), [`musicdl/musicdl.py`](https://github.com/charlespikachu/musicdl/blob/master/musicdl/musicdl.py) (MusicClient)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Client orchestration"]
  node_music_client["MusicClient<br/>[musicdl.py]"]
  node_source_registry["Source registry<br/>[__init__.py]"]
end

subgraph group_platforms["Music platforms"]
  node_platform_adapters["Platform adapters"]
  node_kugou["Kugou adapter<br/>[kugou.py]"]
  node_netease["NetEase adapter<br/>[netease.py]"]
  node_qq["QQ adapter<br/>[qq.py]"]
  node_youtube["YouTube adapter<br/>[youtube.py]"]
end

subgraph group_discovery["Other discovery"]
  node_audiobooks["Audiobook adapters"]
  node_common_sources["Common search sources"]
  node_thirdparty_sites["Third-party music sites"]
end

subgraph group_shared["Shared runtime"]
  node_base_client["Base client<br/>[base.py]"]
  node_utils_facade["Utility exports<br/>[__init__.py]"]
  node_audio_validation["Audio link validation<br/>[misc.py]"]
  node_host_matching["Host matching<br/>[hosts.py]"]
  node_kugou_utils["Kugou helpers<br/>[kugouutils.py]"]
  node_youtube_utils["YouTube helpers<br/>[youtubeutils.py]"]
  node_cli_commands["Command helpers<br/>[cmd.py]"]
  node_logging["Logging<br/>[logger.py]"]
end

node_listener(("Music listener"))
node_platform_services(("Music services"))

node_listener -->|"uses"| node_music_client
node_music_client -->|"initializes sources"| node_source_registry
node_source_registry -->|"registers clients"| node_platform_adapters
node_music_client -->|"searches concurrently"| node_platform_adapters
node_platform_adapters -->|"searches and downloads"| node_platform_services
node_source_registry -->|"imports clients"| node_audiobooks
node_source_registry -->|"imports clients"| node_common_sources
node_source_registry -->|"imports clients"| node_thirdparty_sites
node_kugou -->|"inherits from"| node_base_client
node_netease -->|"inherits from"| node_base_client
node_qq -->|"inherits from"| node_base_client
node_youtube -->|"inherits from"| node_base_client
node_base_client -->|"imports utilities"| node_utils_facade
node_kugou -->|"uses helpers"| node_kugou_utils
node_kugou -->|"uses host utilities"| node_host_matching
node_netease -->|"tests audio links"| node_audio_validation
node_qq -->|"tests audio links"| node_audio_validation
node_youtube -->|"imports helpers"| node_youtube_utils
node_utils_facade -->|"exports commands"| node_cli_commands
node_utils_facade -->|"exports logging"| node_logging

click node_music_client "https://github.com/charlespikachu/musicdl/blob/master/musicdl/musicdl.py"
click node_source_registry "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/__init__.py"
click node_base_client "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/base.py"
click node_platform_adapters "https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/sources"
click node_kugou "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/kugou.py"
click node_netease "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/netease.py"
click node_qq "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/qq.py"
click node_youtube "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/youtube.py"
click node_audiobooks "https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/audiobooks"
click node_common_sources "https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/common"
click node_thirdparty_sites "https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/thirdpartysites"
click node_utils_facade "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/__init__.py"
click node_audio_validation "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/misc.py"
click node_host_matching "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/hosts.py"
click node_kugou_utils "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/kugouutils.py"
click node_youtube_utils "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/youtubeutils.py"
click node_cli_commands "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/cmd.py"
click node_logging "https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/logger.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_music_client,node_source_registry toneBlue
class node_platform_adapters,node_kugou,node_netease,node_qq,node_youtube toneAmber
class node_audiobooks,node_common_sources,node_thirdparty_sites toneMint
class node_base_client,node_utils_facade,node_audio_validation,node_host_matching,node_kugou_utils,node_youtube_utils,node_cli_commands,node_logging toneRose
class node_listener,node_platform_services toneIndigo
```

## Components

### Client orchestration

- [MusicClient](https://github.com/charlespikachu/musicdl/blob/master/musicdl/musicdl.py): `musicdl/musicdl.py`
- [Source registry](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/__init__.py): `musicdl/modules/sources/__init__.py`

### Music platforms

- [Platform adapters](https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/sources): `musicdl/modules/sources`
- [Kugou adapter](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/kugou.py): `musicdl/modules/sources/kugou.py`
- [NetEase adapter](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/netease.py): `musicdl/modules/sources/netease.py`
- [QQ adapter](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/qq.py): `musicdl/modules/sources/qq.py`
- [YouTube adapter](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/youtube.py): `musicdl/modules/sources/youtube.py`

### Other discovery

- [Audiobook adapters](https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/audiobooks): `musicdl/modules/audiobooks`
- [Common search sources](https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/common): `musicdl/modules/common`
- [Third-party music sites](https://github.com/charlespikachu/musicdl/tree/master/musicdl/modules/thirdpartysites): `musicdl/modules/thirdpartysites`

### Shared runtime

- [Base client](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/sources/base.py): `musicdl/modules/sources/base.py`
- [Utility exports](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/__init__.py): `musicdl/modules/utils/__init__.py`
- [Audio link validation](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/misc.py): `musicdl/modules/utils/misc.py`
- [Host matching](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/hosts.py): `musicdl/modules/utils/hosts.py`
- [Kugou helpers](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/kugouutils.py): `musicdl/modules/utils/kugouutils.py`
- [YouTube helpers](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/youtubeutils.py): `musicdl/modules/utils/youtubeutils.py`
- [Command helpers](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/cmd.py): `musicdl/modules/utils/cmd.py`
- [Logging](https://github.com/charlespikachu/musicdl/blob/master/musicdl/modules/utils/logger.py): `musicdl/modules/utils/logger.py`

### Other components

- **Music listener**
- **Music services**

## Connections

- Music listener → MusicClient: uses
- MusicClient → Source registry: initializes sources (evidence: `musicdl/musicdl.py`)
- Source registry → Platform adapters: registers clients (evidence: `musicdl/modules/sources/__init__.py`)
- MusicClient → Platform adapters: searches concurrently (evidence: `musicdl/musicdl.py`)
- Platform adapters → Music services: searches and downloads
- Source registry → Audiobook adapters: imports clients (evidence: `musicdl/modules/sources/__init__.py`)
- Source registry → Common search sources: imports clients (evidence: `musicdl/modules/sources/__init__.py`)
- Source registry → Third-party music sites: imports clients (evidence: `musicdl/modules/sources/__init__.py`)
- Kugou adapter → Base client: inherits from (evidence: `musicdl/modules/sources/kugou.py`)
- NetEase adapter → Base client: inherits from (evidence: `musicdl/modules/sources/netease.py`)
- QQ adapter → Base client: inherits from (evidence: `musicdl/modules/sources/qq.py`)
- YouTube adapter → Base client: inherits from (evidence: `musicdl/modules/sources/youtube.py`)
- Base client → Utility exports: imports utilities (evidence: `musicdl/modules/sources/base.py`)
- Kugou adapter → Kugou helpers: uses helpers (evidence: `musicdl/modules/sources/kugou.py`)
- Kugou adapter → Host matching: uses host utilities (evidence: `musicdl/modules/sources/kugou.py`)
- NetEase adapter → Audio link validation: tests audio links (evidence: `musicdl/modules/sources/netease.py`)
- QQ adapter → Audio link validation: tests audio links (evidence: `musicdl/modules/sources/qq.py`)
- YouTube adapter → YouTube helpers: imports helpers (evidence: `musicdl/modules/sources/youtube.py`)
- Utility exports → Command helpers: exports commands (evidence: `musicdl/modules/utils/__init__.py`)
- Utility exports → Logging: exports logging (evidence: `musicdl/modules/utils/__init__.py`)
