# avi12/youtube-downloader architecture

> Architecture diagram of the GitHub repository avi12/youtube-downloader, 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/avi12/youtube-downloader
- Repository: https://github.com/avi12/youtube-downloader

## Overview

YouTube Downloader is a cross-browser extension that turns video or playlist selections into downloadable media. Users choose formats and tracks in YouTube’s injected controls; requests are captured and routed through the background download pipeline, which retrieves streams, assembles media in an offscreen processing context, and reports progress to the page and popup. The popup also exposes settings, active and recent downloads, and format changes. The README documents these capabilities; detailed internal wiring is shown only where supported by the sampled source.

Main entry points: [`src/layers/youtube/entrypoints/youtube.content/handlers/background.ts`](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube.content/handlers/background.ts) (Content message handlers), [`src/layers/background/handlers/pipeline-handlers.ts`](https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/handlers/pipeline-handlers.ts) (Pipeline handlers), [`src/layers/processing/entrypoints/download-worker/main.ts`](https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/download-worker/main.ts) (Download worker), [`src/lib/download-pipeline/index.ts`](https://github.com/avi12/youtube-downloader/blob/main/src/lib/download-pipeline/index.ts) (Mux and output pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_youtube["YouTube interface"]
  node_yt_entry["YouTube content entry<br/>[index.ts]"]
  node_download_ui["Download controls"]
  node_request_builder["Request builder"]
  node_youtube_api["YouTube stream metadata<br/>[youtube-api.ts]"]
  node_content_bridge["Content message handlers<br/>[background.ts]"]
  node_playlist_ui["Playlist downloader"]
end

subgraph group_background["Download coordination"]
  node_background_main["Background entry<br/>[main.ts]"]
  node_download_handlers["Download handlers"]
  node_pipeline_handlers["Pipeline handlers"]
  node_download_worker["Download worker<br/>[main.ts]"]
  node_stream_downloaders["SABR and CDN retrieval<br/>[sabr-downloader.ts]"]
  node_progress_state[("Progress and queue state<br/>[storage.ts]")]
end

subgraph group_processing["Media processing"]
  node_offscreen["Offscreen processing host<br/>[main.ts]"]
  node_pipeline["Mux and output pipeline<br/>[index.ts]"]
  node_mux_worker["FFmpeg mux worker<br/>[index.ts]"]
  node_opfs[("Temporary media files<br/>[opfs-output-fs.ts]")]
end

subgraph group_experience["Download management"]
  node_popup["Popup download manager<br/>[App.svelte]"]
  node_recent[("Recent downloads")]
  node_settings_ui["Download settings<br/>[SettingsTab.svelte]"]
end

node_user(("User"))
node_yt_page["YouTube page"]
node_youtube_service["YouTube services"]
node_browser_downloads["Browser download manager"]

node_user -->|"selects format"| node_download_ui
node_yt_page -->|"hosts controls"| node_yt_entry
node_yt_entry -->|"renders"| node_download_ui
node_download_ui -->|"builds request"| node_request_builder
node_youtube_api -->|"fetches metadata"| node_youtube_service
node_request_builder -->|"sends request"| node_content_bridge
node_content_bridge -->|"messages"| node_download_handlers
node_background_main -->|"registers"| node_download_handlers
node_background_main -->|"registers"| node_pipeline_handlers
node_download_handlers -->|"starts download"| node_download_worker
node_download_worker -->|"retrieves streams"| node_stream_downloaders
node_stream_downloaders -->|"requests media"| node_youtube_service
node_download_worker -->|"transfers chunks"| node_offscreen
node_offscreen -->|"dispatches processing"| node_pipeline
node_pipeline -->|"runs mux jobs"| node_mux_worker
node_mux_worker -->|"writes output"| node_opfs
node_pipeline -->|"saves media"| node_browser_downloads
node_pipeline_handlers -->|"updates progress"| node_progress_state
node_pipeline_handlers -->|"forwards progress"| node_content_bridge
node_popup -->|"reads download state"| node_progress_state
node_popup -->|"shows history"| node_recent
node_user -->|"selects playlist"| node_playlist_ui
node_playlist_ui -->|"queues downloads"| node_content_bridge
node_user -->|"configures options"| node_settings_ui

click node_yt_entry "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/index.ts"
click node_download_ui "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/components/download-options-panel/DownloadOptionsPanel.svelte"
click node_request_builder "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/video/download-request-builder.ts"
click node_youtube_api "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/video/youtube-api.ts"
click node_content_bridge "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube.content/handlers/background.ts"
click node_background_main "https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/main.ts"
click node_download_handlers "https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/handlers/download-handlers.ts"
click node_pipeline_handlers "https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/handlers/pipeline-handlers.ts"
click node_download_worker "https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/download-worker/main.ts"
click node_stream_downloaders "https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/download/sabr-downloader.ts"
click node_offscreen "https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/offscreen/main.ts"
click node_pipeline "https://github.com/avi12/youtube-downloader/blob/main/src/lib/download-pipeline/index.ts"
click node_mux_worker "https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/mux-worker/index.ts"
click node_opfs "https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/mux-worker/opfs-output-fs.ts"
click node_progress_state "https://github.com/avi12/youtube-downloader/blob/main/src/lib/storage/storage.ts"
click node_popup "https://github.com/avi12/youtube-downloader/blob/main/src/layers/popup/entrypoints/popup/App.svelte"
click node_recent "https://github.com/avi12/youtube-downloader/blob/main/src/lib/storage/recent-downloads-db.ts"
click node_playlist_ui "https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/components/playlist-downloader/PlaylistDownloader.svelte"
click node_settings_ui "https://github.com/avi12/youtube-downloader/blob/main/src/layers/popup/entrypoints/popup/settings/SettingsTab.svelte"

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_yt_entry,node_download_ui,node_request_builder,node_youtube_api,node_content_bridge,node_playlist_ui,node_user,node_browser_downloads toneBlue
class node_background_main,node_download_handlers,node_pipeline_handlers,node_download_worker,node_stream_downloaders,node_progress_state toneAmber
class node_offscreen,node_pipeline,node_mux_worker,node_opfs toneMint
class node_popup,node_recent,node_settings_ui toneRose
class node_yt_page,node_youtube_service toneIndigo
```

## Components

### YouTube interface

- [YouTube content entry](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/index.ts): `src/layers/youtube/entrypoints/youtube-main.content/index.ts`
- [Download controls](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/components/download-options-panel/DownloadOptionsPanel.svelte): `src/layers/youtube/components/download-options-panel/DownloadOptionsPanel.svelte`
- [Request builder](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/video/download-request-builder.ts): `src/layers/youtube/entrypoints/youtube-main.content/video/download-request-builder.ts`
- [YouTube stream metadata](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube-main.content/video/youtube-api.ts): `src/layers/youtube/entrypoints/youtube-main.content/video/youtube-api.ts`
- [Content message handlers](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/entrypoints/youtube.content/handlers/background.ts): `src/layers/youtube/entrypoints/youtube.content/handlers/background.ts`
- [Playlist downloader](https://github.com/avi12/youtube-downloader/blob/main/src/layers/youtube/components/playlist-downloader/PlaylistDownloader.svelte): `src/layers/youtube/components/playlist-downloader/PlaylistDownloader.svelte`

### Download coordination

- [Background entry](https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/main.ts): `src/layers/background/main.ts`
- [Download handlers](https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/handlers/download-handlers.ts): `src/layers/background/handlers/download-handlers.ts`
- [Pipeline handlers](https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/handlers/pipeline-handlers.ts): `src/layers/background/handlers/pipeline-handlers.ts`
- [Download worker](https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/download-worker/main.ts): `src/layers/processing/entrypoints/download-worker/main.ts`
- [SABR and CDN retrieval](https://github.com/avi12/youtube-downloader/blob/main/src/layers/background/download/sabr-downloader.ts): `src/layers/background/download/sabr-downloader.ts`
- [Progress and queue state](https://github.com/avi12/youtube-downloader/blob/main/src/lib/storage/storage.ts): `src/lib/storage/storage.ts`

### Media processing

- [Offscreen processing host](https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/offscreen/main.ts): `src/layers/processing/entrypoints/offscreen/main.ts`
- [Mux and output pipeline](https://github.com/avi12/youtube-downloader/blob/main/src/lib/download-pipeline/index.ts): `src/lib/download-pipeline/index.ts`
- [FFmpeg mux worker](https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/mux-worker/index.ts): `src/layers/processing/entrypoints/mux-worker/index.ts`
- [Temporary media files](https://github.com/avi12/youtube-downloader/blob/main/src/layers/processing/entrypoints/mux-worker/opfs-output-fs.ts): `src/layers/processing/entrypoints/mux-worker/opfs-output-fs.ts`

### Download management

- [Popup download manager](https://github.com/avi12/youtube-downloader/blob/main/src/layers/popup/entrypoints/popup/App.svelte): `src/layers/popup/entrypoints/popup/App.svelte`
- [Recent downloads](https://github.com/avi12/youtube-downloader/blob/main/src/lib/storage/recent-downloads-db.ts): `src/lib/storage/recent-downloads-db.ts`
- [Download settings](https://github.com/avi12/youtube-downloader/blob/main/src/layers/popup/entrypoints/popup/settings/SettingsTab.svelte): `src/layers/popup/entrypoints/popup/settings/SettingsTab.svelte`

### Other components

- **User**
- **YouTube page**
- **YouTube services**
- **Browser download manager**

## Connections

- User → Download controls: selects format
- YouTube page → YouTube content entry: hosts controls
- YouTube content entry → Download controls: renders
- Download controls → Request builder: builds request
- YouTube stream metadata → YouTube services: fetches metadata
- Request builder → Content message handlers: sends request
- Content message handlers → Download handlers: messages
- Background entry → Download handlers: registers
- Background entry → Pipeline handlers: registers
- Download handlers → Download worker: starts download
- Download worker → SABR and CDN retrieval: retrieves streams
- SABR and CDN retrieval → YouTube services: requests media
- Download worker → Offscreen processing host: transfers chunks
- Offscreen processing host → Mux and output pipeline: dispatches processing
- Mux and output pipeline → FFmpeg mux worker: runs mux jobs
- FFmpeg mux worker → Temporary media files: writes output
- Mux and output pipeline → Browser download manager: saves media
- Pipeline handlers → Progress and queue state: updates progress
- Pipeline handlers → Content message handlers: forwards progress
- Popup download manager → Progress and queue state: reads download state
- Popup download manager → Recent downloads: shows history
- User → Playlist downloader: selects playlist
- Playlist downloader → Content message handlers: queues downloads
- User → Download settings: configures options