# sunetworkingnerd/ytdlp-gui architecture

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

- Interactive diagram: https://gitdiagram.com/sunetworkingnerd/ytdlp-gui
- Repository: https://github.com/sunetworkingnerd/ytdlp-gui

## Overview

yt-dlp GUI is a PySide6 desktop front end for configuring and running yt-dlp. The main workflow is: enter a URL, optionally fetch its metadata and formats, configure download options, then run and monitor jobs in the queue. A separate channel-archive workflow builds yt-dlp arguments for resumable, configurable channel downloads. The README documents cookies/login, live-stream controls, and theme preferences as additional capabilities. The graph uses the shown source and README; some UI-to-runtime connections rely on the source index, so unsampled details are not expanded.

Main entry points: [`ytdlp_gui/ui/main_window.py`](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py) (Main window), [`ytdlp_gui/core/runner.py`](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/runner.py) (Process runner), [`ytdlp_gui/__main__.py`](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/__main__.py) (App entry), [`ytdlp_gui/ui/archive_dialog.py`](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/archive_dialog.py) (Archive dialog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_entry["App entry<br/>[__main__.py]"]
  node_main["Main window<br/>[main_window.py]"]
  node_queue["Queue and jobs<br/>[main_window.py]"]
end

subgraph group_download["Download Workflows"]
  node_archive_ui["Archive dialog<br/>[archive_dialog.py]"]
  node_archive_config["Archive arguments<br/>[archive.py]"]
  node_metadata["Info fetch<br/>[metadata.py]"]
  node_cookies["Cookie arguments<br/>[cookies.py]"]
  node_live["Live controls<br/>[main_window.py]"]
end

subgraph group_core["Download Core"]
  node_runner["Process runner<br/>[runner.py]"]
end

subgraph group_settings["Options and Appearance"]
  node_options_ui["Options panel<br/>[options_panel.py]"]
  node_options_model["Option model<br/>[options_model.py]"]
  node_theme_ui["Theme application<br/>[theme.py]"]
  node_theme_model["Theme choices<br/>[theme.py]"]
end

node_user(("User"))
node_ytdlp["yt-dlp"]
node_filesystem["Download files"]

node_user -->|"enters URLs"| node_main
node_entry -->|"creates model"| node_options_model
node_entry -->|"opens window"| node_main
node_entry -->|"applies theme"| node_theme_ui
node_main -->|"creates panel"| node_options_ui
node_options_ui -->|"renders options"| node_options_model
node_main -->|"fetches info"| node_metadata
node_metadata -->|"uses run settings"| node_runner
node_main -->|"builds cookie args"| node_cookies
node_main -->|"configures streams"| node_live
node_main -->|"opens dialog"| node_archive_ui
node_archive_ui -->|"builds arguments"| node_archive_config
node_archive_ui -->|"checks tools"| node_runner
node_main -->|"runs archive"| node_archive_config
node_main -->|"manages jobs"| node_queue
node_queue -->|"starts and stops"| node_runner
node_runner -->|"launches process"| node_ytdlp
node_ytdlp -->|"writes downloads"| node_filesystem
node_theme_ui -->|"resolves choice"| node_theme_model
node_user -->|"chooses appearance"| node_theme_ui

click node_entry "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/__main__.py"
click node_main "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py"
click node_options_ui "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/options_panel.py"
click node_options_model "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/options_model.py"
click node_archive_ui "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/archive_dialog.py"
click node_archive_config "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/archive.py"
click node_metadata "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/metadata.py"
click node_cookies "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/cookies.py"
click node_live "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py"
click node_queue "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py"
click node_runner "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/runner.py"
click node_theme_ui "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/theme.py"
click node_theme_model "https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/theme.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_entry,node_main,node_queue,node_user toneBlue
class node_archive_ui,node_archive_config,node_metadata,node_cookies,node_live toneAmber
class node_runner toneMint
class node_options_ui,node_options_model,node_theme_ui,node_theme_model toneRose
class node_ytdlp,node_filesystem toneIndigo
```

## Components

### Application UI

- [App entry](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/__main__.py): `ytdlp_gui/__main__.py`
- [Main window](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py): `ytdlp_gui/ui/main_window.py`
- [Queue and jobs](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py): `ytdlp_gui/ui/main_window.py`

### Download Workflows

- [Archive dialog](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/archive_dialog.py): `ytdlp_gui/ui/archive_dialog.py`
- [Archive arguments](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/archive.py): `ytdlp_gui/core/archive.py`
- [Info fetch](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/metadata.py): `ytdlp_gui/core/metadata.py`
- [Cookie arguments](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/cookies.py): `ytdlp_gui/core/cookies.py`
- [Live controls](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/main_window.py): `ytdlp_gui/ui/main_window.py`

### Download Core

- [Process runner](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/runner.py): `ytdlp_gui/core/runner.py`

### Options and Appearance

- [Options panel](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/options_panel.py): `ytdlp_gui/ui/options_panel.py`
- [Option model](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/options_model.py): `ytdlp_gui/core/options_model.py`
- [Theme application](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/ui/theme.py): `ytdlp_gui/ui/theme.py`
- [Theme choices](https://github.com/sunetworkingnerd/ytdlp-gui/blob/main/ytdlp_gui/core/theme.py): `ytdlp_gui/core/theme.py`

### Other components

- **User**
- **yt-dlp**
- **Download files**

## Connections

- User → Main window: enters URLs (evidence: `README.md`)
- App entry → Option model: creates model (evidence: `ytdlp_gui/__main__.py`)
- App entry → Main window: opens window (evidence: `ytdlp_gui/__main__.py`)
- App entry → Theme application: applies theme (evidence: `ytdlp_gui/__main__.py`)
- Main window → Options panel: creates panel (evidence: `ytdlp_gui/ui/main_window.py`)
- Options panel → Option model: renders options (evidence: `ytdlp_gui/ui/options_panel.py`)
- Main window → Info fetch: fetches info (evidence: `ytdlp_gui/ui/main_window.py`)
- Info fetch → Process runner: uses run settings (evidence: `ytdlp_gui/core/metadata.py`)
- Main window → Cookie arguments: builds cookie args (evidence: `ytdlp_gui/ui/main_window.py`)
- Main window → Live controls: configures streams (evidence: `README.md`)
- Main window → Archive dialog: opens dialog (evidence: `ytdlp_gui/ui/main_window.py`)
- Archive dialog → Archive arguments: builds arguments (evidence: `ytdlp_gui/ui/archive_dialog.py`)
- Archive dialog → Process runner: checks tools (evidence: `ytdlp_gui/ui/archive_dialog.py`)
- Main window → Archive arguments: runs archive (evidence: `README.md`)
- Main window → Queue and jobs: manages jobs (evidence: `ytdlp_gui/ui/main_window.py`)
- Queue and jobs → Process runner: starts and stops (evidence: `README.md`)
- Process runner → yt-dlp: launches process (evidence: `ytdlp_gui/core/runner.py`)
- yt-dlp → Download files: writes downloads (evidence: `README.md`)
- Theme application → Theme choices: resolves choice (evidence: `ytdlp_gui/ui/theme.py`)
- User → Theme application: chooses appearance (evidence: `README.md`)
