YouTube CLI Agent

Project Overview

This is a command-line interface for browsing and downloading YouTube videos. The application allows users to search YouTube, display videos in pages of 15, and download videos using yt-dlp with progress indication.

Core Features

Search YouTube videos with keyword queries
Display videos with title, author, duration, and type (short/video)
Download videos using yt-dlp with progress indication
Configure download locations through configuration files
Handle short videos (videos with /shorts/ in URL) with special "(short)" prefix
Pagination support to view more than 15 videos per search
Network share integration for copying downloaded videos

Project Structure

youtube-cli/
├── youtube_cli/                 # Main package directory
│   ├── __init__.py             # Package initialization
│   ├── __main__.py             # Main entry point
│   └── main.py                 # Core application logic
├── setup.py                    # Python package setup
├── requirements.txt            # Python dependencies
├── README.md                   # Project documentation
├── prompt.md                   # Prompt template
├── structure.md                # Project structure documentation
└── run.sh                      # Run script

Main Components

youtube_cli/main.py

The core application logic file containing:

YouTubeCLI class with all main functionality
Search videos using yt-dlp with pagination support
Display videos in formatted tables with Rich library
Download videos with progress indication
Configuration management
Archive tracking for downloaded videos
Network share copying functionality
Update checking for yt-dlp

Key Methods in YouTubeCLI Class

search_videos(): Search YouTube videos using yt-dlp
display_videos(): Display videos in a formatted table
download_video(): Download individual videos with progress
download_playlist(): Download YouTube playlists
load_config(): Load configuration from file or use defaults
load_archive(): Load archive of already downloaded videos
add_to_archive(): Add videos to download archive
copy_to_network_share(): Copy downloaded videos to network share
check_for_updates(): Check and update yt-dlp if needed

Configuration

The application creates a default configuration file at ~/.config/youtube_cli/config.json if one doesn't exist. Configuration includes:

download_dir: Default download directory (set to /Volumes/MediaServer/Youtube/)
default_locations: List of default download locations including Tech, AI, Art, Homes, Cooking, Fitness, Music, Gaming, Education, Travel, Business, Science, History, Comedy, News, Sports, Nature, Photography, Language, and Automotive categories
max_videos_per_page: Number of videos per page (default: 15)
yt_dlp_args: Custom yt-dlp arguments for video format and extraction
network_share_path: Network share path for copying videos
default_network_subfolder: Default subfolder on network share

Usage Examples

# Search for videos
youtube-cli "python tutorial"

# Download a specific video
youtube-cli --download "https://www.youtube.com/watch?v=xyz123"

# View help
youtube-cli --help

# Check for yt-dlp updates
youtube-cli --check-update

# Update yt-dlp
youtube-cli --update

Dependencies

Python 3.6+
yt-dlp (for video downloading)
rich (for formatted console output)
requests (for API calls)

Installation

From Source

git clone https://github.com/yourusername/youtube-cli.git
cd youtube-cli
pip install -e .

Using pip

pip install youtube-cli

How It Works

Search: Users enter a search query to find YouTube videos
Display: Videos are shown 15 at a time with title, author, duration, and type
Navigation: Users can go to next page (n), search for new term (s), or quit (q)
Selection: Users can select videos by number to download
Download: Videos are downloaded using yt-dlp with progress indication
Tracking: Downloaded videos are tracked in an archive file

Special Features

Short Video Detection: Automatically detects and marks short videos with "(short)" prefix
Pagination: View 15 videos at a time with option for more
Multiple Download Locations: Choose from default locations or specify custom paths
Network Share Integration: Copy downloaded videos to network shares after download
Update Checking: Automatically checks for and updates yt-dlp when needed
Archive Tracking: Keeps track of already downloaded videos to avoid duplicates

Technical Details

Uses yt-dlp for all YouTube operations
Implements Rich library for beautiful console output
Supports both individual video and playlist downloads
Handles JavaScript challenges with remote components
Includes retry mechanisms for downloads
Cross-platform compatibility (macOS and Linux)

4.9 KiB Raw Blame History