YouTube Video Scraper

A powerful and user-friendly YouTube video downloader with support for multiple formats, codecs, quality options, and tunneling capabilities. Includes video re-encoding, crop/rescale, and comprehensive file conversion features (audio extraction, format conversion, audio-to-video) with parallel processing. Features a beautiful console GUI with progress bars and an interactive web control panel.

Features

Important

This application downloads content from YouTube. Ensure you comply with YouTube's Terms of Service and respect copyright laws. This tool is intended for personal, educational, and non-commercial use only.

Download Features

📥 Batch Downloads: Download multiple videos from a queue file
🎬 Multiple Codecs: Support for AV1, H.264, H.265, and VP9
🎵 Audio Quality Options: Choose from 320kbps, 256kbps, 192kbps, 128kbps, and 96kbps
🎚 Lossless Remux: Optional mode that grabs the best streams and remuxes without re-encoding
📺 Quality Presets: 8K, 4K, 1440p, 1080p, 720p, 480p, 360p
🔄 Smart Fallback: Automatically selects the highest available quality if preferred quality is unavailable
🌐 Proxy Support: Built-in support for custom proxies and Tor network
⚡ Parallel Downloads: Download multiple videos simultaneously
🍪 Cookie Support: Bypass bot detection using browser cookies

Re-encoding Features

🔄 Codec Conversion: Convert videos to H.264, H.265, AV1, or VP9
📉 Quality Control: Multiple quality presets or custom CRF values
📏 Video Downscaling: Reduce resolution to save space (e.g., 1080p to 720p)
💾 Size-based Compression: Compress videos to a target file size
⚡ Parallel Re-encoding: Process multiple videos simultaneously
🎨 Beautiful Progress Bars: Real-time encoding progress with rich UI

Crop/Rescale Features

✂️ Aspect Ratio Conversion: Convert videos to standard aspect ratios (16:9, 4:3, 21:9, etc.)
📐 Custom Dimensions: Rescale to specific pixel dimensions
🎯 Two Processing Modes: Scale (with letterbox/pillarbox) or Crop (center crop)
⚡ Parallel Processing: Process multiple videos simultaneously
🎨 Real-time Progress: Beautiful progress bars with time estimates

Convert/Extract Features

🎵 Audio Extraction: Extract audio from video files while preserving quality
🎬 Audio to Video: Convert audio files to video format (with static background)
🔄 Format Conversion: Convert between video/audio formats (MP4, MKV, WebM, MP3, FLAC, etc.)
📉 Quality Preservation: Options to preserve original quality or customize output
✂️ Combined Operations: Downscale and crop while converting formats
🎨 Interactive Mode: Easy-to-use interactive interface for all conversions

Cut Features

✂️ Timestamp-Based Cutting: Cut video/audio files at specific timestamps
🎯 Multiple Cuts: Extract and concatenate multiple segments from a single file
⚡ Fast Processing: Uses stream copy for single cuts (no re-encoding)
📝 Flexible Timestamps: Supports HH:MM:SS, MM:SS, or SS formats
🎨 Interactive Mode: Easy-to-use interface for specifying cut ranges

Installation

Prerequisites

Python 3.10 or higher
FFmpeg (required for merging video and audio)
(Optional) Tor for anonymous downloads

Install FFmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

macOS:

brew install ffmpeg

Windows: Download from ffmpeg.org and add to PATH

Tip

If you encounter any errors, you may want to update / upgrade your system. Use the following commands:

Ubuntu/Debian:

sudo apt update
sudo apt upgrade

macOS:

brew update
brew upgrade

Windows:

UsoClient StartScan
UsoClient StartDownload
UsoClient StartInstall

Install Python Dependencies

pip install -r requirements.txt

Usage

Quick Start

Note

The YouTube Scraper offers three ways to use it: Interactive Mode, Command Line, and Web Server. Choose the method that best fits your workflow.

Interactive Mode (Recommended for Beginners)

Interactive mode provides a step-by-step guided experience:

python youtube_utils.py --interactive

Features:

Menu-driven interface
Guided configuration
Real-time progress bars
Error handling with helpful hints
No need to remember command-line arguments

Best for:

First-time users
One-time operations
Testing different settings
Converting/cutting specific files

Command-Line Mode (For Automation)

Use command-line arguments for scripting and automation:

# Download videos from queue file
python youtube_utils.py -i downloadqueue.txt -q 1080p -c h264

# Re-encode existing videos
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-codec h265

Best for:

Automation and scheduled tasks
Batch processing
Integration with other scripts
Remote SSH access

Web Server Mode (For Shared Usage)

Launch a web-based control panel for multi-user environments:

./server.sh start

Best for:

Shared environments (family, office)
Real-time monitoring
Managing multiple downloads
Remote access via web browser
Resource usage tracking

Basic Download Setup

Create a downloadqueue.txt file with YouTube URLs (one per line):

https://www.youtube.com/watch?v=***********
https://www.youtube.com/watch?v=***********

Run the scraper in interactive mode:

python youtube_utils.py

Web Server Control Panel

Launch a powerful web-based control panel with a clean black/white themed UI to manage downloads, conversions, and monitor system resources in real-time.

Starting the Server

# Start on default port 8000
./server.sh start

# Start on custom port
./server.sh start --port 9000

# Start on custom host and port
./server.sh start --host 0.0.0.0 --port 8080

Note

The server binds to 0.0.0.0 by default, making it accessible from other devices on your network.

Server Management

# Check server status
./server.sh status

# Restart the server
./server.sh restart

# Stop the server
./server.sh stop

# View live server logs
./server.sh logs

Tip

The server includes automatic crash recovery and will restart itself up to 10 times if it encounters errors.

Web Interface Features

Once started, open http://127.0.0.1:8000 or http://localhost:8000 in your browser to access:

Download Management:

🔍 YouTube Search: Search and preview videos before downloading
📋 Queue Management: Build custom download queues with drag-and-drop
🎛️ Quality Control: Select codec (H.264, H.265, AV1, VP9), resolution (360p-8K), and audio quality
🍪 Cookie Support: Configure browser cookies for bypassing bot detection
📥 Batch Downloads: Upload text files with multiple URLs
⏸️ Queue Control: Pause, resume, or cancel downloads in real-time

File Management:

📁 File Browser: Browse and manage downloaded files
☁️ Google Drive Integration: Automatic upload to Google Drive (optional)
🗑️ Auto-delete: Configure automatic file deletion after upload
📊 Size Tracking: Monitor storage usage per user

Conversion Tools:

🔄 Format Conversion: Convert between video/audio formats
🎵 Audio Extraction: Extract audio from video files
✂️ Video Cropping: Adjust aspect ratios and dimensions
📉 Re-encoding: Compress and optimize videos
⚙️ Batch Processing: Convert multiple files simultaneously

Monitoring & Analytics:

📊 Live Resource Graphs: Real-time CPU, RAM, and network usage
🚦 Rate Limiting: Token-based and size-based download limits
👥 Multi-user Support: Individual usage tracking per IP
📈 Bandwidth Monitoring: Track download/upload speeds
⚡ Performance Limits: Configurable CPU, RAM, and network throttling

Admin Features:

🔐 Secure Login: Password-protected admin panel
👮 User Management: Block/unblock users, view activity
🚫 Rate Limiting: Configure global and per-user limits
📋 Job Management: Priority queue control and batch regeneration
🔄 Server Control: Remote restart and shutdown
🐛 Debug Logs: Real-time debugging and error tracking

Important

Admin credentials are stored in logins.json. Default setup requires manual configuration.

Accessing from Other Devices

To access the server from other devices on your network:

Find your server's IP address:

# Linux/macOS
ifconfig | grep "inet "

# Or
ip addr show

Access from another device:

http://YOUR_SERVER_IP:8000

Warning

When exposing the server to your network, ensure you have proper firewall rules and authentication configured.

Rate Limiting & Resource Control

The web server includes comprehensive rate limiting to manage shared usage:

Note

Token-based Rate Limiting:

Each user gets a token budget that resets every 12 hours
Videos cost 5 tokens, Shorts cost 2 tokens, conversions cost 2 tokens
Prevents abuse while allowing fair usage
Admins can configure token limits in settings

Note

Size-based Rate Limiting:

Daily download size limits per user (default: 10GB/day)
Automatic tracking and reset
Helps manage bandwidth and storage

Note

Request Rate Limiting:

Prevents spam by limiting requests per minute
Separate limits for downloads and conversions
Admin controls for rate limit thresholds

Resource Controls:

CPU usage limits (default: 75%)
RAM usage limits (default: 75%)
Network bandwidth throttling
Concurrent download slots (max 3 by default)

Tip

Configure these limits in the web interface under Admin → Settings to match your server's capabilities.

Google Drive Integration

Note

Optional feature: Automatically upload completed downloads to Google Drive and delete local files after a configurable time period.

Setup:

Create a Google Cloud project and enable Drive API
Download OAuth credentials as credentials.json
Configure in web interface: Admin → Settings → Google Drive
Set auto-delete timer (default: 1 hour after upload)

Benefits:

Automatic cloud backup
Free up local storage automatically
Access downloads from anywhere
Share via Google Drive links

Troubleshooting the Server

Tip

Server won't start or crashes immediately:

# First, try a restart
./server.sh restart

# If that fails, check for port conflicts
sudo lsof -i :8000

# Kill conflicting process (replace PID with actual process ID)
kill -15 [PID]

# Start on a different port
./server.sh start --port 9000

Tip

View server logs for debugging:

# Live log viewing
./server.sh logs

# Or view the log file directly
tail -f logs/server.log

Caution

Port already in use error: If you see "Address already in use" errors, another process is using port 8000. Either:

Stop the conflicting process: sudo lsof -i :8000 then kill -15 [PID]
Use a different port: ./server.sh start --port 8080

Warning

Permission denied errors: On Linux/macOS, you may need to make the server script executable:

chmod +x server.sh

Command Line Options

Note

The command-line interface is perfect for automation, scripts, and single-use downloads. For a more interactive experience with real-time monitoring, use the Web Server Control Panel.

When to use Command Line:

✅ Automation and scheduled downloads
✅ Scripting and batch processing
✅ SSH/remote server access
✅ Integration with other tools

When to use Web Server:

✅ Interactive download management
✅ Real-time progress monitoring
✅ Multi-user environments
✅ Visual file management
✅ Resource usage monitoring

# Download with custom quality and codec
python youtube_utils.py -q 4k -c av1 -a 320 -i downloadqueue.txt

# Specify output directory
python youtube_utils.py -o /path/to/output -i downloadqueue.txt

# Use Tor for anonymity
python youtube_utils.py --tor -i downloadqueue.txt

# Use custom proxy
python youtube_utils.py --proxy socks5://127.0.0.1:1080 -i downloadqueue.txt

# Grab the absolute best streams and remux losslessly
python youtube_utils.py --lossless-download -i downloadqueue.txt

# Force interactive mode
python youtube_utils.py --interactive

Re-encoding Existing Videos

The scraper now includes powerful video re-encoding capabilities:

# Convert videos to H.265 with medium quality
python youtube_utils.py --reencode --reencode-dir ./downloads --reencode-codec h265 --reencode-quality medium

# Parallel re-encoding with 4 jobs
python youtube_utils.py --reencode --reencode-dir ./videos -p 4 --reencode-codec h264

# Downscale videos to 720p
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-scale 720

# Compress videos to 100MB each
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-size 100

# Convert to AV1 with custom CRF
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-codec av1 --reencode-crf 30

# Combine options: downscale to 720p and use H.265 with fast preset
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-codec h265 --reencode-scale 720 --reencode-preset fast -p 4

Crop/Rescale Existing Videos

Convert videos to different aspect ratios or dimensions:

# Convert videos to 16:9 aspect ratio (scale mode with letterbox)
python youtube_utils.py --crop --crop-dir ./downloads --crop-aspect-ratio 16:9

# Crop videos to 16:9 (center crop, no letterbox)
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 16:9 --crop-mode crop

# Convert to 4:3 aspect ratio for classic displays
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 4:3

# Rescale to specific dimensions (1920x1080)
python youtube_utils.py --crop --crop-dir ./videos --crop-width 1920 --crop-height 1080

# Convert vertical videos to 9:16 (Instagram/TikTok format)
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 9:16

# Parallel processing with 4 jobs
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 16:9 -p 4

Available aspect ratios: 16:9, 16:10, 4:3, 21:9 (ultrawide), 1:1 (square), 9:16 (vertical)

Processing modes:

scale (default): Resize video to fit aspect ratio, adding letterbox/pillarbox as needed
crop: Center crop video to exact aspect ratio, removing edges

Convert/Extract Files

Use interactive mode for the easiest conversion experience:

# Run interactive mode and select option 4 (Convert/Extract)
python youtube_utils.py --interactive

Conversion Types Available:

Extract Audio from Video - Extract audio track while preserving quality
- Supports: MP3, M4A/AAC, OPUS, FLAC (lossless), WAV (uncompressed)
- Can specify bitrate or use copy mode for lossless extraction
Convert Audio to Video - Create video file from audio with static background
- Choose video codec: H.264, H.265, VP9
- Output formats: MP4, MKV, WebM
Convert Between Formats - Convert video/audio files to different formats
- Video formats: MP4, MKV, WebM, AVI
- Audio formats: MP3, M4A, AAC, OPUS, FLAC, WAV
- Optional: Downscale video resolution during conversion
- Optional: Crop video during conversion
- Quality preservation: Uses copy mode when possible or high-quality encoding

Interactive Mode Features:

Browse available files in current directory
Step-by-step configuration
Preview of settings before conversion
Automatic codec selection for format compatibility

Cut Video/Audio Files

Extract specific segments from video or audio files at precise timestamps:

# Run interactive mode and select option 5 (Cut)
python youtube_utils.py --interactive

Cut Features:

Single Cut - Extract one segment from a file
- Fast processing with stream copy (no re-encoding)
- Maintains original quality
- Supports all video and audio formats
Multiple Cuts - Extract and concatenate multiple segments
- Combine multiple segments into one output file
- Useful for creating highlights or removing unwanted sections
- Automatic concatenation with proper timing

Timestamp Formats:

Seconds only: 90 (90 seconds)
Minutes:Seconds: 1:30 (1 minute 30 seconds)
Hours:Minutes:Seconds: 0:01:30 (1 minute 30 seconds)

Interactive Mode Features:

Browse available media files in current directory
Display file duration to help with timestamp selection
Add multiple cuts in sequence
Visual summary of all cuts before processing
Automatic output naming (_cut or _cuts suffix)

Available Options

Download Options

Option	Description	Default
`-i, --input`	Path to download queue file	`downloadqueue.txt`
`-o, --output`	Output directory for downloads	`./downloads`
`-q, --quality`	Video quality (8k, 4k, 1440p, 1080p, 720p, 480p, 360p)	`1080p`
`-c, --codec`	Video codec (av1, h264, h265, vp9)	`h264`
`-a, --audio-bitrate`	Audio bitrate in kbps (320, 256, 192, 128, 96)	`192`
`-p, --parallel`	Number of parallel downloads (1-10)	`1`
`--container`	Video container format (mp4, webm, mkv, auto)	`auto`
`--lossless-download`	Download best available streams and remux without re-encoding (auto uses MKV)	`False`
`--proxy`	Proxy URL (e.g., socks5://127.0.0.1:1080)	None
`--tor`	Use Tor network	False
`--cookies-from-browser`	Extract cookies from browser (chrome, firefox, edge, safari, etc.)	None
`--cookies`	Path to cookies.txt file	None
`--interactive`	Run in interactive mode	False

Re-encoding Options

Option	Description	Default
`--reencode`	Enable re-encoding mode	False
`--reencode-dir`	Directory containing videos to re-encode (required)	None
`--reencode-output`	Output directory for re-encoded videos	`<input-dir>/reencoded`
`--reencode-codec`	Target codec (h264, h265, av1, vp9)	`h264`
`--reencode-quality`	Quality preset (best, high, medium, low)	None
`--reencode-crf`	Custom CRF value (codec-dependent)	None
`--reencode-size`	Target file size in MB	None
`--reencode-scale`	Downscale to height (e.g., 720 for 720p)	None
`--reencode-preset`	FFmpeg preset (ultrafast to veryslow)	`medium`
`-p, --parallel`	Number of parallel re-encoding jobs (1-10)	`1`

Crop/Rescale Options

Option	Description	Default
`--crop`	Enable crop/rescale mode	False
`--crop-dir`	Directory containing videos to crop/rescale (required)	None
`--crop-output`	Output directory for processed videos	`<input-dir>/cropped`
`--crop-aspect-ratio`	Aspect ratio preset (16:9, 16:10, 4:3, 21:9, 1:1, 9:16)	None
`--crop-width`	Target width in pixels (requires --crop-height)	None
`--crop-height`	Target height in pixels (requires --crop-width)	None
`--crop-mode`	Processing mode: `scale` or `crop`	`scale`
`-p, --parallel`	Number of parallel processing jobs (1-10)	`1`

Configuration Files

Note

The application uses multiple configuration files for different purposes:

config.ini - Default download settings
settings.json - Web server settings and rate limits
logins.json - Admin authentication
credentials.json - Google Drive API credentials (optional) Use the following template files to start:
settings_template.json
logins_template.json
credentials_template.json Make sure to remove the _template part so the code recognizes the configuration files!

config.ini

You can customize default download settings by editing config.ini:

[DEFAULT]
output_dir = ./downloads
quality = 1080p
video_codec = h264
audio_bitrate = 192
queue_file = downloadqueue.txt

[PROXY]
enabled = false
use_tor = false
proxy_url = 

[ADVANCED]
merge_format = mp4
max_concurrent = 1
retry_count = 3
wait_time = 0

Download Queue File Format

The downloadqueue.txt file should contain one YouTube URL per line:

# You can add comments with #
https://www.youtube.com/watch?v=VIDEO_ID_1
https://www.youtube.com/watch?v=VIDEO_ID_2

# Empty lines are ignored
https://www.youtube.com/watch?v=VIDEO_ID_3

Video Codecs

Note

Choosing the right codec depends on your needs: compatibility, file size, or encoding speed.

AV1: Modern, efficient codec with excellent compression (requires compatible hardware/software)
- Best for: Archival, long-term storage, reducing file sizes
- Trade-off: Slower encoding, may not play on older devices
H.264 (AVC): Most compatible, works on all devices
- Best for: Maximum compatibility, sharing videos
- Trade-off: Larger file sizes compared to newer codecs
H.265 (HEVC): Better compression than H.264, newer devices
- Best for: Balance of compatibility and file size
- Trade-off: Some older devices may not support it
VP9: Google's open codec, good quality and compression
- Best for: Web playback, open-source preference
- Trade-off: Limited hardware support

Tip

For maximum compatibility, use H.264. For smallest file sizes with modern devices, use H.265 or AV1.

Quality Options

The scraper automatically selects the best available quality up to your specified limit:

8K: 7680×4320 (4320p)
4K: 3840×2160 (2160p)
1440p: 2560×1440 (QHD)
1080p: 1920×1080 (Full HD)
720p: 1280×720 (HD)
480p: 854×480 (SD)
360p: 640×360 (Low)

If your selected quality is not available, the scraper will automatically download the highest available quality.

Proxy & Tunneling

Note

Proxy support allows you to route downloads through external servers for privacy or to bypass regional restrictions.

Using Tor

Important

Tor provides anonymity but will significantly slow down downloads. Only use when necessary.

Install and run Tor:

# Ubuntu/Debian
sudo apt install tor
sudo service tor start

# macOS
brew install tor
tor

Run scraper with Tor:

python youtube_utils.py --tor

Using Custom Proxy

# SOCKS5 proxy
python youtube_utils.py --proxy socks5://127.0.0.1:1080

# HTTP proxy
python youtube_utils.py --proxy http://proxy.example.com:8080

# With authentication
python youtube_utils.py --proxy socks5://user:pass@127.0.0.1:1080

Bypassing Bot Detection with Cookies

Warning

YouTube may block downloads with "Sign in to confirm you're not a bot" errors, especially for age-restricted or private content.

You can bypass this by using cookies from your browser, which authenticates the download as if you were logged in.

Caution

Never share your cookies file or browser cookies with others. They contain your authentication tokens and could be used to access your account.

Option 1: Extract Cookies from Browser (Recommended)

The easiest method is to let yt-dlp extract cookies directly from your browser:

# Extract from Chrome
python youtube_utils.py --cookies-from-browser chrome

# Extract from Firefox
python youtube_utils.py --cookies-from-browser firefox

# Extract from Edge
python youtube_utils.py --cookies-from-browser edge

# Extract from Safari (macOS)
python youtube_utils.py --cookies-from-browser safari

Supported browsers: chrome, firefox, edge, safari, opera, brave, chromium, vivaldi

Note: Make sure you're logged into YouTube in the browser you're extracting cookies from.

Option 2: Export Cookies to File

If automatic extraction doesn't work, you can manually export cookies:

Install a cookie export extension:
- Chrome/Edge: Get cookies.txt LOCALLY
- Firefox: cookies.txt
Export cookies:
- Navigate to YouTube while logged in
- Click the extension icon
- Export cookies as cookies.txt in Netscape format
- Save to your project directory
Use the cookies file:

python youtube_utils.py --cookies cookies.txt

Interactive Mode Cookie Setup

When using interactive mode, you'll be prompted:

Use cookies to bypass bot detection? [y/N]: y

Cookie options:
  1. Extract from browser (chrome, firefox, edge, safari, etc.)
  2. Use cookies.txt file
Choose option [1]: 1

Available browsers:
  chrome, firefox, edge, safari, opera, brave, chromium
Enter browser name [chrome]: chrome

Troubleshooting Cookie Issues

"Could not find browser" error: Make sure the browser is installed and yt-dlp can access it
"Could not extract cookies" error: Try closing the browser and running the scraper again
Still getting bot detection: Try logging out and back into YouTube, then extract cookies again
Permission errors: On Linux/macOS, you may need to close the browser before extracting cookies

Best Practices

Important

Legal and Ethical Usage:

Only download content you have the right to access
Respect copyright laws and YouTube's Terms of Service
Do not redistribute downloaded content without permission
This tool is for personal, educational, and non-commercial use only

Tip

Quality vs. File Size Trade-offs:

For archival: Use highest quality with lossless remux (--lossless-download)
For sharing: Use 1080p with H.264 codec (maximum compatibility)
For storage savings: Use 720p with H.265 or AV1 codec
For mobile: Use 480p or 720p to save data and storage

Tip

Optimal Parallel Downloads:

For most connections: -p 2 or -p 3
For very fast connections: -p 5 to -p 10
For slow connections: -p 1 (default, sequential)
Server usage: Balance between speed and resource consumption

Tip

Cookie Management:

Extract cookies when you encounter bot detection
Re-extract cookies if they stop working (usually after browser logout)
Use --cookies-from-browser for automatic extraction
Keep cookies.txt file secure and don't share it

Warning

Proxy/Tor Usage:

Tor significantly slows download speeds (use only when necessary)
Some proxies may be unreliable or inject malware
Free proxies often have bandwidth limits
Always verify proxy source before use

Tip

Server Performance:

Set appropriate CPU/RAM limits to prevent system overload
Enable auto-delete with Google Drive to manage storage
Configure rate limiting for shared environments
Monitor resource usage through the web interface
Use token-based limits to ensure fair usage

Caution

Storage Management:

Video files can be very large (8K videos: 1-5GB per minute)
Monitor available disk space regularly
Enable auto-delete or manually clean up completed downloads
Consider using re-encoding to reduce file sizes

Examples

Download in highest quality with AV1 codec

python youtube_utils.py -q 8k -c av1 -a 320

Download 4K videos with high quality audio through Tor

python youtube_utils.py -q 4k -a 320 --tor

Download to specific directory with custom settings

python youtube_utils.py -o ~/Videos/YouTube -q 1440p -c h265 -a 256

Bypass bot detection with browser cookies

# Using Chrome cookies
python youtube_utils.py --cookies-from-browser chrome

# Using Firefox cookies
python youtube_utils.py --cookies-from-browser firefox

# Using cookies.txt file
python youtube_utils.py --cookies cookies.txt

Parallel downloads

# Download 3 videos simultaneously
python youtube_utils.py -p 3 -i downloadqueue.txt

# Download in 4K with 5 parallel jobs
python youtube_utils.py -q 4k -p 5 -i downloadqueue.txt

Re-encoding examples

# Convert all MP4 files to H.265
python youtube_utils.py --reencode --reencode-dir ./downloads --reencode-codec h265

# Compress videos to 50MB each with 3 parallel jobs
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-size 50 -p 3

# Downscale to 720p and convert to AV1
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-codec av1 --reencode-scale 720 --reencode-quality high

# Fast re-encoding with ultrafast preset
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-preset ultrafast -p 4

Crop/Rescale examples

# Convert all videos to 16:9 aspect ratio
python youtube_utils.py --crop --crop-dir ./downloads --crop-aspect-ratio 16:9

# Crop videos to 4:3 (remove edges, no letterbox)
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 4:3 --crop-mode crop

# Rescale to 1280x720 with 4 parallel jobs
python youtube_utils.py --crop --crop-dir ./videos --crop-width 1280 --crop-height 720 -p 4

# Convert to square format for Instagram
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 1:1 --crop-mode crop

Convert/Extract examples

# Use interactive mode for guided conversion (recommended)
python youtube_utils.py --interactive
# Then select option 4 (Convert/Extract)

# The interactive mode provides:
# - Automatic file discovery
# - Step-by-step configuration
# - Format-specific codec selection
# - Quality preservation options
# - Combined operations (scale + crop + convert)

Example workflows in interactive mode:

Extract high-quality audio from video:
- Select: Extract audio from video file
- Choose: FLAC (lossless) or MP3 320k (high quality)
- Result: Pure audio file with original quality preserved
Convert audio to video for platforms:
- Select: Convert audio file to video
- Choose: MP4 with H.264 codec
- Result: Video with static background, preserving audio quality
Convert and optimize video:
- Select: Convert between file formats
- Choose: Output format (e.g., WebM for web)
- Optional: Downscale to 720p to reduce file size
- Result: Converted and optimized video

Cut examples

# Use interactive mode for guided cutting (recommended)
python youtube_utils.py --interactive
# Then select option 5 (Cut video/audio at specific timestamps)

# The interactive mode provides:
# - Automatic file discovery
# - File duration display
# - Flexible timestamp formats (HH:MM:SS, MM:SS, or SS)
# - Support for multiple cuts
# - Visual cut configuration summary

Example workflows in interactive mode:

Extract a single segment:
- Select: Your video/audio file
- Enter: Start time: 00:01:30 (or 1:30 or 90)
- Enter: End time: 00:03:45 (or 3:45 or 225)
- Result: New file with just that segment (fast, no re-encoding)
Create a highlights reel (multiple cuts):
- Select: Your video file
- Cut 1: 00:00:10 to 00:00:30 (opening scene)
- Cut 2: 00:02:15 to 00:02:45 (highlight 1)
- Cut 3: 00:05:20 to 00:06:00 (highlight 2)
- Result: Combined video with all selected segments
Remove unwanted sections:
- Extract segments before and after the unwanted section
- Cut 1: 00:00:00 to 00:05:00 (keep beginning)
- Cut 2: 00:08:00 to 00:15:00 (keep end)
- Result: Video without the middle section (5:00-8:00)

Performance Tips

Tip

Optimize download speeds:

Use H.264 codec (fastest encoding)
Enable parallel downloads: -p 3
Disable proxy if not needed
Use lossless remux mode: --lossless-download

Tip

Reduce file sizes:

Lower video quality: -q 720p
Reduce audio bitrate: -a 128
Use efficient codecs: AV1 or H.265
Enable re-encoding with size target: --reencode-size 100

Tip

Optimize server performance:

Limit concurrent downloads in web interface
Set CPU/RAM limits to prevent system overload
Enable auto-delete to free up storage
Configure rate limiting for shared usage

Troubleshooting

"FFmpeg not found" or "You have requested merging of multiple formats but ffmpeg is not installed"

Install FFmpeg as described in the Installation section.

Caution

Ensure FFmpeg is in your system PATH. Test with ffmpeg -version in terminal.

"Sign in to confirm you're not a bot"

YouTube is blocking the download. Use cookies to bypass this:

python youtube_utils.py --cookies-from-browser chrome

See the "Bypassing Bot Detection with Cookies" section for more details.

"No formats found"

The video might not be available in your requested quality/codec. Try a different quality preset or codec.

Slow downloads

Try using a different video codec (h264 is usually fastest to encode)
Lower the quality setting
Check your internet connection
Disable proxy if not needed

Proxy connection failed

Ensure your proxy/Tor is running
Check the proxy URL format
Verify firewall settings

License

CC BY-NC-SA 4.0 License - See LICENSE and NOTICE files for details. Non-commercial use only.

Quick Reference

Note

Common Commands Cheat Sheet:

# Basic Downloads
python youtube_utils.py                          # Interactive mode
python youtube_utils.py -i queue.txt             # Batch download from file
python youtube_utils.py -q 4k -c h265 -a 320     # 4K, H.265, 320kbps audio

# Web Server
./server.sh start                                # Start server (port 8000)
./server.sh start --port 9000                    # Start on custom port
./server.sh status                               # Check status
./server.sh logs                                 # View live logs
./server.sh stop                                 # Stop server

# Bypass Bot Detection
python youtube_utils.py --cookies-from-browser chrome
python youtube_utils.py --cookies cookies.txt

# Re-encoding
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-codec h265
python youtube_utils.py --reencode --reencode-dir ./videos --reencode-size 100

# Crop/Rescale
python youtube_utils.py --crop --crop-dir ./videos --crop-aspect-ratio 16:9
python youtube_utils.py --crop --crop-dir ./videos --crop-width 1920 --crop-height 1080

# Parallel Processing
python youtube_utils.py -p 3 -i queue.txt        # 3 parallel downloads
python youtube_utils.py --reencode -p 4          # 4 parallel re-encodes

# Privacy
python youtube_utils.py --tor                    # Use Tor network
python youtube_utils.py --proxy socks5://127.0.0.1:1080

File Locations:

Downloads: ./downloads/
Re-encoded videos: ./downloads/reencoded/
Cropped videos: ./downloads/cropped/
Converted files: ./conversions/
Server logs: ./logs/server.log
Configuration: config.ini, settings.json

Default Ports:

Web Server: 8000
Tor SOCKS proxy: 9050

Tip

For detailed information on any feature, refer to the relevant section above or use the interactive mode.

Credits

Built with:

yt-dlp - YouTube downloader
Flask - Web framework
rich - Beautiful terminal formatting
FFmpeg - Media processing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Note

When contributing, please:

Follow existing code style
Add tests for new features
Update documentation
Ensure all tests pass

Support

Tip

Having issues?

Check the Troubleshooting section
Review Best Practices
Check existing GitHub issues
Create a new issue with detailed information

Made with ❤️ for the community. Happy downloading! 🎬

Name		Name	Last commit message	Last commit date
Latest commit History 186 Commits
.devcontainer		.devcontainer
.github		.github
INFO		INFO
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
config.ini		config.ini
credentials_template.json		credentials_template.json
driveapi.txt		driveapi.txt
logins_template.json		logins_template.json
requirements.txt		requirements.txt
server.py		server.py
server.sh		server.sh
setting_template.json		setting_template.json
youtube_utils.py		youtube_utils.py

License

maple-underscore/youtube-scraper

Folders and files

Latest commit

History

Repository files navigation

YouTube Video Scraper

Table of Contents

Features

Download Features

Re-encoding Features

Crop/Rescale Features

Convert/Extract Features

Cut Features

Installation

Prerequisites

Install FFmpeg

Install Python Dependencies

Usage

Quick Start

Interactive Mode (Recommended for Beginners)

Command-Line Mode (For Automation)

Web Server Mode (For Shared Usage)

Basic Download Setup

Web Server Control Panel

Starting the Server

Server Management

Web Interface Features

Accessing from Other Devices

Rate Limiting & Resource Control

Google Drive Integration

Troubleshooting the Server

Command Line Options

Re-encoding Existing Videos

Crop/Rescale Existing Videos

Convert/Extract Files

Cut Video/Audio Files

Available Options

Download Options

Re-encoding Options

Crop/Rescale Options

Configuration Files

config.ini

Download Queue File Format

Video Codecs

Quality Options

Proxy & Tunneling

Using Tor

Using Custom Proxy

Bypassing Bot Detection with Cookies

Option 1: Extract Cookies from Browser (Recommended)

Option 2: Export Cookies to File

Interactive Mode Cookie Setup

Troubleshooting Cookie Issues

Best Practices

Examples

Download in highest quality with AV1 codec

Download 4K videos with high quality audio through Tor

Download to specific directory with custom settings

Bypass bot detection with browser cookies

Parallel downloads

Re-encoding examples

Crop/Rescale examples

Convert/Extract examples

Cut examples

Performance Tips

Troubleshooting

"FFmpeg not found" or "You have requested merging of multiple formats but ffmpeg is not installed"

"Sign in to confirm you're not a bot"

"No formats found"

Slow downloads

Proxy connection failed

License

Quick Reference

Credits

Contributing

Support

About

Resources

License

Packages