# omar-mk06/song-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/omar-mk06/song-downloader
- Repository: https://github.com/omar-mk06/song-downloader

## Overview

Song Downloader is a Spicetify extension with an optional localhost server. A player-bar button or track context-menu action enters the download workflow: it gets track details, prefers spotdl through the server, and falls back to a web lookup and browser download. The server saves songs and registers its folder in Spotify Local Files; the extension then requests an index refresh. The README documents these capabilities, while the edges below are limited to relationships visible in the sampled source or README.

Main entry points: [`downloadSong.js`](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js) (Download workflow), [`spotdl-server.py`](https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py) (HTTP endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Spotify Extension"]
  node_ui_actions["Download actions<br/>[downloadSong.js]"]
  node_download_flow["Download workflow<br/>[downloadSong.js]"]
  node_track_info["Track details<br/>[downloadSong.js]"]
  node_local_refresh["Local Files refresh<br/>[downloadSong.js]"]
end

subgraph group_download["Download Methods"]
  node_server_client["Server client<br/>[downloadSong.js]"]
  node_web_lookup["Web fallback lookup<br/>[downloadSong.js]"]
  node_browser_save["Browser file save<br/>[downloadSong.js]"]
end

subgraph group_server["Local Server"]
  node_http_handler["HTTP endpoints<br/>[spotdl-server.py]"]
  node_spotdl_runner["spotdl runner<br/>[spotdl-server.py]"]
  node_folder_setup["Folder setup<br/>[spotdl-server.py]"]
  node_prefs_registration["Prefs registration<br/>[spotdl-server.py]"]
  node_download_folder[("Download folder")]
end

subgraph group_integrations["External Services"]
  node_spotify_api["Spotify track API"]
  node_download_mirror["Download mirror"]
  node_cdn["Audio CDN"]
  node_local_files["Spotify Local Files"]
  node_spotdl["spotdl package"]
end

node_user(("Spotify user"))
node_spotify_ui["Spotify UI"]
node_spotify_prefs[("Spotify prefs")]

node_user -->|"uses"| node_spotify_ui
node_spotify_ui -->|"selects track"| node_ui_actions
node_ui_actions -->|"starts download"| node_download_flow
node_download_flow -->|"gets details"| node_track_info
node_track_info -->|"queries track"| node_spotify_api
node_download_flow -->|"checks and requests"| node_server_client
node_server_client -->|"HTTP requests"| node_http_handler
node_download_flow -->|"falls back"| node_web_lookup
node_web_lookup -->|"queries mirror"| node_download_mirror
node_download_mirror -->|"returns link"| node_cdn
node_download_flow -->|"saves fallback"| node_browser_save
node_browser_save -->|"fetches audio"| node_cdn
node_http_handler -->|"runs download"| node_spotdl_runner
node_spotdl_runner -->|"invokes package"| node_spotdl
node_spotdl_runner -->|"writes songs"| node_download_folder
node_http_handler -->|"handles setup"| node_folder_setup
node_folder_setup -->|"creates folder"| node_download_folder
node_folder_setup -->|"registers folder"| node_prefs_registration
node_prefs_registration -->|"updates prefs"| node_spotify_prefs
node_download_flow -->|"refreshes after success"| node_local_refresh
node_local_refresh -->|"requests refresh"| node_local_files

click node_ui_actions "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_download_flow "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_track_info "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_server_client "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_web_lookup "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_browser_save "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_local_refresh "https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js"
click node_http_handler "https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py"
click node_spotdl_runner "https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py"
click node_folder_setup "https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py"
click node_prefs_registration "https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.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_ui_actions,node_download_flow,node_track_info,node_local_refresh,node_user,node_spotify_ui toneBlue
class node_server_client,node_web_lookup,node_browser_save,node_spotify_prefs toneAmber
class node_http_handler,node_spotdl_runner,node_folder_setup,node_prefs_registration,node_download_folder toneMint
class node_spotify_api,node_download_mirror,node_cdn,node_local_files,node_spotdl toneRose
```

## Components

### Spotify Extension

- [Download actions](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`
- [Download workflow](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`
- [Track details](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`
- [Local Files refresh](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`

### Download Methods

- [Server client](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`
- [Web fallback lookup](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`
- [Browser file save](https://github.com/omar-mk06/song-downloader/blob/main/downloadSong.js): `downloadSong.js`

### Local Server

- [HTTP endpoints](https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py): `spotdl-server.py`
- [spotdl runner](https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py): `spotdl-server.py`
- [Folder setup](https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py): `spotdl-server.py`
- [Prefs registration](https://github.com/omar-mk06/song-downloader/blob/main/spotdl-server.py): `spotdl-server.py`
- **Download folder**

### External Services

- **Spotify track API**
- **Download mirror**
- **Audio CDN**
- **Spotify Local Files**
- **spotdl package**

### Other components

- **Spotify user**
- **Spotify UI**
- **Spotify prefs**

## Connections

- Spotify user → Spotify UI: uses (evidence: `README.md`)
- Spotify UI → Download actions: selects track (evidence: `README.md`)
- Download actions → Download workflow: starts download (evidence: `downloadSong.js`)
- Download workflow → Track details: gets details (evidence: `downloadSong.js`)
- Track details → Spotify track API: queries track (evidence: `downloadSong.js`)
- Download workflow → Server client: checks and requests (evidence: `downloadSong.js`)
- Server client → HTTP endpoints: HTTP requests (evidence: `README.md`)
- Download workflow → Web fallback lookup: falls back (evidence: `downloadSong.js`)
- Web fallback lookup → Download mirror: queries mirror (evidence: `downloadSong.js`)
- Download mirror → Audio CDN: returns link
- Download workflow → Browser file save: saves fallback (evidence: `downloadSong.js`)
- Browser file save → Audio CDN: fetches audio (evidence: `downloadSong.js`)
- HTTP endpoints → spotdl runner: runs download (evidence: `spotdl-server.py`)
- spotdl runner → spotdl package: invokes package (evidence: `spotdl-server.py`)
- spotdl runner → Download folder: writes songs (evidence: `README.md`)
- HTTP endpoints → Folder setup: handles setup (evidence: `spotdl-server.py`)
- Folder setup → Download folder: creates folder (evidence: `spotdl-server.py`)
- Folder setup → Prefs registration: registers folder (evidence: `spotdl-server.py`)
- Prefs registration → Spotify prefs: updates prefs (evidence: `spotdl-server.py`)
- Download workflow → Local Files refresh: refreshes after success (evidence: `downloadSong.js`)
- Local Files refresh → Spotify Local Files: requests refresh (evidence: `downloadSong.js`)
