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

# 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

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:

pip install yt-dlp

📖 Usage

Basic Usage

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

# 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 - the excellent YouTube downloading library
• Inspired by the need for content preservation and offline access

---

⭐ Star this repository if you find it useful!