aytube 🚀
Ultra-fast YouTube Video & Audio Downloader and Direct Stream Extractor in Python.
A modern, lightweight alternative to pytube and yt-dlp that runs cleanly without HTTP 403 Forbidden errors, without bloated dependencies, and with full Netscape cookie support.
⚡ Why AyTube? (Comparison)
| Feature | aytube |
pytube |
yt-dlp |
|---|---|---|---|
| Working in 2025 / 2026 | ✅ Yes | ❌ Broken (403 Forbidden) |
⚠️ Requires external challenge solvers |
| Package Size | < 60 KB (Zero bloat) | ~100 KB | ~15+ MB |
| Python Dependencies | 0 (Standard library only) | 0 | Multiple |
| Direct Stream Extraction | ✅ Instant Google Video CDN URLs | ❌ Often 403 | ✅ Yes |
| 4K (2160p), 1080p, 60fps | ✅ All resolutions | ❌ Restricted | ✅ Yes |
| Audio Extraction (Opus / AAC) | ✅ High-bitrate streams | ⚠️ Inconsistent | ✅ Yes |
| Cookie Auto-Discovery | ✅ Automatic (cookies.txt, cookie.txt) |
❌ No | ✅ Manual flags |
| Byte Range Stream Verification | ✅ Built-in Range check | ❌ No | ❌ No |
| Resumable Downloads & Muxing | ✅ Built-in (ffmpeg auto-merge) |
⚠️ Basic | ✅ Yes |
| CLI with 13 Subcommands | ✅ Fast & Scriptable | ⚠️ Minimal | ✅ Yes |
📦 Installation
Install aytube from PyPI:
pip install aytube
Or install the latest version directly from source:
git clone https://github.com/Sinchu-xD/AyTube.git
cd AyTube
pip install -e .
Requirements: Python 3.10+ (Standard library only).
🚀 Quick Start (Python)
1. Extract Direct Stream URL
from aytube import get_stream_url
# Extract highest available quality (e.g. 4K / 1080p)
result = get_stream_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print("Playable URL:", result.url) # Direct Google Video CDN URL
print("Resolution: ", result.quality) # e.g., "2160p" or "1080p"
print("File Size: ", result.size) # Size in bytes
print("Title: ", result.title) # Video title
2. Video Quality Selection (1080p, 720p, 480p, 360p)
from aytube import get_stream_url
# Specific resolution
res_1080p = get_stream_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ", quality="1080p")
res_720p = get_stream_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ", quality="720p")
3. Extract High-Bitrate Audio Stream (Opus / AAC)
from aytube import get_stream_url
audio = get_stream_url("https://www.youtube.com/watch?v=dQw4w9WgXcQ", audio_only=True, quality="high")
print(f"Codec: {audio.audio_codec} | Quality: {audio.quality} | URL: {audio.url}")
4. Download Video or Audio (with Auto FFmpeg Muxing)
When downloading 1080p or 4K streams that have separate video and audio tracks, aytube automatically merges them into a single high-definition MP4 if ffmpeg is available on your system:
from aytube import download
# Download 1080p video (auto-muxes audio)
download("https://www.youtube.com/watch?v=dQw4w9WgXcQ", quality="1080p", output="video.mp4")
# Download audio only
download("https://www.youtube.com/watch?v=dQw4w9WgXcQ", audio_only=True, output="audio.m4a")
5. Resumable Range Downloads
Continue interrupted transfers from where they left off:
from aytube import download_with_resume
download_with_resume(stream_url, output="large_video.mp4")
6. Cookie Support (Bypass Bot Checks & Rate Limits)
aytube automatically checks the current working directory, ~/.config/aytube/, and your home folder for:
cookies.txtcookie.txtcookies_file
You can also pass a path explicitly:
result = get_stream_url(
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
cookies_file="cookies.txt",
quality="1080p"
)
Tip (1-Click Cookie Exporter): Use our built-in lightweight browser extension in
extension/to export YouTube cookies directly tocookies.txtin one click.
7. Metadata, Subtitles, Chapters & Search
from aytube import get_metadata, list_subtitles, get_chapters, search
# Video metadata
meta = get_metadata("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(f"{meta['title']} by {meta['channel_name']} ({meta['duration']})")
# Captions & subtitles
subs = list_subtitles("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# Video chapters
chapters = get_chapters("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
# YouTube Search
results = search("lofi hip hop", max_results=5)
💻 CLI Commands
AyTube includes a full-featured command line interface:
# 1. Get direct stream URL (1080p)
aytube get "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 1080p
# 2. Get stream URL as JSON
aytube get "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -j
# 3. List all available formats with itags, resolutions, and sizes
aytube list "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 4. Download video with progress bar
aytube download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -q 1080p -o video.mp4
# 5. Download audio track only
aytube download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -a -o song.m4a
# 6. Resume interrupted download using HTTP Range requests
aytube resume "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o video.mp4
# 7. Search YouTube directly
aytube search "lofi beats" -N 5
# 8. Download HD thumbnail (1280x720)
aytube thumb "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o thumbnail.jpg
# 9. Get structured video metadata
aytube info "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 10. List video subtitles / captions
aytube subs "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 11. List video chapters
aytube chapters "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 12. Batch download from file
aytube batch urls.txt -q 720p -n 4
# 13. Interactive configuration wizard
aytube setup
CLI Flags Reference
| Option | Flag | Description |
|---|---|---|
--quality |
-q |
Video resolution: best, 2160p, 1440p, 1080p, 720p, 480p, 360p, high, low |
--audio |
-a |
Audio stream only |
--output |
-o |
Output file path or directory |
--cookies |
-c |
Path to Netscape cookies.txt file |
--proxy |
-p |
HTTP / HTTPS proxy URL |
--format |
-f |
Specific YouTube itag format (e.g. 137, 251) |
--json |
-j |
Output result as formatted JSON |
--concurrent |
-n |
Number of concurrent downloads for batch mode |
--max-results |
-N |
Maximum results for search queries |
--quiet |
Suppress progress output |
📁 Repository Architecture
aytube/
├── aytube/
│ ├── __init__.py # Clean public API exports (24 functions & classes)
│ ├── __main__.py # CLI dispatcher supporting 13 subcommands
│ ├── cipher.py # Signature deciphering & anti-throttling n-parameter
│ ├── downloader.py # Resumable downloads, ffmpeg muxing, and batching
│ ├── extractor.py # Stream extraction orchestrator, format mapping, & cache
│ ├── innertube.py # YouTube internal API client (Android VR, Web, iOS, TV)
│ ├── metadata.py # Video metadata, subtitles, chapters, channel info
│ ├── search.py # YouTube keyword search query scraper
│ ├── stream.py # StreamResult dataclass, itags, & Range verification
│ └── utils.py # URL parser, HTTP fetcher, cookies, & configuration
├── examples/
│ ├── basic_usage.py # Quick start extraction demonstration
│ ├── batch_download.py# Multi-video concurrent downloading
│ └── custom_cookies.py# Cookie loading & proxy configuration
├── tests/
│ ├── test_unit.py # 8 offline unit tests
│ ├── test_stream.py # 7 live Google Video CDN stream extraction tests
│ └── test_cli.sh # 13 CLI integration tests
├── CHANGELOG.md # Semantic versioning release history
├── MANIFEST.in # Packaging inclusion/exclusion rules
├── pyproject.toml # Modern PEP 517 build configuration
└── setup.py # Standard setuptools configuration
🎯 Supported Stream Formats (Itags)
| ITAG | Resolution | FPS | Container | Video Codec | Audio Codec | Type |
|---|---|---|---|---|---|---|
| 401 | 2160p (4K) | 25/60 | MP4 | AV1 | — | Video (DASH) |
| 313 | 2160p (4K) | 25/60 | WebM | VP9 | — | Video (DASH) |
| 400 | 1440p (2K) | 25/60 | MP4 | AV1 | — | Video (DASH) |
| 271 | 1440p (2K) | 25/60 | WebM | VP9 | — | Video (DASH) |
| 137 | 1080p (FHD) | 25/60 | MP4 | H.264 (AVC) | — | Video (DASH) |
| 248 | 1080p (FHD) | 25/60 | WebM | VP9 | — | Video (DASH) |
| 399 | 1080p (FHD) | 25/60 | MP4 | AV1 | — | Video (DASH) |
| 136 | 720p (HD) | 25/60 | MP4 | H.264 (AVC) | — | Video (DASH) |
| 247 | 720p (HD) | 25/60 | WebM | VP9 | — | Video (DASH) |
| 135 | 480p | 25 | MP4 | H.264 (AVC) | — | Video (DASH) |
| 18 | 360p | 25 | MP4 | H.264 (AVC) | AAC | Pre-muxed Video+Audio |
| 251 | High (~160k) | — | WebM | — | Opus (48kHz) | Audio Only |
| 140 | Medium (~128k) | — | MP4 | — | AAC (m4a) | Audio Only |
| 249 | Low (~50k) | — | WebM | — | Opus | Audio Only |
🧪 Running Tests
# 1. Run offline unit tests
python3 -m unittest discover tests
# 2. Run live stream resolution test suite
python3 tests/test_stream.py
# 3. Run CLI integration tests
bash tests/test_cli.sh
🛡️ Cookie Protection & Privacy
AyTube respects your security. Cookie files and user credentials are never bundled or published. AyTube reads standard Netscape cookie files exported from your browser, allowing access to age-restricted videos and higher rate limits without sharing your credentials.
📄 License
Released under the MIT License.
Created and maintained by ABHISHEK THAKUR (abhiyanshicreation@gmail.com).
Metadata
Release files for aytube 2.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aytube-2.2.0.tar.gz | 54.9 kB | Without provenance | Details for aytube-2.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aytube-2.2.0-py3-none-any.whl | Python 3 | none | any | Details for aytube-2.2.0-py3-none-any.whl |
Total release size: 104.8 kB
Release files / aytube-2.2.0.tar.gz
| Download URL | aytube-2.2.0.tar.gz |
|---|---|
| Size | 54.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d36fb236ac40b602c7effebd5fd7ba2912d9772d976a7b61ce6ee04e2633641b
|
|
BLAKE2b-256 checksum How to use checksums |
0c3e1e925c0ad914000f8177c7a5efe6c6bd43d74c2763b30e14a68bee7f4a41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aytube-2.2.0-py3-none-any.whl
| Download URL | aytube-2.2.0-py3-none-any.whl |
|---|---|
| Size | 49.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81f788575cce087ea8e904be15a5ac73f6fe1cef8b7e32935b0db06250f278b0
|
|
BLAKE2b-256 checksum How to use checksums |
ec1401c4637abcb7519fcab7f5f85fc0dafe92739197d68ec6c453f633dcf3a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for aytube 2.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.