# ivensarj/downloader architecture

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

## Overview

Baixador de Mídia is a desktop Python app for downloading authorized video and audio links in batches. The main workflow collects links and download options, runs concurrent jobs through yt-dlp or the Spotify/spotDL path, reports per-item progress, and saves files to a folder or ZIP. The README also documents playlist handling, retries, cancellation, saved preferences, and runtime checks. The source is a single substantial file; the map separates its responsibilities, while several connections rely on README descriptions rather than sampled call sites.

Main entry points: [`downloader.py`](https://github.com/ivensarj/downloader/blob/main/downloader.py) (Batch coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_ui["Download interface<br/>[downloader.py]"]
  node_link_input["Link input<br/>[downloader.py]"]
  node_options["Download options<br/>[downloader.py]"]
  node_progress["Progress and log<br/>[downloader.py]"]
end

subgraph group_jobs["Batch downloads"]
  node_batch["Batch coordinator<br/>[downloader.py]"]
  node_job_queue["Concurrent jobs<br/>[downloader.py]"]
  node_retry_cancel["Retry and cancel<br/>[downloader.py]"]
end

subgraph group_delivery["Output and settings"]
  node_preferences[("Saved preferences<br/>[downloader.py]")]
  node_output["Downloaded files"]
  node_zip["ZIP packaging<br/>[downloader.py]"]
end

subgraph group_integrations["Download integrations"]
  node_download_dispatch["Download dispatch<br/>[downloader.py]"]
  node_ytdlp["yt-dlp engine<br/>[downloader.py]"]
  node_spotify["Spotify handling<br/>[downloader.py]"]
  node_runtime_check["YouTube runtime check<br/>[downloader.py]"]
  node_ffmpeg["FFmpeg processing"]
end

node_user(("User"))
node_platforms(("Video platforms"))
node_spotify_service(("Spotify and audio search"))
node_local_storage[("Local storage")]

node_user -->|"configures downloads"| node_ui
node_ui -->|"enters links"| node_link_input
node_user -->|"pastes or imports"| node_link_input
node_ui -->|"chooses format"| node_options
node_ui -.->|"starts batch"| node_batch
node_batch -->|"runs concurrently"| node_job_queue
node_batch -->|"supports retry and cancel"| node_retry_cancel
node_batch -->|"runs each item"| node_download_dispatch
node_download_dispatch -->|"dispatches non-Spotify"| node_ytdlp
node_download_dispatch -->|"dispatches Spotify"| node_spotify
node_ytdlp -->|"downloads media"| node_platforms
node_spotify -->|"looks up tracks"| node_spotify_service
node_ytdlp -->|"processes media"| node_ffmpeg
node_spotify -.->|"creates MP3"| node_ffmpeg
node_runtime_check -->|"checks readiness"| node_ytdlp
node_batch -->|"reports item updates"| node_progress
node_progress -.->|"updates display"| node_ui
node_batch -->|"saves downloads"| node_output
node_batch -->|"packages when selected"| node_zip
node_zip -->|"writes archive"| node_output
node_output -->|"writes files"| node_local_storage
node_options -->|"persists choices"| node_preferences
node_preferences -->|"stores configuration"| node_local_storage

click node_ui "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_link_input "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_options "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_progress "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_batch "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_job_queue "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_retry_cancel "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_download_dispatch "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_ytdlp "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_spotify "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_runtime_check "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_preferences "https://github.com/ivensarj/downloader/blob/main/downloader.py"
click node_zip "https://github.com/ivensarj/downloader/blob/main/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_ui,node_link_input,node_options,node_progress,node_user toneBlue
class node_batch,node_job_queue,node_retry_cancel,node_local_storage toneAmber
class node_preferences,node_output,node_zip toneMint
class node_download_dispatch,node_ytdlp,node_spotify,node_runtime_check,node_ffmpeg toneRose
class node_platforms,node_spotify_service toneIndigo
```

## Components

### Desktop interface

- [Download interface](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Link input](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Download options](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Progress and log](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`

### Batch downloads

- [Batch coordinator](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Concurrent jobs](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Retry and cancel](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`

### Output and settings

- [Saved preferences](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- **Downloaded files**
- [ZIP packaging](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`

### Download integrations

- [Download dispatch](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [yt-dlp engine](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [Spotify handling](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- [YouTube runtime check](https://github.com/ivensarj/downloader/blob/main/downloader.py): `downloader.py`
- **FFmpeg processing**

### Other components

- **User**
- **Video platforms**
- **Spotify and audio search**
- **Local storage**

## Connections

- User → Download interface: configures downloads (evidence: `README.md`)
- Download interface → Link input: enters links (evidence: `README.md`)
- User → Link input: pastes or imports (evidence: `README.md`)
- Download interface → Download options: chooses format (evidence: `downloader.py`)
- Download interface → Batch coordinator: starts batch (evidence: `downloader.py`)
- Batch coordinator → Concurrent jobs: runs concurrently (evidence: `README.md`)
- Batch coordinator → Retry and cancel: supports retry and cancel (evidence: `README.md`)
- Batch coordinator → Download dispatch: runs each item (evidence: `downloader.py`)
- Download dispatch → yt-dlp engine: dispatches non-Spotify (evidence: `downloader.py`)
- Download dispatch → Spotify handling: dispatches Spotify (evidence: `downloader.py`)
- yt-dlp engine → Video platforms: downloads media (evidence: `README.md`)
- Spotify handling → Spotify and audio search: looks up tracks (evidence: `README.md`)
- yt-dlp engine → FFmpeg processing: processes media (evidence: `README.md`)
- Spotify handling → FFmpeg processing: creates MP3
- YouTube runtime check → yt-dlp engine: checks readiness (evidence: `README.md`)
- Batch coordinator → Progress and log: reports item updates (evidence: `downloader.py`)
- Progress and log → Download interface: updates display (evidence: `downloader.py`)
- Batch coordinator → Downloaded files: saves downloads (evidence: `README.md`)
- Batch coordinator → ZIP packaging: packages when selected (evidence: `downloader.py`)
- ZIP packaging → Downloaded files: writes archive (evidence: `downloader.py`)
- Downloaded files → Local storage: writes files (evidence: `README.md`)
- Download options → Saved preferences: persists choices (evidence: `README.md`)
- Saved preferences → Local storage: stores configuration (evidence: `README.md`)
