# moritzgladigau/yt2mpx architecture

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

- Interactive diagram: https://gitdiagram.com/moritzgladigau/yt2mpx
- Repository: https://github.com/moritzgladigau/yt2mpx

## Overview

yt2mpX is a local web app for checking YouTube video or playlist links, selecting media options, and downloading converted files. The main workflow runs from browser link checking through job creation, media processing, metadata review, and final delivery; playlists are packaged as ZIPs. The README also documents optional account cookies and fingerprint-based identification, plus fallback metadata and cover-art lookup. Backend processing is concentrated in app/main.py, while app/static/app.js implements the browser workflow. Some backend stages are documented but their implementation details were not sampled.

Main entry points: [`app/main.py`](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py) (Job orchestration), [`app/static/app.js`](https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js) (Download UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Browser interface"]
  node_web_ui["Download UI<br/>[app.js]"]
  node_playlist["Playlist selection<br/>[app.js]"]
  node_metadata_review["Metadata review<br/>[app.js]"]
end

subgraph group_processing["Media processing"]
  node_probe["Link probe<br/>[main.py]"]
  node_job["Job orchestration<br/>[main.py]"]
  node_youtube["YouTube / yt-dlp"]
  node_convert["Media conversion<br/>[main.py]"]
end

subgraph group_enrichment["Metadata enrichment"]
  node_fingerprint["Audio fingerprinting<br/>[main.py]"]
  node_acoustid["AcoustID"]
  node_musicbrainz["MusicBrainz lookup"]
  node_tagging["Tag writing<br/>[main.py]"]
  node_cover_art["Cover art lookup<br/>[main.py]"]
end

subgraph group_delivery["Job delivery"]
  node_job_storage[("Temporary job files<br/>[main.py]")]
  node_download["File and ZIP download<br/>[main.py]"]
  node_history["Download history<br/>[app.js]"]
end

node_user(("Home-network user"))

node_user -->|"uses"| node_web_ui
node_web_ui -->|"checks link"| node_probe
node_web_ui -->|"selects items"| node_playlist
node_web_ui -->|"starts job"| node_job
node_probe -->|"inspects URL"| node_youtube
node_job -->|"downloads media"| node_youtube
node_job -->|"converts media"| node_convert
node_job -.->|"uses selections"| node_playlist
node_convert -.->|"fingerprints tracks"| node_fingerprint
node_fingerprint -->|"identifies audio"| node_acoustid
node_acoustid -->|"matches recording"| node_musicbrainz
node_job -->|"provides suggestions"| node_metadata_review
node_metadata_review -->|"submits edits"| node_job
node_job -->|"finds artwork"| node_cover_art
node_job -->|"writes tags"| node_tagging
node_job -->|"stores files"| node_job_storage
node_job -->|"prepares result"| node_download
node_web_ui -->|"refreshes history"| node_history
node_history -->|"requests history"| node_job
node_download -->|"delivers file"| node_user

click node_web_ui "https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js"
click node_probe "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_job "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_convert "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_playlist "https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js"
click node_fingerprint "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_metadata_review "https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js"
click node_tagging "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_cover_art "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_job_storage "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_download "https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py"
click node_history "https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js"

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_web_ui,node_playlist,node_metadata_review,node_user toneBlue
class node_probe,node_job,node_youtube,node_convert toneAmber
class node_fingerprint,node_acoustid,node_musicbrainz,node_tagging,node_cover_art toneMint
class node_job_storage,node_download,node_history toneRose
```

## Components

### Browser interface

- [Download UI](https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js): `app/static/app.js`
- [Playlist selection](https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js): `app/static/app.js`
- [Metadata review](https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js): `app/static/app.js`

### Media processing

- [Link probe](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- [Job orchestration](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- **YouTube / yt-dlp**
- [Media conversion](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`

### Metadata enrichment

- [Audio fingerprinting](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- **AcoustID**
- **MusicBrainz lookup**
- [Tag writing](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- [Cover art lookup](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`

### Job delivery

- [Temporary job files](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- [File and ZIP download](https://github.com/moritzgladigau/yt2mpx/blob/main/app/main.py): `app/main.py`
- [Download history](https://github.com/moritzgladigau/yt2mpx/blob/main/app/static/app.js): `app/static/app.js`

### Other components

- **Home-network user**

## Connections

- Home-network user → Download UI: uses (evidence: `README.md`)
- Download UI → Link probe: checks link (evidence: `app/static/app.js`)
- Download UI → Playlist selection: selects items (evidence: `app/static/app.js`)
- Download UI → Job orchestration: starts job (evidence: `app/static/app.js`)
- Link probe → YouTube / yt-dlp: inspects URL (evidence: `README.md`)
- Job orchestration → YouTube / yt-dlp: downloads media (evidence: `README.md`)
- Job orchestration → Media conversion: converts media (evidence: `README.md`)
- Job orchestration → Playlist selection: uses selections
- Media conversion → Audio fingerprinting: fingerprints tracks (evidence: `app/main.py`)
- Audio fingerprinting → AcoustID: identifies audio (evidence: `README.md`)
- AcoustID → MusicBrainz lookup: matches recording (evidence: `README.md`)
- Job orchestration → Metadata review: provides suggestions (evidence: `README.md`)
- Metadata review → Job orchestration: submits edits (evidence: `app/static/app.js`)
- Job orchestration → Cover art lookup: finds artwork (evidence: `README.md`)
- Job orchestration → Tag writing: writes tags (evidence: `README.md`)
- Job orchestration → Temporary job files: stores files (evidence: `README.md`)
- Job orchestration → File and ZIP download: prepares result (evidence: `README.md`)
- Download UI → Download history: refreshes history (evidence: `app/static/app.js`)
- Download history → Job orchestration: requests history (evidence: `app/static/app.js`)
- File and ZIP download → Home-network user: delivers file (evidence: `README.md`)
