# spoonnewman/ytmp3 architecture

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

- Interactive diagram: https://gitdiagram.com/spoonnewman/ytmp3
- Repository: https://github.com/spoonnewman/ytmp3

## Overview

ytmp3 is a cross-platform desktop and CLI utility that downloads YouTube audio and saves it as MP3 locally. The GUI accepts multiple links, output folder, quality, and playlist preference, then runs downloads in a background worker with progress/log events; the CLI offers URL arguments or interactive input. Both invoke yt-dlp, which uses ffmpeg for extraction/conversion, and save files to the chosen folder. The platform folders contain self-contained copies; the README identifies core/ as shared source. GUI excerpts are partial, so the graph omits uncertain internal progress-event details.

Main entry points: [`core/ytmp3.py`](https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3.py) (CLI app), [`core/ytmp3_gui.py`](https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3_gui.py) (Download worker), [`core/ytdlp_common.py`](https://github.com/spoonnewman/ytmp3/blob/main/core/ytdlp_common.py) (Runtime helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gui["GUI app<br/>[ytmp3_gui.py]"]
  node_cli["CLI app<br/>[ytmp3.py]"]
end

subgraph group_runtime["Download runtime"]
  node_worker["Download worker<br/>[ytmp3_gui.py]"]
  node_helpers["Runtime helpers<br/>[ytdlp_common.py]"]
end

subgraph group_integrations["External systems"]
  node_ytdlp["yt-dlp"]
  node_ffmpeg["ffmpeg"]
  node_youtube["YouTube"]
  node_files[("Local MP3 files")]
end

node_user(("User"))

node_user -->|"enters links"| node_gui
node_gui -->|"starts worker"| node_worker
node_worker -->|"resolves tools"| node_helpers
node_worker -->|"runs download"| node_ytdlp
node_user -->|"provides URLs"| node_cli
node_cli -->|"resolves tools"| node_helpers
node_cli -->|"runs download"| node_ytdlp
node_ytdlp -->|"downloads media"| node_youtube
node_ytdlp -->|"extracts audio"| node_ffmpeg
node_ytdlp -->|"writes MP3"| node_files
node_user -->|"sets quality and folder"| node_cli
node_user -->|"sets options"| node_gui

click node_gui "https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3_gui.py"
click node_worker "https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3_gui.py"
click node_cli "https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3.py"
click node_helpers "https://github.com/spoonnewman/ytmp3/blob/main/core/ytdlp_common.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_gui,node_cli,node_user toneBlue
class node_worker,node_helpers toneAmber
class node_ytdlp,node_ffmpeg,node_youtube,node_files toneMint
```

## Components

### User interfaces

- [GUI app](https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3_gui.py): `core/ytmp3_gui.py`
- [CLI app](https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3.py): `core/ytmp3.py`

### Download runtime

- [Download worker](https://github.com/spoonnewman/ytmp3/blob/main/core/ytmp3_gui.py): `core/ytmp3_gui.py`
- [Runtime helpers](https://github.com/spoonnewman/ytmp3/blob/main/core/ytdlp_common.py): `core/ytdlp_common.py`

### External systems

- **yt-dlp**
- **ffmpeg**
- **YouTube**
- **Local MP3 files**

### Other components

- **User**

## Connections

- User → GUI app: enters links
- GUI app → Download worker: starts worker
- Download worker → Runtime helpers: resolves tools
- Download worker → yt-dlp: runs download
- User → CLI app: provides URLs
- CLI app → Runtime helpers: resolves tools
- CLI app → yt-dlp: runs download
- yt-dlp → YouTube: downloads media
- yt-dlp → ffmpeg: extracts audio
- yt-dlp → Local MP3 files: writes MP3
- User → CLI app: sets quality and folder
- User → GUI app: sets options