# aerusw/ytdownloaderstuff architecture

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

- Interactive diagram: https://gitdiagram.com/aerusw/ytdownloaderstuff
- Repository: https://github.com/aerusw/ytdownloaderstuff

## Overview

##### What this project is (type + purpose)
This repo is a **Windows-friendly Python CLI tool** for downloading YouTube videos with performance and compatibility features:
- **High-speed segmented downloads** via **aria2** (multi-connection/segment tuning)
- **Post-processing** via **ffmpeg** (AAC conversion + MP4 merge)
- **User-facing progress** via **tqdm**
- **Configurable defaults** via `~/.config/config.json` (with CLI override)
- Likely uses **yt-dlp** (or equivalent) to resolve YouTube media URLs/streams (README implies “yt-dlp JS runtime” optional)

So your “system” is not a distributed web app; it’s a **local CLI orchestrator** coordinating external executables and filesystem outputs.

##### How to read the file tree (architectural clues)
Top-level files strongly suggest a small modular CLI architecture:

- `YTDownload.py`
**Entry point / CLI interface**. Parses args, triggers download pipeline, handles interactive prompt.

- `configmanager.py` + `.config/config.json`
**Configuration layer**. Loads defaults, expands paths (`~`), merges CLI overrides, provides validated settings object.

- `downloadtool.py`
**Core orchestration**. Likely:
- resolves video metadata/streams (yt-dlp)
- starts aria2 segmented download(s)
- tracks segments/progress, maybe manages concurrency (`concurrent_segments`)
- triggers merge + audio conversion steps
- applies sequential naming (`video001.mp4`, etc.)

- `loggingtool.py`
**Logging layer**. Writes logs to configured folder, controls verbosity, log file naming, and captures stdout/stderr from aria2/ffmpeg.

- `requirements.txt`
Confirms Python deps (likely `tqdm`, `yt-dlp`, etc.).

**External runtime dependencies** (not in tree but required by README):
- `aria2c` binary
- `ffmpeg` binary
- (optional) Node.js for yt-dlp JS runtime

##### `downloadtool` spawns `aria2c` with
- segments, connections, segment-size
- concurrency controls (`concurrent_segments`)
##### On completion
- merges streams into MP4 (if separate audio/video)
- converts audio to AAC for Windows compatibility (ffmpeg)
##### Writes logs into log folder

- aria2/ffmpeg failures captured → logged → exit codes surfaced to user.

##### Labels (be explicit)
- “subprocess exec (aria2c)”
- “subprocess exec (ffmpeg)”
- “HTTPS media fetch”
- “read config JSON”
- “write mp4 / write logs”
- Config knobs on the aria2 interaction edge: `segments`, `connections`, `segment_size`, `concurrent_segments`.

##### “Don’t overthink it” decomposition (separate into as many components as possible)
- **Format/quality selector** (maps `--quality` to stream format)
- **Sequential filename allocator** (`video001.mp4`, `video002.mp4`)
- **aria2 job builder** (command-line construction + segment settings)
- **Progress reporter** (tqdm integration)
- **Post-processor**:
- merge step
- AAC conversion step
- **Cleanup** (temp parts removal)
- **Error handler** (stderr capture, exit codes, log emission)

##### System Context: user + CLI + YouTube + aria2/ffmpeg + filesystem/config/logs

These three together capture: boundaries, responsibilities, dependencies, runtime behavior, and performance-critical interactions (aria2 segmentation + ffmpeg steps).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1: System Context
    %% =========================
    subgraph "System Context (Local CLI Orchestrator)"
        direction TB

        U["User"]:::external

        subgraph "Windows Machine"
            direction TB

            CLI["Python CLI App\n(YTDownloadStuff)"]:::app

            subgraph "External Tools (Executables)"
                direction TB
                A2["aria2c\n(segmented downloader)"]:::exec
                FF["ffmpeg\n(merge + AAC conversion)"]:::exec
            end

            subgraph "Local Filesystem"
                direction TB
                CFG[("Config JSON\n(~/.config/config.json)")]:::store
                OUT[("Download Folder\n(final mp4 + temp parts)")]:::store
                LOG[("Log Folder\n(log files)")]:::store
            end
        end

        YT["YouTube / CDN\n(remote media source)"]:::cloud
    end

    U -->|"CLI_args_or_interactive_link"| CLI
    CLI -->|"read_config_JSON"| CFG
    CLI -->|"resolve_streams_metadata(yt-dlp)|HTTPS"| YT
    CLI -->|"subprocess_exec(aria2c)\nsegments/connections/segment_size/concurrent_segments"| A2
    A2 -->|"HTTPS_segmented_fetch"| YT
    A2 -->|"write_temp_parts"| OUT
    CLI -->|"subprocess_exec(ffmpeg)\nmerge+convert_AAC"| FF
    FF -->|"read_parts_write_final_mp4"| OUT
    CLI -->|"write_logs_and_capture_stdout/stderr"| LOG

    %% =========================
    %% Diagram 2: Component View
    %% =========================
    subgraph "Python Application (Modules / Components)"
        direction TB

        EP["YTDownload.py\nCLI + arg parsing + main workflow"]:::py
        CM["configmanager.py\nload/merge/validate config\npath expansion (~)"]:::py

        subgraph "downloadtool.py (Core Orchestration)"
            direction TB
            DT["downloadtool.py\npipeline coordinator"]:::py

            FQS["Format/Quality Selector\n(map --quality -> stream)"]:::subpy
            NFA["Sequential Filename Allocator\n(video001.mp4 ...)"]:::subpy
            AJB["aria2 Job Builder\n(cmdline + segment tuning)"]:::subpy
            PR["Progress Reporter\n(tqdm)"]:::subpy
            PP["Post-Processor\n(merge + AAC conversion)"]:::subpy
            CLN["Cleanup\n(remove temp parts)"]:::subpy
            EH["Error Handler\n(stderr capture, exit codes)"]:::subpy
        end

        LG["loggingtool.py\nverbosity + log file handling\ncapture subprocess output"]:::py

        YDL["YouTube Stream Resolver\n(yt-dlp integration)"]:::lib
        TQ["tqdm\nprogress UI"]:::lib
    end

    EP -->|"load_defaults_and_overrides"| CM
    EP -->|"invoke_download_pipeline"| DT
    DT -->|"structured_logs"| LG
    DT -->|"resolve_formats_and_select_stream"| YDL
    DT -->|"progress_updates"| TQ

    DT -->|"build_and_exec_download"| AJB
    AJB -->|"subprocess_exec"| A2
    DT -->|"post_process_merge_convert"| PP
    PP -->|"subprocess_exec"| FF

    DT -->|"write_outputs_and_temps"| OUT
    LG -->|"write_logs"| LOG
    CM -->|"read_config_JSON"| CFG

    %% =================================
    %% Diagram 3: Runtime Sequence (Flow)
    %% =================================
    subgraph "Runtime: Download One Video (End-to-End Workflow)"
        direction TB

        S1["1) User runs CLI (or enters link interactively)"]:::step
        S2["2) Load config (~/.config/config.json)"]:::step
        S3["3) Merge CLI overrides into defaults"]:::step
        S4["4) Resolve formats/streams and choose quality"]:::step
        S5["5) Spawn aria2c with segmentation tuning\n(segments/connections/segment_size/concurrent_segments)"]:::step
        S6["6) Monitor progress and update tqdm"]:::step
        S7["7) ffmpeg merge streams + convert audio to AAC"]:::step
        S8["8) Write final video###.mp4 and cleanup temps"]:::step
        S9["9) Write logs; surface errors via exit code"]:::step
    end

    S1 --> EP
    EP --> S2
    S2 --> CM
    CM --> CFG
    CM --> EP
    EP --> S3 --> DT
    DT --> S4 --> YDL --> YT
    DT --> S5 --> A2 --> YT
    A2 --> OUT
    DT --> S6 --> PR
    PR --> TQ
    DT --> S7 --> FF --> OUT
    DT --> S8 --> CLN --> OUT
    DT --> S9 --> LG --> LOG

    %% Error/Retry annotation (captured + logged)
    EH -.->|"on_failure: capture_stderr/exit_code"| LG
    A2 -.->|"nonzero_exit_code"| EH
    FF -.->|"nonzero_exit_code"| EH

    %% =========================
    %% Click Events (Mapped Paths)
    %% =========================
    click EP "https://github.com/aerusw/ytdownloaderstuff/blob/master/YTDownload.py"
    click CM "https://github.com/aerusw/ytdownloaderstuff/blob/master/configmanager.py"
    click CFG "https://github.com/aerusw/ytdownloaderstuff/blob/master/.config/config.json"
    click DT "https://github.com/aerusw/ytdownloaderstuff/blob/master/downloadtool.py"
    click LG "https://github.com/aerusw/ytdownloaderstuff/blob/master/loggingtool.py"

    %% extra mapped files (not primary nodes)
    REQ["requirements.txt\nPython deps"]:::file
    RD["Readme.md\nDocs + external deps"]:::file
    REQ -.->|"declares_deps"| EP
    RD -.->|"usage_and_setup"| EP
    click REQ "https://github.com/aerusw/ytdownloaderstuff/blob/master/requirements.txt"
    click RD "https://github.com/aerusw/ytdownloaderstuff/blob/master/Readme.md"

    %% =========================
    %% Styles (Color Required)
    %% =========================
    classDef external fill:#E8EEF6,stroke:#2B4C7E,stroke-width:1px,color:#0F1F3A
    classDef app fill:#BFD7FF,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
    classDef py fill:#93C5FD,stroke:#1E40AF,stroke-width:1px,color:#0B1B3A
    classDef subpy fill:#C7D2FE,stroke:#3730A3,stroke-width:1px,color:#0B1B3A
    classDef lib fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#0B1B3A
    classDef exec fill:#FDBA74,stroke:#C2410C,stroke-width:1px,color:#3A1700
    classDef store fill:#86EFAC,stroke:#166534,stroke-width:1px,color:#052E16
    classDef cloud fill:#D1FAE5,stroke:#047857,stroke-width:1px,color:#064E3B
    classDef step fill:#FDE68A,stroke:#B45309,stroke-width:1px,color:#3A2300
    classDef file fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
```
