# logosww/hls-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/logosww/hls-downloader
- Repository: https://github.com/logosww/hls-downloader
- Video tour (about a minute): https://gitdiagram.com/logosww/hls-downloader/video

## Overview

HLS Downloader parses playlists, retrieves media segments, and produces downloadable MP4 files or streamed fMP4. Its shared HlsDownloader API delegates to either a browser or Node adapter; the browser path uses WebAssembly transmuxing and optional WebCodecs transcoding, while Node uses a Rust native implementation. The repository also includes browser and Bun applications. Relationships among major stages are documented in the README; unsampled implementation details are represented only where supported by the source index or documentation.

Main entry points: [`packages/core/src/index.ts`](https://github.com/logosww/hls-downloader/blob/main/packages/core/src/index.ts) (Downloader API), [`packages/adapters/src/browser/index.ts`](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/index.ts) (Browser Adapter), [`packages/adapters/src/node/index.ts`](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/index.ts) (Node Adapter), [`packages/adapters/src/node/crates/napi/src/lib.rs`](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/napi/src/lib.rs) (Native Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Shared API"]
  node_api["Downloader API<br/>[index.ts]"]
  node_shared["Shared Types<br/>[types.ts]"]
  node_errors["Error Model<br/>[errors.ts]"]
  node_cache["Playlist Cache<br/>[parse-hls-cache.ts]"]
end

subgraph group_browser["Browser Adapter"]
  node_browser_adapter["Browser Adapter<br/>[index.ts]"]
  node_browser_retry["Retry Requests<br/>[retry.ts]"]
  node_browser_poster["Poster Extraction<br/>[poster.ts]"]
  node_browser_transcode["WebCodecs Transcode<br/>[mediabunny.ts]"]
  node_browser_writable["Stream Output<br/>[writable.ts]"]
  node_wasm["WASM Bridge<br/>[wasm.ts]"]
end

subgraph group_node["Node Adapter"]
  node_node_adapter["Node Adapter<br/>[index.ts]"]
  node_node_native["Native Bridge<br/>[lib.rs]"]
  node_node_hls["Native Playlist<br/>[hls.rs]"]
  node_node_download["Native Download<br/>[download.rs]"]
end

subgraph group_apps["Applications"]
  node_web_ui["Web Interface<br/>[page.tsx]"]
  node_web_download["Browser Download Manager"]
  node_web_preview["Stream Preview"]
  node_bun_routes["Bun HTTP Routes<br/>[app.ts]"]
  node_bun_tasks["Download Tasks<br/>[task-manager.ts]"]
  node_file_output["File Output<br/>[file-output.ts]"]
end

subgraph group_media["Media Processing"]
  node_wasm_transmux["WASM Transmux<br/>[lib.rs]"]
  node_transmux["Transmux Engine"]
  node_transcode_options["Transcode Presets<br/>[transcode.ts]"]
end

node_user(("Caller"))

node_user -->|"calls"| node_api
node_api -->|"selects adapter"| node_browser_adapter
node_api -->|"selects adapter"| node_node_adapter
node_api -->|"uses types"| node_shared
node_api -.->|"caches playlists"| node_cache
node_browser_adapter -->|"retries fetches"| node_browser_retry
node_browser_adapter -->|"extracts poster"| node_browser_poster
node_browser_adapter -->|"transcodes media"| node_browser_transcode
node_browser_adapter -->|"resolves playlist"| node_browser_writable
node_browser_adapter -->|"transmuxes media"| node_wasm
node_wasm -.->|"calls WASM"| node_wasm_transmux
node_wasm_transmux -.->|"invokes engine"| node_transmux
node_transmux -.->|"reports media"| node_shared
node_browser_transcode -->|"uses options"| node_transcode_options
node_node_adapter -.->|"calls native module"| node_node_native
node_node_native -.->|"dispatches playlist"| node_node_hls
node_node_native -.->|"dispatches download"| node_node_download
node_node_download -->|"uses playlist"| node_node_hls
node_node_adapter -.->|"extracts poster"| node_browser_poster
node_web_ui -.->|"manages downloads"| node_web_download
node_web_download -->|"downloads via"| node_api
node_web_download -->|"saves files"| node_file_output
node_web_preview -->|"streams preview"| node_api
node_bun_routes -->|"routes tasks"| node_bun_tasks
node_bun_tasks -.->|"downloads via"| node_api
node_bun_tasks -->|"gets poster"| node_api

click node_api "https://github.com/logosww/hls-downloader/blob/main/packages/core/src/index.ts"
click node_shared "https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/types.ts"
click node_errors "https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/errors.ts"
click node_cache "https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/parse-hls-cache.ts"
click node_browser_adapter "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/index.ts"
click node_browser_retry "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/retry.ts"
click node_browser_poster "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/poster.ts"
click node_browser_transcode "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/mediabunny.ts"
click node_browser_writable "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/writable.ts"
click node_wasm "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/wasm.ts"
click node_wasm_transmux "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/crates/hls-transmux-wasm/src/lib.rs"
click node_transmux "https://github.com/logosww/hls-downloader/tree/main/packages/adapters/src/browser/crates/hls-transmux/src"
click node_transcode_options "https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/transcode.ts"
click node_node_adapter "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/index.ts"
click node_node_native "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/napi/src/lib.rs"
click node_node_hls "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/core/src/hls.rs"
click node_node_download "https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/core/src/download.rs"
click node_web_ui "https://github.com/logosww/hls-downloader/blob/main/packages/app/web/app/page.tsx"
click node_web_download "https://github.com/logosww/hls-downloader/blob/main/packages/app/web/hooks/use-download-manager.ts"
click node_web_preview "https://github.com/logosww/hls-downloader/blob/main/packages/app/web/hooks/use-stream-preview.ts"
click node_bun_routes "https://github.com/logosww/hls-downloader/blob/main/packages/app/bun/app.ts"
click node_bun_tasks "https://github.com/logosww/hls-downloader/blob/main/packages/app/bun/task-manager.ts"
click node_file_output "https://github.com/logosww/hls-downloader/blob/main/packages/app/web/lib/file-output.ts"

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_api,node_shared,node_errors,node_cache toneBlue
class node_browser_adapter,node_browser_retry,node_browser_poster,node_browser_transcode,node_browser_writable,node_wasm toneAmber
class node_node_adapter,node_node_native,node_node_hls,node_node_download toneMint
class node_web_ui,node_web_download,node_web_preview,node_bun_routes,node_bun_tasks,node_file_output toneRose
class node_wasm_transmux,node_transmux,node_transcode_options,node_user toneIndigo
```

## Components

### Shared API

- [Downloader API](https://github.com/logosww/hls-downloader/blob/main/packages/core/src/index.ts): `packages/core/src/index.ts`
- [Shared Types](https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/types.ts): `packages/shared/src/types.ts`
- [Error Model](https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/errors.ts): `packages/shared/src/errors.ts`
- [Playlist Cache](https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/parse-hls-cache.ts): `packages/shared/src/parse-hls-cache.ts`

### Browser Adapter

- [Browser Adapter](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/index.ts): `packages/adapters/src/browser/index.ts`
- [Retry Requests](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/retry.ts): `packages/adapters/src/browser/retry.ts`
- [Poster Extraction](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/poster.ts): `packages/adapters/src/browser/poster.ts`
- [WebCodecs Transcode](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/mediabunny.ts): `packages/adapters/src/browser/mediabunny.ts`
- [Stream Output](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/writable.ts): `packages/adapters/src/browser/writable.ts`
- [WASM Bridge](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/wasm.ts): `packages/adapters/src/browser/wasm.ts`

### Node Adapter

- [Node Adapter](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/index.ts): `packages/adapters/src/node/index.ts`
- [Native Bridge](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/napi/src/lib.rs): `packages/adapters/src/node/crates/napi/src/lib.rs`
- [Native Playlist](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/core/src/hls.rs): `packages/adapters/src/node/crates/core/src/hls.rs`
- [Native Download](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/node/crates/core/src/download.rs): `packages/adapters/src/node/crates/core/src/download.rs`

### Applications

- [Web Interface](https://github.com/logosww/hls-downloader/blob/main/packages/app/web/app/page.tsx): `packages/app/web/app/page.tsx`
- [Browser Download Manager](https://github.com/logosww/hls-downloader/blob/main/packages/app/web/hooks/use-download-manager.ts): `packages/app/web/hooks/use-download-manager.ts`
- [Stream Preview](https://github.com/logosww/hls-downloader/blob/main/packages/app/web/hooks/use-stream-preview.ts): `packages/app/web/hooks/use-stream-preview.ts`
- [Bun HTTP Routes](https://github.com/logosww/hls-downloader/blob/main/packages/app/bun/app.ts): `packages/app/bun/app.ts`
- [Download Tasks](https://github.com/logosww/hls-downloader/blob/main/packages/app/bun/task-manager.ts): `packages/app/bun/task-manager.ts`
- [File Output](https://github.com/logosww/hls-downloader/blob/main/packages/app/web/lib/file-output.ts): `packages/app/web/lib/file-output.ts`

### Media Processing

- [WASM Transmux](https://github.com/logosww/hls-downloader/blob/main/packages/adapters/src/browser/crates/hls-transmux-wasm/src/lib.rs): `packages/adapters/src/browser/crates/hls-transmux-wasm/src/lib.rs`
- [Transmux Engine](https://github.com/logosww/hls-downloader/tree/main/packages/adapters/src/browser/crates/hls-transmux/src): `packages/adapters/src/browser/crates/hls-transmux/src`
- [Transcode Presets](https://github.com/logosww/hls-downloader/blob/main/packages/shared/src/transcode.ts): `packages/shared/src/transcode.ts`

### Other components

- **Caller**

## Connections

- Caller → Downloader API: calls
- Downloader API → Browser Adapter: selects adapter
- Downloader API → Node Adapter: selects adapter
- Downloader API → Shared Types: uses types (evidence: `packages/core/src/index.ts`)
- Downloader API → Playlist Cache: caches playlists
- Browser Adapter → Retry Requests: retries fetches (evidence: `packages/adapters/src/browser/index.ts`)
- Browser Adapter → Poster Extraction: extracts poster (evidence: `packages/adapters/src/browser/index.ts`)
- Browser Adapter → WebCodecs Transcode: transcodes media (evidence: `packages/adapters/src/browser/index.ts`)
- Browser Adapter → Stream Output: resolves playlist (evidence: `packages/adapters/src/browser/index.ts`)
- Browser Adapter → WASM Bridge: transmuxes media (evidence: `packages/adapters/src/browser/index.ts`)
- WASM Bridge → WASM Transmux: calls WASM
- WASM Transmux → Transmux Engine: invokes engine
- Transmux Engine → Shared Types: reports media
- WebCodecs Transcode → Transcode Presets: uses options (evidence: `packages/adapters/src/browser/mediabunny.ts`)
- Node Adapter → Native Bridge: calls native module
- Native Bridge → Native Playlist: dispatches playlist
- Native Bridge → Native Download: dispatches download
- Native Download → Native Playlist: uses playlist (evidence: `packages/adapters/src/node/crates/core/src/download.rs`)
- Node Adapter → Poster Extraction: extracts poster
- Web Interface → Browser Download Manager: manages downloads
- Browser Download Manager → Downloader API: downloads via (evidence: `packages/app/web/hooks/use-download-manager.ts`)
- Browser Download Manager → File Output: saves files (evidence: `packages/app/web/hooks/use-download-manager.ts`)
- Stream Preview → Downloader API: streams preview (evidence: `packages/app/web/hooks/use-stream-preview.ts`)
- Bun HTTP Routes → Download Tasks: routes tasks (evidence: `packages/app/bun/app.ts`)
- Download Tasks → Downloader API: downloads via
- Download Tasks → Downloader API: gets poster (evidence: `packages/app/bun/task-manager.ts`)