yt-channel-archiver/README.md

# YouTube Channel Archiver

A cross-platform Python application for downloading and archiving entire YouTube channels using `yt-dlp`. Features both a graphical user interface (GUI) and command-line interface (CLI) for maximum flexibility. Perfect for content preservation, offline viewing, and creating personal archives of your favorite channels.

## ✨ Features

- 🖥️ **Dual Interface**: Easy-to-use GUI and powerful command-line interface
- 🌍 **Cross-platform**: Works on macOS, Linux, and Windows
- 📦 **Automatic setup**: Installs `yt-dlp` dependency automatically if needed
- 📁 **Smart organization**: Creates channel-specific folders with date-organized files
- 🔄 **Resume support**: Tracks downloaded videos to avoid duplicates and resume interrupted downloads
- 🎥 **Quality options**: Choose from multiple video qualities or audio-only downloads
- 📝 **Metadata preservation**: Downloads video descriptions, info, and thumbnails
- ⚡ **Error resilient**: Continues downloading even if individual videos fail
- 🎯 **Flexible input**: Supports various YouTube URL formats and channel IDs
- 🛑 **Stoppable downloads**: Cancel downloads anytime with proper cleanup

## 🚀 Quick Start

### GUI Version (Recommended for beginners)
```bash
# Clone the repository
git clone <your-gitea-repo-url>
cd youtube-channel-archiver

# Run the GUI (it will install yt-dlp automatically if needed)
python youtube_archiver_gui.py
```

### Command Line Version
```bash
# Run the CLI script directly
python youtube_archiver.py "https://www.youtube.com/@channelname"
```

## 📋 Requirements

- **Python 3.6+** 
- **tkinter** (usually included with Python - needed for GUI only)
- **pip** (for automatic yt-dlp installation)
- Internet connection

The application will automatically install `yt-dlp` if it's not already available on your system.

## 🔧 Installation

### Option 1: Direct Download
Download both `youtube_archiver_gui.py` and `youtube_archiver.py` and run directly - no additional setup required!

### Option 2: Clone Repository
```bash
git clone <your-repo-url>
cd youtube-channel-archiver
chmod +x *.py  # On Unix systems
```

### Option 3: Manual yt-dlp Installation
If you prefer to install yt-dlp manually:
```bash
pip install yt-dlp
```

## 📖 Usage

### GUI Interface

1. **Launch the GUI:**
   ```bash
   python youtube_archiver_gui.py
   ```

2. **Fill in the details:**
   - Enter the YouTube channel URL
   - Choose an output directory (or use default)
   - Adjust quality and options as needed

3. **Start downloading:**
   - Click "Download Channel"
   - Monitor progress in real-time
   - Click "Stop Download" to cancel if needed

#### GUI Features:
- **Live Progress**: Real-time output and progress indication
- **Quality Selection**: Dropdown menu for video quality
- **Options**: Checkboxes for audio-only, thumbnails, and metadata
- **Directory Browser**: Easy folder selection
- **Status Updates**: Clear feedback on download status

### Command Line Interface

#### Basic Usage
```bash
python youtube_archiver.py "CHANNEL_URL"
```

#### Supported URL Formats
- `https://www.youtube.com/@channelname`
- `https://www.youtube.com/c/channelname`
- `https://www.youtube.com/user/username`
- `https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxx`
- `UCxxxxxxxxxxxxxxxxxxx` (Channel ID only)

#### Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--output`, `-o` | Output directory | Current directory |
| `--quality`, `-q` | Video quality (`best`, `worst`, `720p`, `1080p`, `480p`) | `best` |
| `--audio-only`, `-a` | Download audio only | False |
| `--no-thumbnails` | Skip thumbnail downloads | False |
| `--no-metadata` | Skip metadata files | False |
| `--help`, `-h` | Show help message | - |

#### Examples

```bash
# Download all videos in best quality
python youtube_archiver.py "https://www.youtube.com/@examplechannel"

# Download to specific directory with 720p quality
python youtube_archiver.py "https://www.youtube.com/@examplechannel" --output ./Downloads --quality 720p

# Audio-only downloads
python youtube_archiver.py "https://www.youtube.com/@musicchannel" --audio-only

# Minimal download (no thumbnails or metadata)
python youtube_archiver.py "https://www.youtube.com/@newschannel" --no-thumbnails --no-metadata
```

## 📁 Output Structure

Both interfaces create the same organized directory structure:

```
Channel_Name/
├── download_archive.txt          # Tracks downloaded videos
├── 20240115 - Video Title 1.mp4
├── 20240115 - Video Title 1.info.json
├── 20240115 - Video Title 1.description
├── 20240115 - Video Title 1.webp
├── 20240116 - Video Title 2.mp4
└── ...
```

### File Types
- **`.mp4/.webm/etc`**: Video files
- **`.info.json`**: Video metadata (duration, views, description, etc.)
- **`.description`**: Video description text
- **`.webp/.jpg`**: Thumbnails
- **`download_archive.txt`**: List of downloaded video IDs (prevents re-downloading)

## 🔄 Resuming Downloads

Both interfaces automatically track downloaded videos in `download_archive.txt`. If a download is interrupted:

1. Simply restart the application/command
2. Already downloaded videos will be skipped
3. New or failed videos will be downloaded

## 🖼️ GUI Screenshots

The GUI provides an intuitive interface with:
- **Channel URL Input**: Easy copy-paste of YouTube URLs
- **Directory Selection**: Browse button for choosing download location
- **Quality Options**: Dropdown for video quality selection
- **Download Options**: Checkboxes for audio-only, thumbnails, and metadata
- **Progress Monitoring**: Real-time download progress and output
- **Status Bar**: Current operation status

## ⚠ Legal Considerations

- **Respect copyright**: Only download content you have permission to archive
- **Personal use**: This tool is intended for personal archiving and offline viewing
- **YouTube ToS**: Be aware of YouTube's Terms of Service regarding content downloading
- **Fair use**: Consider fair use principles in your jurisdiction

## 🛠 Troubleshooting

### Common Issues

**GUI won't start**
- Ensure Python includes tkinter: `python -c "import tkinter"`
- On some Linux distributions: `sudo apt-get install python3-tk`

**"yt-dlp not found" error**
- Both interfaces should install it automatically
- If not, manually install: `pip install yt-dlp`

**Permission denied errors**
- On Unix systems: `chmod +x *.py`
- Run with appropriate permissions

**Network/download errors**
- The application continues on errors - check the output for specific failures
- Some videos may be unavailable due to geographic restrictions or privacy settings

**Python not found**
- Ensure Python 3.6+ is installed and in your PATH
- Try `python3` instead of `python` on some systems

### Getting Help

If you encounter issues:
1. Check the console/GUI output for specific error messages
2. Ensure you have a stable internet connection
3. Verify the channel URL is correct and publicly accessible
4. Try running with lower quality settings to test with smaller files

## 🤝 Contributing

Contributions are welcome! Please feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation
- Add new GUI features

## 📄 License

This project is provided as-is for educational and personal archiving purposes. Please ensure your use complies with applicable laws and YouTube's Terms of Service.

## 🙏 Acknowledgments

- Built using [yt-dlp](https://github.com/yt-dlp/yt-dlp) - the excellent YouTube downloading library
- GUI built with Python's built-in tkinter library for maximum compatibility
- Inspired by the need for content preservation and offline access

---

**⭐ Star this repository if you find it useful!**