yt-channel-archiver/README.md

# YouTube Channel Archiver

A cross-platform Python script for downloading and archiving entire YouTube channels using `yt-dlp`. Perfect for content preservation, offline viewing, and creating personal archives of your favorite channels.

## ✨ Features

- 🌍 **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

## 🚀 Quick Start

```bash
# Clone the repository
git clone <your-gitea-repo-url>
cd youtube-channel-archiver

# Run the script (it will install yt-dlp automatically if needed)
python youtube_archiver.py "https://www.youtube.com/@channelname"
```

## 📋 Requirements

- **Python 3.6+** 
- **pip** (for automatic yt-dlp installation)
- Internet connection

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

## 🔧 Installation

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

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

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

## 📖 Usage

### 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

The script creates an 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

The script automatically tracks downloaded videos in `download_archive.txt`. If a download is interrupted:

1. Simply run the same command again
2. Already downloaded videos will be skipped
3. New or failed videos will be downloaded

## ⚠ 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

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

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

**Network/download errors**
- The script 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 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 `--quality worst` to test with smaller files

## 🤝 Contributing

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

## 📄 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
- Inspired by the need for content preservation and offline access

---

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