# oncename/pytube architecture

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

- Interactive diagram: https://gitdiagram.com/oncename/pytube
- Repository: https://github.com/oncename/pytube

## Overview

pytube is a Python library and CLI for retrieving YouTube video information and downloading media. The main workflow accepts a video URL, fetches and extracts its details and available streams, lets the caller select a stream, then downloads it; users can also obtain captions or work with playlists, channels, and search. The graph separates public entry points, YouTube-facing retrieval, parsing and stream handling, and collection features. Some connections are based on the SOURCE INDEX or README rather than fully sampled implementations, so uncertain links are omitted.

Main entry points: [`pytube/__main__.py`](https://github.com/oncename/pytube/blob/master/pytube/__main__.py) (YouTube interface), [`pytube/streams.py`](https://github.com/oncename/pytube/blob/master/pytube/streams.py) (Stream handling), [`pytube/extract.py`](https://github.com/oncename/pytube/blob/master/pytube/extract.py) (Data extraction), [`pytube/request.py`](https://github.com/oncename/pytube/blob/master/pytube/request.py) (HTTP requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_youtube["YouTube interface<br/>[__main__.py]"]
end

subgraph group_video["Video retrieval"]
  node_http["HTTP requests<br/>[request.py]"]
  node_innertube["Innertube API<br/>[innertube.py]"]
end

subgraph group_media["Media processing"]
  node_extract["Data extraction<br/>[extract.py]"]
  node_parser["HTML parser<br/>[parser.py]"]
  node_cipher["Signature cipher<br/>[cipher.py]"]
  node_streams["Stream handling<br/>[streams.py]"]
  node_streamquery["Stream queries<br/>[query.py]"]
  node_captions["Caption tracks<br/>[captions.py]"]
  node_metadata["Video metadata<br/>[metadata.py]"]
  node_itags["Format definitions<br/>[itags.py]"]
  node_state["Shared state<br/>[monostate.py]"]
  node_helpers["Utilities<br/>[helpers.py]"]
  node_errors["Exceptions<br/>[exceptions.py]"]
end

subgraph group_discovery["Discovery features"]
  node_playlist["Playlist access<br/>[playlist.py]"]
  node_channel["Channel access<br/>[channel.py]"]
  node_search["YouTube search<br/>[search.py]"]
end

node_user(("Library user"))
node_youtube_service(("YouTube"))

node_user -->|"provides URL"| node_youtube
node_user -->|"runs command"| node_cli
node_cli -->|"uses library"| node_youtube
node_youtube -->|"fetches pages"| node_http
node_youtube -->|"requests player data"| node_innertube
node_youtube -->|"extracts details"| node_extract
node_youtube -->|"exposes streams"| node_streams
node_youtube -->|"exposes captions"| node_captions
node_streams -->|"downloads media"| node_http
node_streams -->|"uses format data"| node_extract
node_streams -->|"looks up formats"| node_itags
node_streams -->|"shares state"| node_state
node_streams -->|"uses utilities"| node_helpers
node_streamquery -->|"queries stream objects"| node_streams
node_captions -->|"fetches captions"| node_http
node_captions -->|"uses utilities"| node_helpers
node_extract -->|"parses page data"| node_parser
node_extract -->|"deciphers signatures"| node_cipher
node_extract -->|"builds metadata"| node_metadata
node_innertube -->|"sends API requests"| node_http
node_playlist -->|"fetches playlist pages"| node_http
node_playlist -->|"extracts page data"| node_extract
node_playlist -->|"creates video objects"| node_youtube
node_channel -->|"fetches channel data"| node_http
node_channel -->|"extracts channel data"| node_extract
node_search -->|"fetches search results"| node_innertube
node_search -->|"creates video objects"| node_youtube
node_http -->|"requests content"| node_youtube_service
node_youtube -->|"raises access errors"| node_errors

click node_cli "https://github.com/oncename/pytube/blob/master/pytube/cli.py"
click node_youtube "https://github.com/oncename/pytube/blob/master/pytube/__main__.py"
click node_http "https://github.com/oncename/pytube/blob/master/pytube/request.py"
click node_innertube "https://github.com/oncename/pytube/blob/master/pytube/innertube.py"
click node_extract "https://github.com/oncename/pytube/blob/master/pytube/extract.py"
click node_parser "https://github.com/oncename/pytube/blob/master/pytube/parser.py"
click node_cipher "https://github.com/oncename/pytube/blob/master/pytube/cipher.py"
click node_streams "https://github.com/oncename/pytube/blob/master/pytube/streams.py"
click node_streamquery "https://github.com/oncename/pytube/blob/master/pytube/query.py"
click node_captions "https://github.com/oncename/pytube/blob/master/pytube/captions.py"
click node_metadata "https://github.com/oncename/pytube/blob/master/pytube/metadata.py"
click node_itags "https://github.com/oncename/pytube/blob/master/pytube/itags.py"
click node_state "https://github.com/oncename/pytube/blob/master/pytube/monostate.py"
click node_helpers "https://github.com/oncename/pytube/blob/master/pytube/helpers.py"
click node_playlist "https://github.com/oncename/pytube/blob/master/pytube/contrib/playlist.py"
click node_channel "https://github.com/oncename/pytube/blob/master/pytube/contrib/channel.py"
click node_search "https://github.com/oncename/pytube/blob/master/pytube/contrib/search.py"
click node_errors "https://github.com/oncename/pytube/blob/master/pytube/exceptions.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_cli,node_youtube,node_user toneBlue
class node_http,node_innertube toneAmber
class node_extract,node_parser,node_cipher,node_streams,node_streamquery,node_captions,node_metadata,node_itags,node_state,node_helpers,node_errors toneMint
class node_playlist,node_channel,node_search toneRose
class node_youtube_service toneIndigo
```

## Components

### User entry points

- [CLI](https://github.com/oncename/pytube/blob/master/pytube/cli.py): `pytube/cli.py`
- [YouTube interface](https://github.com/oncename/pytube/blob/master/pytube/__main__.py): `pytube/__main__.py`

### Video retrieval

- [HTTP requests](https://github.com/oncename/pytube/blob/master/pytube/request.py): `pytube/request.py`
- [Innertube API](https://github.com/oncename/pytube/blob/master/pytube/innertube.py): `pytube/innertube.py`

### Media processing

- [Data extraction](https://github.com/oncename/pytube/blob/master/pytube/extract.py): `pytube/extract.py`
- [HTML parser](https://github.com/oncename/pytube/blob/master/pytube/parser.py): `pytube/parser.py`
- [Signature cipher](https://github.com/oncename/pytube/blob/master/pytube/cipher.py): `pytube/cipher.py`
- [Stream handling](https://github.com/oncename/pytube/blob/master/pytube/streams.py): `pytube/streams.py`
- [Stream queries](https://github.com/oncename/pytube/blob/master/pytube/query.py): `pytube/query.py`
- [Caption tracks](https://github.com/oncename/pytube/blob/master/pytube/captions.py): `pytube/captions.py`
- [Video metadata](https://github.com/oncename/pytube/blob/master/pytube/metadata.py): `pytube/metadata.py`
- [Format definitions](https://github.com/oncename/pytube/blob/master/pytube/itags.py): `pytube/itags.py`
- [Shared state](https://github.com/oncename/pytube/blob/master/pytube/monostate.py): `pytube/monostate.py`
- [Utilities](https://github.com/oncename/pytube/blob/master/pytube/helpers.py): `pytube/helpers.py`
- [Exceptions](https://github.com/oncename/pytube/blob/master/pytube/exceptions.py): `pytube/exceptions.py`

### Discovery features

- [Playlist access](https://github.com/oncename/pytube/blob/master/pytube/contrib/playlist.py): `pytube/contrib/playlist.py`
- [Channel access](https://github.com/oncename/pytube/blob/master/pytube/contrib/channel.py): `pytube/contrib/channel.py`
- [YouTube search](https://github.com/oncename/pytube/blob/master/pytube/contrib/search.py): `pytube/contrib/search.py`

### Other components

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

## Connections

- Library user → YouTube interface: provides URL (evidence: `README.md`)
- Library user → CLI: runs command (evidence: `README.md`)
- CLI → YouTube interface: uses library (evidence: `pytube/cli.py`)
- YouTube interface → HTTP requests: fetches pages (evidence: `pytube/__main__.py`)
- YouTube interface → Innertube API: requests player data (evidence: `pytube/__main__.py`)
- YouTube interface → Data extraction: extracts details (evidence: `pytube/__main__.py`)
- YouTube interface → Stream handling: exposes streams (evidence: `README.md`)
- YouTube interface → Caption tracks: exposes captions (evidence: `pytube/__init__.py`)
- Stream handling → HTTP requests: downloads media (evidence: `pytube/streams.py`)
- Stream handling → Data extraction: uses format data (evidence: `pytube/streams.py`)
- Stream handling → Format definitions: looks up formats (evidence: `pytube/streams.py`)
- Stream handling → Shared state: shares state (evidence: `pytube/streams.py`)
- Stream handling → Utilities: uses utilities (evidence: `pytube/streams.py`)
- Stream queries → Stream handling: queries stream objects (evidence: `pytube/query.py`)
- Caption tracks → HTTP requests: fetches captions (evidence: `pytube/captions.py`)
- Caption tracks → Utilities: uses utilities (evidence: `pytube/captions.py`)
- Data extraction → HTML parser: parses page data (evidence: `pytube/extract.py`)
- Data extraction → Signature cipher: deciphers signatures (evidence: `pytube/extract.py`)
- Data extraction → Video metadata: builds metadata (evidence: `pytube/extract.py`)
- Innertube API → HTTP requests: sends API requests (evidence: `pytube/innertube.py`)
- Playlist access → HTTP requests: fetches playlist pages (evidence: `pytube/contrib/playlist.py`)
- Playlist access → Data extraction: extracts page data (evidence: `pytube/contrib/playlist.py`)
- Playlist access → YouTube interface: creates video objects (evidence: `pytube/contrib/playlist.py`)
- Channel access → HTTP requests: fetches channel data (evidence: `pytube/contrib/channel.py`)
- Channel access → Data extraction: extracts channel data (evidence: `pytube/contrib/channel.py`)
- YouTube search → Innertube API: fetches search results (evidence: `pytube/contrib/search.py`)
- YouTube search → YouTube interface: creates video objects (evidence: `pytube/contrib/search.py`)
- HTTP requests → YouTube: requests content (evidence: `README.md`)
- YouTube interface → Exceptions: raises access errors (evidence: `pytube/__main__.py`)
