YouTube Downloader & Encoder (yt-dler)

🌈 Vibes

This entire project was 100% vibe coded - a testament to the raw creative energy that flows when developers embrace the aesthetic of retro computing and the pure joy of building something meaningful. Every line of code, every feature, and every design decision was infused with the nostalgic essence of computing's golden age.

🎆 Dedicated with infinite respect to the honorable Zachary Hanif 🎆
A visionary who understands that the best code isn't just functional - it's got soul.

---

"Now remember, kids, the internet is serious business." - Isaac Asimov (probably)
But sometimes... sometimes you just gotta vibe. 🌊

---

A powerful Rust-based application for downloading and encoding YouTube videos with both command-line and graphical user interfaces.

🎯 Project Status

✅ FULLY FUNCTIONAL - All compilation errors resolved
✅ HIGH-QUALITY DOWNLOADS - Automatic 1080p downloads with adaptive encoding
✅ CLI Interface - Working with full argument parsing
✅ GUI Interface - Builds and launches successfully
✅ ADAPTIVE ENCODING - Preserves source quality automatically
⚠️ External Dependencies Required - See installation section

Features

• 🎬 High-Quality Downloads: Automatically downloads the highest available quality (up to 1080p) using yt-dlp
• 🧠 Adaptive Encoding: New mp4_adaptive preset preserves source resolution and quality automatically
• ⚡ Smart Fallback: Multiple download strategies to bypass YouTube throttling
• 🎯 Dual Interface: Both CLI and GUI applications for different use cases
• 📊 Progress Tracking: Real-time progress reporting with speed and ETA information
• 🚀 Hardware Acceleration: Automatic detection and use of GPU acceleration when available
• ⚙️ Flexible Configuration: Comprehensive configuration system with TOML files
• 🛡️ Error Recovery: Robust error handling with user-friendly suggestions
• 🚫 Cancellation Support: Graceful cancellation of long-running operations

Prerequisites

Before using yt-dler, ensure you have the following dependencies installed:

Required Dependencies

1. yt-dlp: For downloading YouTube videos

   # Install via pip (recommended)
   pip install yt-dlp
   
   # Or via pipx (isolated installation)
   pipx install yt-dlp

2. FFmpeg: For video encoding and processing

   • Ubuntu/Debian: sudo apt install ffmpeg
   • macOS: brew install ffmpeg
   • Windows: Download from FFmpeg official site
   • Arch Linux: sudo pacman -S ffmpeg
   • Fedora/RHEL: sudo dnf install ffmpeg

Verification

Check if dependencies are installed correctly:

# Build and test dependency checking
cargo build
cargo run --bin yt-dler-cli -- --check-deps

Expected output when dependencies are missing:

🔍 Checking dependencies...
❌ Missing dependencies:
  • yt-dlp
  • ffmpeg
  • ffprobe

💡 Installation suggestions:
  Install yt-dlp: pip install yt-dlp
  Install FFmpeg: https://ffmpeg.org/download.html

Installation

Building from Source

1. Prerequisites:

   • Rust 1.70+ (install via rustup.rs)
   • Git

2. Clone the repository:

   git clone <repository-url>
   cd yt-dler

3. Build the project:

   # Debug build (faster compilation)
   cargo build
   
   # Release build (optimized)
   cargo build --release

4. Install binaries (optional):

   cargo install --path .

Binary Locations

After building, binaries are located in:

• Debug: target/debug/yt-dler-cli and target/debug/yt-dler-gui
• Release: target/release/yt-dler-cli and target/release/yt-dler-gui

Usage

Command Line Interface (CLI)

Basic Usage (New Default Behavior)

Check dependencies first:

./target/release/yt-dler-cli --check-deps

✨ Download in highest quality with adaptive encoding (NEW DEFAULT):

# Downloads at best available quality (up to 1080p) and encodes to MP4 preserving source resolution
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4"
# Result: Full 1080p MP4 maintaining source quality automatically!

🎬 Example Downloads:

1080p Movie Clip Example:

./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4"
# Downloads and encodes to 1920x1080 MP4 (or source resolution if different)

4K Content Example:

./target/release/yt-dler-cli "https://www.youtube.com/watch?v=vsjK7AVmsL8"
# Downloads best available quality, preserves 4K if available

Download only (skip encoding):

./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --download-only

Encoding Presets

🆕 NEW: Adaptive Preset (Default)

• mp4_adaptive - DEFAULT: Preserves source resolution and quality automatically
  • Uses CRF 18 for near-lossless quality
  • H.264 + AAC encoding for maximum compatibility
  • No downscaling - maintains original resolution
  • Perfect for preserving high-quality downloads

Standard Presets:

• Video Presets: mp4_480p, mp4_720p, mp4_1080p, mp4_1440p, mp4_4k
• WebM Presets: webm_720p, webm_1080p
• Audio Only: audio_mp3, audio_aac

Advanced Options

Custom preset selection:

# Force specific resolution (will downscale if needed)
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --preset mp4_720p

# 4K encoding (if source supports it)
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=vsjK7AVmsL8" --preset mp4_4k

# Extract audio only
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --preset audio_mp3

Other options:

# Custom output directory
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --output /path/to/downloads

# Quiet mode (no progress bars)
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --quiet

# Verbose output
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --verbose

# Custom configuration file
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --config /path/to/config.toml

Performance Trade-offs

Preset	Encoding Speed	Quality	Hardware Accel	Best For
mp4_adaptive	Medium	Highest	✅ Yes	Archive/Best quality
mp4_1080p	Fast	High	✅ Yes	Standard high-def
mp4_720p	Faster	Good	✅ Yes	Balanced performance
audio_only	Fastest	N/A	❌ No	Audio extraction

CLI Help

./target/release/yt-dler-cli --help

Graphical User Interface (GUI)

Launch the GUI application:

cargo run --bin yt-dler-gui
# or
./target/release/yt-dler-gui

GUI Features

• Intuitive Interface: Simple form-based input for URLs and settings
• 🆕 Adaptive Preset: Now defaults to mp4_adaptive for best quality
• Real-time Progress: Visual progress bars with speed and ETA
• Quality Selection: Choose from multiple video quality and preset options
• Output Management: Select custom output directories
• Error Display: Clear error messages with troubleshooting suggestions
• Configuration: Access to all application settings via GUI

Configuration Options

Default configuration with new adaptive behavior:

[download]
video_quality = "best"  # Downloads highest available quality
extract_audio = false
keep_video_after_audio_extract = true

[encoding]
default_preset = "mp4_adaptive"  # NEW: Preserves source quality
use_hardware_acceleration = true
max_concurrent_jobs = 4

[output]
default_directory = "YouTube Downloads"
organize_by_date = false
keep_original_after_encoding = false

[ui]
theme = "dark"
show_advanced_options = false

[advanced]
verbose_output = false
temp_directory = ""
cleanup_after_encoding = true

Configuration Management

Create custom configuration:

# Generate default config
./target/release/yt-dler-cli --generate-config > config.toml

# Use custom config
./target/release/yt-dler-cli "https://www.youtube.com/watch?v=Bmz67ErIRa4" --config config.toml

Development

Building

# Debug build (faster compilation, includes debug symbols)
cargo build

# Release build (optimized, smaller size)
cargo build --release

# Run tests
cargo test

# Check code formatting
cargo fmt --check

# Run linter
cargo clippy -- -D warnings

# Fix formatting automatically
cargo fmt

Key Dependencies

• tokio: Async runtime for concurrent operations
• clap: Command-line argument parsing
• eframe/egui: Cross-platform GUI framework
• serde: Serialization for configuration management
• yt-dlp: External tool for YouTube video downloading
• FFmpeg: External tool for video encoding and processing

Project Structure

src/
├── lib.rs          # Core library and YtDler struct
├── config.rs       # Configuration management
├── downloader.rs   # YouTube download logic with yt-dlp
├── encoder.rs      # Video encoding with FFmpeg
├── progress.rs     # Progress reporting system
├── error.rs        # Error types and handling
├── gui.rs          # GUI implementation with egui
└── bin/
    ├── cli.rs      # Command-line interface
    └── gui.rs      # GUI application entry point

Error Handling

yt-dler provides comprehensive error handling with user-friendly messages:

Common Issues and Solutions

1. Missing Dependencies

   Error: Missing dependencies
   Solution: Install yt-dlp and FFmpeg (see Prerequisites)
   Check: ./target/release/yt-dler-cli --check-deps
   

2. Network Errors

   Error: Network timeout or connection failed
   Solution: Check internet connection and try again
   Note: yt-dler has multiple fallback strategies for YouTube throttling
   

3. Invalid URLs

   Error: Invalid YouTube URL
   Solution: Ensure URL format is correct (youtube.com or youtu.be)
   Example: https://www.youtube.com/watch?v=Bmz67ErIRa4
   

4. Quality Not Available

   Error: Requested quality not available
   Solution: Use adaptive preset or check available qualities
   Note: mp4_adaptive automatically adapts to best available
   

5. Disk Space

   Error: Insufficient disk space
   Solution: Free up space or choose different output directory
   Note: Adaptive encoding produces larger files for better quality
   

6. Permissions

   Error: Permission denied
   Solution: Ensure write access to output directory
   

Getting Help

• Review error messages carefully (they include suggestions)
• Enable verbose output with --verbose
• Check this README for common solutions
• Verify external dependencies are properly installed
• Test with example URLs provided in this README

Performance Optimization

Hardware Acceleration

yt-dler automatically detects and uses hardware acceleration when available:

• NVIDIA: CUDA/NVENC encoding (major performance boost)
• Intel: Quick Sync Video (QSV)
• AMD: Video Acceleration API (VAAPI)

Tips for Better Performance

1. Use hardware acceleration (enabled by default)
2. Choose appropriate presets (adaptive = best quality, 720p = faster)
3. Use SSD storage for temporary files
4. Ensure sufficient RAM for large video files (especially 4K)
5. Modern CPU benefits adaptive encoding CRF calculations

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following Rust best practices
4. Add tests as needed
5. Ensure code passes cargo clippy and cargo test
6. Submit a pull request

Code Style

• Follow Rust naming conventions (use cargo fmt)
• Add comprehensive comments and documentation
• Include error handling for all operations
• Write tests for new functionality
• Use #[derive(Debug)] for custom types
• Prefer Result<T, E> over panics

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• yt-dlp: Powerful YouTube video downloader and successor to youtube-dl
• FFmpeg: Comprehensive multimedia processing framework
• egui: Immediate mode GUI framework for Rust
• Rust Community: Excellent ecosystem, tools, and documentation
• Tokio: Asynchronous runtime for Rust

Troubleshooting

Build Issues

1. Rust version: Ensure Rust 1.70+ is installed
2. Dependencies: Update with cargo update
3. Clean build: Try cargo clean && cargo build

Runtime Issues

1. Check dependencies: ./target/release/yt-dler-cli --check-deps
2. Verify URLs: Test with provided example URLs
3. Check permissions: Ensure write access to output directory
4. Free space: Verify sufficient disk space (adaptive encoding uses more space)
5. Hardware accel: Check if GPU drivers are properly installed

Changelog

Version 0.1.1 (Latest)

• 🆕 NEW: mp4_adaptive preset for source-quality preservation
• 🆕 NEW: Automatic 1080p downloads with adaptive encoding as default
• ✅ Enhanced download quality selection with proper DASH stream handling
• ✅ Improved fallback strategies for YouTube throttling bypass
• ✅ Updated CLI and GUI to use adaptive encoding by default
• ✅ Better quality preservation - no more unnecessary downscaling
• ✅ CRF 18 encoding for near-lossless quality
• ✅ Source resolution preservation (1728x1080, 4K, etc.)

Version 0.1.0 (Foundation)

• ✅ Initial release with working CLI and GUI
• ✅ Download and encoding functionality
• ✅ Configuration management system
• ✅ Progress reporting with real-time updates
• ✅ Comprehensive error handling and recovery
• ✅ Hardware acceleration support
• ✅ Cross-platform compatibility (Linux, macOS, Windows)
• ✅ External dependency validation
• ✅ Multiple encoding presets and quality options

Recent Major Improvements

• 🔧 Fixed YouTube quality parameter propagation through fallback strategies
• 🔧 Resolved all compilation errors and build issues
• 🔧 Enhanced ProgressReporter trait implementation
• 🔧 Improved download success rate with better client spoofing
• 🔧 Added adaptive encoding that preserves source video quality
• 🔧 Updated default behavior to automatically use best practices