# juanbindez/pytubefix architecture

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

- Interactive diagram: https://gitdiagram.com/juanbindez/pytubefix
- Repository: https://github.com/juanbindez/pytubefix

## Overview

PyTubeFix is a Python library for finding YouTube media, inspecting its metadata and available formats, and downloading video or audio. The main workflow starts with a video URL or ID, retrieves and parses YouTube data, exposes selectable streams, then fetches and saves the chosen media. Separate branches cover search, playlists and channels, captions and other video details, asynchronous access, and SABR streaming. The README documents these capabilities; several internal links below are based on module roles and documented usage rather than sampled call sites.

Main entry points: [`pytubefix/__init__.py`](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/__init__.py) (YouTube video), [`pytubefix/request.py`](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/request.py) (HTTP requests), [`pytubefix/streams.py`](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/streams.py) (Media streams), [`pytubefix/async_youtube.py`](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/async_youtube.py) (Async video)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User access"]
  node_youtube["YouTube video<br/>[__init__.py]"]
  node_async_youtube["Async video<br/>[async_youtube.py]"]
end

subgraph group_discovery["YouTube discovery"]
  node_search["Video search<br/>[search.py]"]
  node_channel["Channel listing<br/>[channel.py]"]
  node_playlist["Playlist listing<br/>[playlist.py]"]
  node_innertube["Innertube client<br/>[innertube.py]"]
  node_request["HTTP requests<br/>[request.py]"]
  node_extract["Page extraction<br/>[extract.py]"]
  node_parser["Response parsing<br/>[parser.py]"]
end

subgraph group_media["Media retrieval"]
  node_stream_query["Stream selection<br/>[query.py]"]
  node_streams["Media streams<br/>[streams.py]"]
  node_cipher["URL deciphering<br/>[cipher.py]"]
  node_filesystem["File output<br/>[file_system.py]"]
end

subgraph group_details["Video details"]
  node_captions["Caption tracks<br/>[captions.py]"]
  node_metadata["Video metadata<br/>[metadata.py]"]
  node_chapters["Chapters<br/>[chapters.py]"]
  node_keymoments["Key moments<br/>[keymoments.py]"]
end

subgraph group_protocol["Protocol support"]
  node_async_http["Async HTTP"]
  node_sabr["SABR streaming"]
  node_botguard["BotGuard tokens<br/>[bot_guard.py]"]
  node_signature_vm["Signature runtime<br/>[node_runner.py]"]
end

node_developer(("Library user"))
node_youtube_api["YouTube API"]

node_developer -->|"opens video"| node_youtube
node_developer -->|"opens asynchronously"| node_async_youtube
node_developer -->|"searches"| node_search
node_developer -->|"opens channel"| node_channel
node_developer -->|"opens playlist"| node_playlist
node_youtube -->|"requests details"| node_innertube
node_youtube -->|"extracts video data"| node_extract
node_innertube -->|"sends requests"| node_request
node_request -->|"fetches data"| node_youtube_api
node_extract -->|"parses page data"| node_parser
node_youtube -->|"exposes streams"| node_stream_query
node_stream_query -->|"selects format"| node_streams
node_streams -->|"deciphers URLs"| node_cipher
node_streams -->|"fetches media"| node_request
node_streams -->|"writes download"| node_filesystem
node_youtube -->|"provides captions"| node_captions
node_youtube -->|"provides metadata"| node_metadata
node_youtube -->|"provides chapters"| node_chapters
node_youtube -->|"provides key moments"| node_keymoments
node_search -->|"queries YouTube"| node_innertube
node_channel -->|"fetches channel"| node_request
node_playlist -->|"fetches playlist"| node_request
node_async_youtube -->|"requests asynchronously"| node_async_http
node_async_http -->|"fetches data"| node_youtube_api
node_async_youtube -.->|"uses streaming"| node_sabr
node_sabr -->|"requests media"| node_request
node_youtube -.->|"may generate token"| node_botguard
node_streams -.->|"resolves signatures"| node_signature_vm

click node_youtube "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/__init__.py"
click node_async_youtube "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/async_youtube.py"
click node_search "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/search.py"
click node_channel "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/channel.py"
click node_playlist "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/playlist.py"
click node_innertube "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/innertube.py"
click node_request "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/request.py"
click node_extract "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/extract.py"
click node_parser "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/parser.py"
click node_stream_query "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/query.py"
click node_streams "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/streams.py"
click node_cipher "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/cipher.py"
click node_filesystem "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/file_system.py"
click node_captions "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/captions.py"
click node_metadata "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/metadata.py"
click node_chapters "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/chapters.py"
click node_keymoments "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/keymoments.py"
click node_async_http "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/async_http_client.py"
click node_sabr "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/sabr/core/server_abr_stream.py"
click node_botguard "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/botGuard/bot_guard.py"
click node_signature_vm "https://github.com/juanbindez/pytubefix/blob/main/pytubefix/sig_nsig/node_runner.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_youtube,node_async_youtube,node_developer toneBlue
class node_search,node_channel,node_playlist,node_innertube,node_request,node_extract,node_parser toneAmber
class node_stream_query,node_streams,node_cipher,node_filesystem,node_youtube_api toneMint
class node_captions,node_metadata,node_chapters,node_keymoments toneRose
class node_async_http,node_sabr,node_botguard,node_signature_vm toneIndigo
```

## Components

### User access

- [YouTube video](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/__init__.py): `pytubefix/__init__.py`
- [Async video](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/async_youtube.py): `pytubefix/async_youtube.py`

### YouTube discovery

- [Video search](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/search.py): `pytubefix/contrib/search.py`
- [Channel listing](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/channel.py): `pytubefix/contrib/channel.py`
- [Playlist listing](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/contrib/playlist.py): `pytubefix/contrib/playlist.py`
- [Innertube client](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/innertube.py): `pytubefix/innertube.py`
- [HTTP requests](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/request.py): `pytubefix/request.py`
- [Page extraction](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/extract.py): `pytubefix/extract.py`
- [Response parsing](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/parser.py): `pytubefix/parser.py`

### Media retrieval

- [Stream selection](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/query.py): `pytubefix/query.py`
- [Media streams](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/streams.py): `pytubefix/streams.py`
- [URL deciphering](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/cipher.py): `pytubefix/cipher.py`
- [File output](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/file_system.py): `pytubefix/file_system.py`

### Video details

- [Caption tracks](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/captions.py): `pytubefix/captions.py`
- [Video metadata](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/metadata.py): `pytubefix/metadata.py`
- [Chapters](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/chapters.py): `pytubefix/chapters.py`
- [Key moments](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/keymoments.py): `pytubefix/keymoments.py`

### Protocol support

- [Async HTTP](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/async_http_client.py): `pytubefix/async_http_client.py`
- [SABR streaming](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/sabr/core/server_abr_stream.py): `pytubefix/sabr/core/server_abr_stream.py`
- [BotGuard tokens](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/botGuard/bot_guard.py): `pytubefix/botGuard/bot_guard.py`
- [Signature runtime](https://github.com/juanbindez/pytubefix/blob/main/pytubefix/sig_nsig/node_runner.py): `pytubefix/sig_nsig/node_runner.py`

### Other components

- **Library user**
- **YouTube API**

## Connections

- Library user → YouTube video: opens video
- Library user → Async video: opens asynchronously
- Library user → Video search: searches
- Library user → Channel listing: opens channel
- Library user → Playlist listing: opens playlist
- YouTube video → Innertube client: requests details
- YouTube video → Page extraction: extracts video data
- Innertube client → HTTP requests: sends requests
- HTTP requests → YouTube API: fetches data
- Page extraction → Response parsing: parses page data
- YouTube video → Stream selection: exposes streams
- Stream selection → Media streams: selects format
- Media streams → URL deciphering: deciphers URLs
- Media streams → HTTP requests: fetches media
- Media streams → File output: writes download
- YouTube video → Caption tracks: provides captions
- YouTube video → Video metadata: provides metadata
- YouTube video → Chapters: provides chapters
- YouTube video → Key moments: provides key moments
- Video search → Innertube client: queries YouTube
- Channel listing → HTTP requests: fetches channel
- Playlist listing → HTTP requests: fetches playlist
- Async video → Async HTTP: requests asynchronously
- Async HTTP → YouTube API: fetches data
- Async video → SABR streaming: uses streaming
- SABR streaming → HTTP requests: requests media
- YouTube video → BotGuard tokens: may generate token
- Media streams → Signature runtime: resolves signatures