# williamschack/spotify-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/williamschack/spotify-downloader
- Repository: https://github.com/williamschack/spotify-downloader

## Overview

Spotify Downloader is a GUI application for finding and downloading Spotify songs and playlists through YouTube. The principal workflow runs from the user’s URL and settings, through Spotify metadata and YouTube Music matching/download, to audio files and optional playlist/LRC outputs. The README excerpt documents the GUI and customization; sampled source confirms application setup, settings wiring, Spotify authentication, update checks, and playlist-file generation. Several downloader and API implementations were not sampled, so their links reflect the documented product workflow rather than inspected call sites.

Main entry points: [`Spotify Downloader/Downloading/PlaylistDownloader.cpp`](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/PlaylistDownloader.cpp) (Download coordinator), [`Spotify Downloader/Playlist/PlaylistFile.cpp`](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Playlist/PlaylistFile.cpp) (Playlist file writer), [`Spotify Downloader/Network/Network.cpp`](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/Network.cpp) (Network transport), [`Spotify Downloader/UI/UISetup.cpp`](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/UI/UISetup.cpp) (GUI and settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["GUI and settings<br/>[UISetup.cpp]"]
  node_config["Download settings<br/>[Config.cpp]"]
  node_app["Application window"]
  node_worker["Download thread"]
end

subgraph group_download["Download workflow"]
  node_manager["Download coordinator"]
  node_song["Song model<br/>[Song.cpp]"]
  node_songdownloader["Song downloader<br/>[SongDownloader.cpp]"]
end

subgraph group_services["Network services"]
  node_spotify["Spotify metadata API<br/>[SpotifyAPI.cpp]"]
  node_auth["Spotify auth retrieval"]
  node_ytmusic["YouTube Music API<br/>[YTMusicAPI.cpp]"]
  node_network["Network transport<br/>[Network.cpp]"]
  node_musixapi["Musixmatch API<br/>[MusixmatchAPI.cpp]"]
end

subgraph group_outputs["Files and metadata"]
  node_audio[("Downloaded audio")]
  node_taglib["Audio tags<br/>[fileref.h]"]
  node_lyrics["Lyrics and LRC<br/>[Lyrics.cpp]"]
  node_lrcfile["LRC writer<br/>[LRCFile.cpp]"]
  node_playlistfile["Playlist file writer<br/>[PlaylistFile.cpp]"]
  node_formats["Playlist formats"]
end

node_user(("User"))
node_spotifyservice{{"Spotify"}}
node_youtube{{"YouTube Music"}}
node_filesystem[("Local filesystem")]
node_musixmatch{{"Musixmatch lyrics"}}

node_user -->|"enters URL"| node_ui
node_ui -->|"sets options"| node_config
node_ui -->|"starts download"| node_app
node_app -->|"dispatches work"| node_worker
node_worker -->|"runs download"| node_manager
node_manager -->|"requests metadata"| node_spotify
node_spotify -->|"sends requests"| node_network
node_network -->|"queries"| node_spotifyservice
node_auth -.->|"retrieves credentials"| node_spotifyservice
node_manager -->|"handles tracks"| node_song
node_manager -->|"downloads tracks"| node_songdownloader
node_songdownloader -->|"searches and downloads"| node_ytmusic
node_ytmusic -->|"sends requests"| node_network
node_network -->|"queries"| node_youtube
node_songdownloader -->|"writes audio"| node_audio
node_audio -->|"stored on"| node_filesystem
node_manager -.->|"obtains lyrics"| node_lyrics
node_lyrics -.->|"requests lyrics"| node_musixapi
node_musixapi -.->|"queries"| node_musixmatch
node_lyrics -.->|"creates timed lyrics"| node_lrcfile
node_lrcfile -.->|"writes file"| node_filesystem
node_manager -.->|"creates playlist"| node_playlistfile
node_playlistfile -->|"reads audio tags"| node_taglib
node_playlistfile -->|"selects format"| node_formats
node_playlistfile -->|"writes file"| node_filesystem

click node_ui "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/UI/UISetup.cpp"
click node_config "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Config.cpp"
click node_app "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/SpotifyDownloader.cpp"
click node_worker "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/UI/CustomWidgets/DownloaderThread.cpp"
click node_manager "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/PlaylistDownloader.cpp"
click node_song "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/Song.cpp"
click node_songdownloader "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/SongDownloader.cpp"
click node_spotify "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/SpotifyAPI.cpp"
click node_auth "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/SpotifyAuthRetriever.cpp"
click node_ytmusic "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/YTMusicAPI.cpp"
click node_network "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/Network.cpp"
click node_taglib "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/include/taglib/fileref.h"
click node_lyrics "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Lyrics/Lyrics.cpp"
click node_lrcfile "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Lyrics/LRCFile.cpp"
click node_playlistfile "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Playlist/PlaylistFile.cpp"
click node_formats "https://github.com/williamschack/spotify-downloader/tree/main/Spotify%20Downloader/Playlist"
click node_musixapi "https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/MusixmatchAPI.cpp"

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_ui,node_config,node_app,node_worker,node_user toneBlue
class node_manager,node_song,node_songdownloader,node_filesystem toneAmber
class node_spotify,node_auth,node_ytmusic,node_network,node_musixapi toneMint
class node_audio,node_taglib,node_lyrics,node_lrcfile,node_playlistfile,node_formats toneRose
class node_spotifyservice,node_youtube,node_musixmatch toneIndigo
```

## Components

### User interface

- [GUI and settings](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/UI/UISetup.cpp): `Spotify Downloader/UI/UISetup.cpp`
- [Download settings](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Config.cpp): `Spotify Downloader/Config.cpp`
- [Application window](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/SpotifyDownloader.cpp): `Spotify Downloader/SpotifyDownloader.cpp`
- [Download thread](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/UI/CustomWidgets/DownloaderThread.cpp): `Spotify Downloader/UI/CustomWidgets/DownloaderThread.cpp`

### Download workflow

- [Download coordinator](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/PlaylistDownloader.cpp): `Spotify Downloader/Downloading/PlaylistDownloader.cpp`
- [Song model](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/Song.cpp): `Spotify Downloader/Downloading/Song.cpp`
- [Song downloader](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Downloading/SongDownloader.cpp): `Spotify Downloader/Downloading/SongDownloader.cpp`

### Network services

- [Spotify metadata API](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/SpotifyAPI.cpp): `Spotify Downloader/Network/SpotifyAPI.cpp`
- [Spotify auth retrieval](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/SpotifyAuthRetriever.cpp): `Spotify Downloader/Network/SpotifyAuthRetriever.cpp`
- [YouTube Music API](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/YTMusicAPI.cpp): `Spotify Downloader/Network/YTMusicAPI.cpp`
- [Network transport](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/Network.cpp): `Spotify Downloader/Network/Network.cpp`
- [Musixmatch API](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Network/MusixmatchAPI.cpp): `Spotify Downloader/Network/MusixmatchAPI.cpp`

### Files and metadata

- **Downloaded audio**
- [Audio tags](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/include/taglib/fileref.h): `Spotify Downloader/include/taglib/fileref.h`
- [Lyrics and LRC](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Lyrics/Lyrics.cpp): `Spotify Downloader/Lyrics/Lyrics.cpp`
- [LRC writer](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Lyrics/LRCFile.cpp): `Spotify Downloader/Lyrics/LRCFile.cpp`
- [Playlist file writer](https://github.com/williamschack/spotify-downloader/blob/main/Spotify%20Downloader/Playlist/PlaylistFile.cpp): `Spotify Downloader/Playlist/PlaylistFile.cpp`
- [Playlist formats](https://github.com/williamschack/spotify-downloader/tree/main/Spotify%20Downloader/Playlist): `Spotify Downloader/Playlist`

### Other components

- **User**
- **Spotify**
- **YouTube Music**
- **Local filesystem**
- **Musixmatch lyrics**

## Connections

- User → GUI and settings: enters URL
- GUI and settings → Download settings: sets options
- GUI and settings → Application window: starts download
- Application window → Download thread: dispatches work
- Download thread → Download coordinator: runs download
- Download coordinator → Spotify metadata API: requests metadata
- Spotify metadata API → Network transport: sends requests
- Network transport → Spotify: queries
- Spotify auth retrieval → Spotify: retrieves credentials
- Download coordinator → Song model: handles tracks
- Download coordinator → Song downloader: downloads tracks
- Song downloader → YouTube Music API: searches and downloads
- YouTube Music API → Network transport: sends requests
- Network transport → YouTube Music: queries
- Song downloader → Downloaded audio: writes audio
- Downloaded audio → Local filesystem: stored on
- Download coordinator → Lyrics and LRC: obtains lyrics
- Lyrics and LRC → Musixmatch API: requests lyrics
- Musixmatch API → Musixmatch lyrics: queries
- Lyrics and LRC → LRC writer: creates timed lyrics
- LRC writer → Local filesystem: writes file
- Download coordinator → Playlist file writer: creates playlist
- Playlist file writer → Audio tags: reads audio tags
- Playlist file writer → Playlist formats: selects format
- Playlist file writer → Local filesystem: writes file