# m-awais-11/youtube-video-downloder architecture

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

- Interactive diagram: https://gitdiagram.com/m-awais-11/youtube-video-downloder
- Repository: https://github.com/m-awais-11/youtube-video-downloder

## Overview

This is a Tkinter desktop app for previewing and downloading YouTube video or audio, individually or in batches. The main workflow runs from URL entry in the main window through metadata/thumbnail preview and format selection, then through the download engine to a saved media file, with progress controls, notifications, and a history record. Playlist expansion feeds the batch queue, while settings and history provide separate management flows. Core call paths are supported by sampled source; some UI wiring and history-dialog interactions are inferred from README descriptions and the documented project structure.

Main entry points: [`src/ui/main_window.py`](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/main_window.py) (Main window), [`src/core/downloader.py`](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/downloader.py) (Download engine), [`src/core/metadata.py`](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/metadata.py) (Metadata extractor), [`src/config.py`](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/config.py) (Settings manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_app["App launcher<br/>[main.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_preview["Preview card<br/>[preview_card.py]"]
  node_progress["Progress controls<br/>[progress_panel.py]"]
  node_batch["Batch panel<br/>[batch_panel.py]"]
  node_historyui["History dialog<br/>[history_dialog.py]"]
  node_settingsui["Settings dialog<br/>[settings_dialog.py]"]
  node_theme["Theme styling<br/>[theme.py]"]
  node_notifier["Notifications<br/>[notifier.py]"]
end

subgraph group_media["Media workflow"]
  node_metadata["Metadata extractor<br/>[metadata.py]"]
  node_engine["Download engine<br/>[downloader.py]"]
  node_utils["Media utilities<br/>[utils.py]"]
  node_downloads["Downloaded media"]
end

subgraph group_persistence["Preferences and history"]
  node_config["Settings manager<br/>[config.py]"]
  node_settingsfile["Settings file"]
  node_history["History manager<br/>[history.py]"]
  node_historydb[("History database")]
end

subgraph group_integrations["External tools"]
  node_yt["yt-dlp"]
  node_requests["Thumbnail host"]
  node_ffmpeg["FFmpeg"]
  node_os["Desktop OS"]
end

node_user(("User"))

node_user -->|"launches"| node_app
node_app -->|"creates"| node_window
node_user -->|"enters URLs"| node_window
node_window -->|"fetches preview"| node_metadata
node_metadata -->|"extracts info"| node_yt
node_metadata -->|"fetches thumbnail"| node_requests
node_window -->|"updates preview"| node_preview
node_window -->|"starts download"| node_engine
node_window -->|"updates progress"| node_progress
node_engine -->|"downloads media"| node_yt
node_engine -->|"records status"| node_history
node_engine -->|"formats progress"| node_utils
node_engine -->|"writes media"| node_downloads
node_engine -->|"reads FFmpeg setting"| node_config
node_utils -.->|"detects tool"| node_ffmpeg
node_metadata -->|"formats duration"| node_utils
node_metadata -->|"reads FFmpeg setting"| node_config
node_window -->|"hosts batch view"| node_batch
node_batch -->|"expands playlists"| node_metadata
node_batch -->|"processes queue"| node_engine
node_batch -->|"announces batch"| node_notifier
node_window -->|"announces download"| node_notifier
node_window -->|"applies theme"| node_theme
node_window -->|"reads and updates"| node_config
node_settingsui -->|"saves preferences"| node_config
node_window -->|"opens settings"| node_settingsui
node_window -->|"opens history"| node_historyui
node_historyui -->|"searches records"| node_history
node_history -->|"reads and writes"| node_historydb
node_config -->|"reads and writes"| node_settingsfile
node_notifier -->|"checks preference"| node_config
node_notifier -.->|"sends toast"| node_os
node_user -->|"queues URLs"| node_batch

click node_app "https://github.com/m-awais-11/youtube-video-downloder/blob/main/main.py"
click node_window "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/main_window.py"
click node_preview "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/preview_card.py"
click node_progress "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/progress_panel.py"
click node_batch "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/batch_panel.py"
click node_historyui "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/history_dialog.py"
click node_settingsui "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/settings_dialog.py"
click node_theme "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/theme.py"
click node_notifier "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/notifier.py"
click node_metadata "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/metadata.py"
click node_engine "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/downloader.py"
click node_utils "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/utils.py"
click node_config "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/config.py"
click node_history "https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/history.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_app,node_window,node_preview,node_progress,node_batch,node_historyui,node_settingsui,node_theme,node_notifier,node_user toneBlue
class node_metadata,node_engine,node_utils,node_downloads toneAmber
class node_config,node_settingsfile,node_history,node_historydb toneMint
class node_yt,node_requests,node_ffmpeg,node_os toneRose
```

## Components

### Desktop interface

- [App launcher](https://github.com/m-awais-11/youtube-video-downloder/blob/main/main.py): `main.py`
- [Main window](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/main_window.py): `src/ui/main_window.py`
- [Preview card](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/preview_card.py): `src/ui/components/preview_card.py`
- [Progress controls](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/progress_panel.py): `src/ui/components/progress_panel.py`
- [Batch panel](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/batch_panel.py): `src/ui/components/batch_panel.py`
- [History dialog](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/history_dialog.py): `src/ui/components/history_dialog.py`
- [Settings dialog](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/components/settings_dialog.py): `src/ui/components/settings_dialog.py`
- [Theme styling](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/theme.py): `src/ui/theme.py`
- [Notifications](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/ui/notifier.py): `src/ui/notifier.py`

### Media workflow

- [Metadata extractor](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/metadata.py): `src/core/metadata.py`
- [Download engine](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/downloader.py): `src/core/downloader.py`
- [Media utilities](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/utils.py): `src/core/utils.py`
- **Downloaded media**

### Preferences and history

- [Settings manager](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/config.py): `src/config.py`
- **Settings file**
- [History manager](https://github.com/m-awais-11/youtube-video-downloder/blob/main/src/core/history.py): `src/core/history.py`
- **History database**

### External tools

- **yt-dlp**
- **Thumbnail host**
- **FFmpeg**
- **Desktop OS**

### Other components

- **User**

## Connections

- User → App launcher: launches
- App launcher → Main window: creates
- User → Main window: enters URLs
- Main window → Metadata extractor: fetches preview
- Metadata extractor → yt-dlp: extracts info
- Metadata extractor → Thumbnail host: fetches thumbnail
- Main window → Preview card: updates preview
- Main window → Download engine: starts download
- Main window → Progress controls: updates progress
- Download engine → yt-dlp: downloads media
- Download engine → History manager: records status
- Download engine → Media utilities: formats progress
- Download engine → Downloaded media: writes media
- Download engine → Settings manager: reads FFmpeg setting
- Media utilities → FFmpeg: detects tool
- Metadata extractor → Media utilities: formats duration
- Metadata extractor → Settings manager: reads FFmpeg setting
- Main window → Batch panel: hosts batch view
- Batch panel → Metadata extractor: expands playlists
- Batch panel → Download engine: processes queue
- Batch panel → Notifications: announces batch
- Main window → Notifications: announces download
- Main window → Theme styling: applies theme
- Main window → Settings manager: reads and updates
- Settings dialog → Settings manager: saves preferences
- Main window → Settings dialog: opens settings
- Main window → History dialog: opens history
- History dialog → History manager: searches records
- History manager → History database: reads and writes
- Settings manager → Settings file: reads and writes
- Notifications → Settings manager: checks preference
- Notifications → Desktop OS: sends toast
- User → Batch panel: queues URLs