# 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
```bash
# 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
```bash
git clone https://github.com/yourusername/youtube-cli.git
cd youtube-cli
pip install -e .
```

### Using pip
```bash
pip install youtube-cli
```

## How It Works
1. **Search**: Users enter a search query to find YouTube videos
2. **Display**: Videos are shown 15 at a time with title, author, duration, and type
3. **Navigation**: Users can go to next page (n), search for new term (s), or quit (q)
4. **Selection**: Users can select videos by number to download
5. **Download**: Videos are downloaded using yt-dlp with progress indication
6. **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)