TubeFetch

A lightweight, powerful video downloader powered by yt-dlp. Supports 2000+ websites including YouTube, Bilibili, TikTok, and more.

Quick Start

1. Create Virtual Environment & Install Dependencies

It is recommended to use a virtual environment to isolate project dependencies.

Option A — Using venv (Built-in)

# Windows (PowerShell)
python -m venv venv
.\venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

Option B — Using Conda

conda create -n tubefetch python=3.10 -y
conda activate tubefetch

Once activated, install the requirements:

pip install -r requirements.txt

Note: If you need to merge high-quality video/audio (bestvideo+bestaudio), you must install ffmpeg:

• macOS: brew install ffmpeg
• Ubuntu: sudo apt install ffmpeg
• Windows: Download from ffmpeg.org or winget install ffmpeg

2. Basic Usage

# Show help
python tubefetch.py --help

# Show version
python tubefetch.py --version

# Download the first video (default)
python tubefetch.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Download the Nth video on a page
python tubefetch.py "URL" -n 2

# Specify output directory
python tubefetch.py "URL" --output-dir ~/Downloads

# Use a custom config file
python tubefetch.py "URL" --config my_config.json

# Specify quality (e.g., 720p max)
python tubefetch.py "URL" -f "bestvideo[height<=720]+bestaudio/best[height<=720]"

# Verbose mode for debugging
python tubefetch.py "URL" -v

# Run as a module
python -m tubefetch "URL"

3. Using Configuration

Copy config.json and customize it:

cp config.json my_config.json

Then run:

python tubefetch.py "URL" --config my_config.json

Configuration Options

Option	Description	Default
playlist_item	Index of the video to download	1
format	Quality selector (avoids AV1/HEVC by default)	bestvideo[vcodec!*=av01][vcodec!*=hev1][vcodec!*=hvc1]+bestaudio/...
merge_output_format	Final container format	mp4
outtmpl	Filename template	%(title)s.%(ext)s
output_dir	Download directory	./downloads
write_subtitle	Download subtitles	false
write_thumbnail	Download thumbnails	false
socket_timeout	Network timeout (seconds)	30
retries	Number of retries	3
user_agent	Custom User-Agent	"" (default)
force_generic_extractor	Enable generic extractor fallback	false
cookie_file	Path to cookies.txt (for login)	""

Common Quality Selectors

Format	Description
best	Best single-file format
worst	Lowest quality
bestvideo+bestaudio/best	Best video + best audio merged (may use AV1/HEVC)
bestvideo[vcodec!*=av01][vcodec!*=hev1][vcodec!*=hvc1]+bestaudio/...	Best quality excluding AV1/HEVC (Recommended)
bestvideo[height<=720]+bestaudio/best[height<=720]	720p Max
bestvideo[height<=1080]+bestaudio/best[height<=1080]	1080p Max

Compatibility Note: Some sites (like Bilibili) use AV1 (av01) or HEVC (hev1/hvc1) for high-quality videos. Windows Media Player often lacks native support for these, resulting in "audio only, no picture". The default configuration filters these out to ensure H.264 (avc1) compatibility.

Cookie Settings (for Restricted/Member Videos)

Some videos require login. You can provide cookies:

Option 1: Export Cookies (Recommended)

1. Install a browser extension to export cookies:
   • Chrome: Get cookies.txt LOCALLY
   • Firefox: cookies.txt
2. Log in to the site, click the extension, and export cookies.txt.
3. Set cookie_file in config.json:

   "cookie_file": "/path/to/cookies.txt"

Option 2: Use Built-in Browser Cookies

# This requires yt-dlp directly
yt-dlp --cookies-from-browser chrome "URL"

Supported Sites

Powered by yt-dlp, TubeFetch supports 2000+ sites including:

• International: YouTube, Twitter/X, Instagram, TikTok, Facebook, Vimeo, Twitch
• China: Bilibili, Douyin, Youku, iQIYI, Tencent Video, Weibo, NetEase Music
• Others: Any page with embedded video via the generic extractor.

See the full list: yt-dlp --list-extractors

Troubleshooting

Q: Download failed for a specific site?

1. Update yt-dlp: pip install -U yt-dlp
2. Enable generic extractor in config: "force_generic_extractor": true
3. Provide cookies if the video is restricted.

Q: Slow download speeds?

TubeFetch supports external downloaders like aria2:

pip install aria2
python tubefetch.py "URL"  # Automatically detected

CLI Usage Reference

usage: tubefetch.py [-h] [-n ITEM] [-o OUTPUT_DIR] [-c CONFIG] [-f FORMAT]
                    [-v] [-q] [--version] url

positional arguments:
  url                   URL of the video page

options:
  -h, --help            show this help message and exit
  -n, --item ITEM       Index of the video (default: 1)
  -o, --output-dir OUTPUT_DIR
                        Directory to save videos
  -c, --config CONFIG   Path to a custom JSON config file
  -f, --format FORMAT   Video format selector (yt-dlp syntax)
  -v, --verbose         Enable verbose debug output
  -q, --quiet           Suppress all output except errors
  --version             show program's version number and exit