# onnowhere/youtube_music_playlist_downloader architecture

> Architecture diagram of the GitHub repository onnowhere/youtube_music_playlist_downloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onnowhere/youtube_music_playlist_downloader
- Repository: https://github.com/onnowhere/youtube_music_playlist_downloader

## Overview

##### Project type and purpose
- This is an open-source, command-line Python application (“YouTube Music Playlist Downloader”) whose sole purpose is to download YouTube playlist audio as music albums, keep them in sync, and generate song metadata (tags and cover art). It is not a web- or GUI-based full-stack app but a utility/tool that integrates third-party services (YouTube), libraries (yt-dlp, ffmpeg), and the local file system.

##### File structure
- Top-level files:
- `youtube_music_playlist_downloader.py` – the main CLI entry point
- `requirements.txt` – Python dependencies
- `scripts/` – helper utilities:
– `build.py` – builds standalone executable via PyInstaller
– `1.2.0_updater.py` – updates existing albums
– `download_single.py` – download a single playlist or URL
– `yt-dlp-master/` – embedded yt-dlp submodule
- Config files: `.playlist_config.json` generated per album folder
- No `frontend` or `backend` dirs, so it’s a single-process CLI tool.

##### README for additional insights
- Core functions: playlist download, update, metadata tagging, cover art creation
- Uses ffmpeg for audio conversion
- Supports threading, custom naming, language selection for lyrics, extractor args for yt-dlp
- Build instructions show PyInstaller usage and inclusion of the yt-dlp submodule

##### Main components
a. User Interface (CLI)
b. Core Controller – orchestrates download/update workflows
c. Config Manager – reads/writes `.playlist_config.json` per album
d. Downloader Module – wraps yt-dlp to fetch video streams & metadata
e. Converter Module – calls ffmpeg to transcode audio
f. Metadata Generator – extracts tags (title, artist, album, lyrics) and embeds them
g. File Manager – organizes album folders, moves missing tracks, saves cover art
h. External Services:
- YouTube (via yt-dlp extractors)
- Local filesystem
i. Build Scripts (PyInstaller) – separate subcomponent for creating the executable

##### Relationships and data flow
- CLI → Core Controller
- Core Controller ↔ Config Manager (load/save settings)
- Core Controller → Downloader Module → YouTube (download stream + raw metadata)
- Downloader Module → Converter Module (pipe raw audio to ffmpeg)
- Converter Module → File Manager (writes .mp3 / .flac files)
- Downloader Module → Metadata Generator → File Manager (embed tags, cover art)
- Core Controller → File Manager (update folder structure, move deleted tracks)
- Build Script → PyInstaller → produces standalone EXE incorporating: Core Controller, yt-dlp submodule, all modules

##### Key architectural patterns and design principles
- Modular separation: distinct modules for downloading, conversion, metadata, configuration, and file management
- Plugin-style integration of yt-dlp (submodule) and ffmpeg (external executable)
- Config-driven behavior: supports per-album overrides and global options
- Optional concurrency: threading for parallel downloads
- Single-process, sequential orchestration with clear interfaces

- Blue for external systems (YouTube, filesystem)
- Orange for third-party executables/libraries (yt-dlp, ffmpeg)
- Green for your application modules
- Annotations for optional features (e.g., threading, extractor args)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Boundary
    subgraph "Runtime" 
        direction TB
        CLI["CLI (youtube_music_playlist_downloader.py)"]:::internal
        Core["Core Controller"]:::internal
        Config["Config Manager"]:::internal
        Downloader["Downloader Module (yt-dlp wrapper)"]:::internal
        Converter["Converter Module (ffmpeg invocation)"]:::internal
        Meta["Metadata Generator"]:::internal
        FileMgr["File Manager"]:::internal
    end

    %% Build Boundary
    subgraph "Build" 
        direction TB
        Build["Build Scripts (scripts/build.py)"]:::build
        Single["Single-Download Utility (scripts/download_single.py)"]:::build
        Updater["Updater Script (scripts/1.2.0_updater.py)"]:::build
    end

    %% External Services
    YouTube["YouTube"]:::external
    FS["Local Filesystem"]:::external
    YTDLP["yt-dlp submodule"]:::thirdparty
    FFMPEG["ffmpeg"]:::thirdparty

    %% Interactions
    CLI -->|"invokes"| Core
    Core -->|"load/save .playlist_config.json"| Config
    Core -->|"download request"| Downloader
    Downloader -->|"uses extractors"| YouTube
    Downloader -->|"raw audio+metadata"| Converter
    Converter -->|"transcoded audio"| FileMgr
    Downloader -->|"metadata payload"| Meta
    Meta -->|"embed tags & cover art"| FileMgr
    Core -->|"sync folders"| FileMgr

    Downloader -->|"wrappers"| YTDLP
    Converter -->|"executes"| FFMPEG
    FileMgr -->|"writes files"| FS

    %% Build Flow
    Build -->|"packages runtime"| Core
    Build -->|includes| YTDLP
    Single -->|"one-off download"| Core
    Updater -->|"update workflow"| Core

    %% Click Events
    click CLI "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click Core "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click Config "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click Converter "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click Meta "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click FileMgr "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/youtube_music_playlist_downloader.py"
    click Build "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/scripts/build.py"
    click Single "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/scripts/download_single.py"
    click Updater "https://github.com/onnowhere/youtube_music_playlist_downloader/blob/master/scripts/1.2.0_updater.py"
    click Downloader "https://github.com/onnowhere/youtube_music_playlist_downloader/tree/master/scripts/yt-dlp-master/"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef internal fill:#90EE90,stroke:#000,stroke-width:1px
    classDef thirdparty fill:#FFA500,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px

    %% Legend
    subgraph "Legend"
      direction TB
      EX[External Services]:::external
      TP[Third-Party Tools]:::thirdparty
      IN[Application Modules]:::internal
      BD[Build Components]:::build
    end
```
