# glomatico/gytmdl architecture

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

- Interactive diagram: https://gitdiagram.com/glomatico/gytmdl
- Repository: https://github.com/glomatico/gytmdl

## Overview

Gytmdl is a command-line YouTube Music downloader. Its main flow accepts song, album, playlist, or artist URLs, resolves tracks, retrieves metadata and audio, then writes tagged files and optional synced lyrics or cover images. The sampled CLI and downloader support these calls; artist selection, configuration, and advertised features are represented where documented, but unsampled implementation details and wiring are kept conservative.

Main entry points: [`gytmdl/cli.py`](https://github.com/glomatico/gytmdl/blob/master/gytmdl/cli.py) (Command workflow), [`gytmdl/downloader.py`](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py) (Downloader), [`gytmdl/utils.py`](https://github.com/glomatico/gytmdl/blob/master/gytmdl/utils.py) (Path validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["Command workflow<br/>[cli.py]"]
  node_config["Config loading<br/>[cli.py]"]
  node_pathcheck["Path validation<br/>[utils.py]"]
end

subgraph group_resolve["Music resolution"]
  node_downloader["Downloader<br/>[downloader.py]"]
  node_artistselect["Artist selection<br/>[downloader.py]"]
end

subgraph group_media["Track processing"]
  node_metadata["Track metadata<br/>[downloader.py]"]
  node_audio["Audio download<br/>[downloader.py]"]
  node_tagging["Tag and cover embedding<br/>[downloader.py]"]
  node_cover["Cover retrieval<br/>[downloader.py]"]
  node_lyrics["Synced lyrics<br/>[downloader.py]"]
end

subgraph group_output["Output artifacts"]
  node_outputfiles["Audio files"]
  node_lyricfiles["LRC files"]
  node_coverfiles["Cover files"]
end

node_user(("CLI user"))
node_ytmusic["YouTube Music API"]
node_ytdlp["yt-dlp"]
node_selection["Interactive selection"]
node_ffmpeg["FFmpeg remux"]
node_musicservice["YouTube Music"]
node_imageservice["Cover image server"]

node_user -->|"provides URLs/options"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"validates cookies"| node_pathcheck
node_cli -->|"creates and calls"| node_downloader
node_downloader -->|"queries metadata"| node_ytmusic
node_downloader -->|"resolves and downloads"| node_ytdlp
node_downloader -->|"resolves artist URLs"| node_artistselect
node_artistselect -->|"prompts selection"| node_selection
node_artistselect -->|"lists albums"| node_ytmusic
node_cli -->|"gets track tags"| node_metadata
node_metadata -->|"fetches lyrics and album data"| node_ytmusic
node_cli -->|"downloads track"| node_audio
node_cli -->|"applies tags"| node_tagging
node_cli -->|"gets cover details"| node_cover
node_cli -->|"gets synced lyrics"| node_lyrics
node_audio -->|"fetches audio"| node_ytdlp
node_cli -->|"requests remux"| node_ffmpeg
node_tagging -->|"fetches cover bytes"| node_imageservice
node_cover -->|"downloads image"| node_imageservice
node_lyrics -->|"requests synced lyrics"| node_ytmusic
node_cli -->|"writes track"| node_outputfiles
node_cli -->|"writes LRC"| node_lyricfiles
node_cli -->|"optionally saves cover"| node_coverfiles
node_cli -.->|"optionally selects aria2c mode"| node_audio

click node_cli "https://github.com/glomatico/gytmdl/blob/master/gytmdl/cli.py"
click node_config "https://github.com/glomatico/gytmdl/blob/master/gytmdl/cli.py"
click node_pathcheck "https://github.com/glomatico/gytmdl/blob/master/gytmdl/utils.py"
click node_downloader "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_artistselect "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_metadata "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_audio "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_tagging "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_cover "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py"
click node_lyrics "https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.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_cli,node_config,node_pathcheck,node_user toneBlue
class node_downloader,node_artistselect toneAmber
class node_metadata,node_audio,node_tagging,node_cover,node_lyrics,node_ytmusic,node_imageservice toneMint
class node_outputfiles,node_lyricfiles,node_coverfiles toneRose
class node_ytdlp,node_selection,node_ffmpeg,node_musicservice toneIndigo
```

## Components

### CLI and configuration

- [Command workflow](https://github.com/glomatico/gytmdl/blob/master/gytmdl/cli.py): `gytmdl/cli.py`
- [Config loading](https://github.com/glomatico/gytmdl/blob/master/gytmdl/cli.py): `gytmdl/cli.py`
- [Path validation](https://github.com/glomatico/gytmdl/blob/master/gytmdl/utils.py): `gytmdl/utils.py`

### Music resolution

- [Downloader](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`
- [Artist selection](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`

### Track processing

- [Track metadata](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`
- [Audio download](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`
- [Tag and cover embedding](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`
- [Cover retrieval](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`
- [Synced lyrics](https://github.com/glomatico/gytmdl/blob/master/gytmdl/downloader.py): `gytmdl/downloader.py`

### Output artifacts

- **Audio files**
- **LRC files**
- **Cover files**

### Other components

- **CLI user**
- **YouTube Music API**
- **yt-dlp**
- **Interactive selection**
- **FFmpeg remux**
- **YouTube Music**
- **Cover image server**

## Connections

- CLI user → Command workflow: provides URLs/options
- Command workflow → Config loading: loads settings
- Command workflow → Path validation: validates cookies
- Command workflow → Downloader: creates and calls
- Downloader → YouTube Music API: queries metadata
- Downloader → yt-dlp: resolves and downloads
- Downloader → Artist selection: resolves artist URLs
- Artist selection → Interactive selection: prompts selection
- Artist selection → YouTube Music API: lists albums
- Command workflow → Track metadata: gets track tags
- Track metadata → YouTube Music API: fetches lyrics and album data
- Command workflow → Audio download: downloads track
- Command workflow → Tag and cover embedding: applies tags
- Command workflow → Cover retrieval: gets cover details
- Command workflow → Synced lyrics: gets synced lyrics
- Audio download → yt-dlp: fetches audio
- Command workflow → FFmpeg remux: requests remux
- Tag and cover embedding → Cover image server: fetches cover bytes
- Cover retrieval → Cover image server: downloads image
- Synced lyrics → YouTube Music API: requests synced lyrics
- Command workflow → Audio files: writes track
- Command workflow → LRC files: writes LRC
- Command workflow → Cover files: optionally saves cover
- Command workflow → Audio download: optionally selects aria2c mode