From e9d3b9e43faff03280edb950862973031359759a Mon Sep 17 00:00:00 2001 From: Kevin Thompson Date: Wed, 23 Jul 2025 14:46:05 -0500 Subject: [PATCH] Update README to reflect GUI --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 69 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 43fbe2f..7179e8b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # 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. +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 @@ -12,36 +13,45 @@ A cross-platform Python script for downloading and archiving entire YouTube chan - 📝 **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 cd youtube-channel-archiver -# Run the script (it will install yt-dlp automatically if needed) +# 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 script will automatically install `yt-dlp` if it's not already available on your system. +The application 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! +Download both `youtube_archiver_gui.py` and `youtube_archiver.py` and run directly - no additional setup required! ### Option 2: Clone Repository ```bash git clone cd youtube-channel-archiver -chmod +x youtube_archiver.py # On Unix systems +chmod +x *.py # On Unix systems ``` ### Option 3: Manual yt-dlp Installation @@ -52,19 +62,45 @@ pip install yt-dlp ## 📖 Usage -### Basic 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 +#### 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 +#### Command Line Options | Option | Description | Default | |--------|-------------|---------| @@ -75,7 +111,7 @@ python youtube_archiver.py "CHANNEL_URL" | `--no-metadata` | Skip metadata files | False | | `--help`, `-h` | Show help message | - | -### Examples +#### Examples ```bash # Download all videos in best quality @@ -93,7 +129,7 @@ python youtube_archiver.py "https://www.youtube.com/@newschannel" --no-thumbnail ## 📁 Output Structure -The script creates an organized directory structure: +Both interfaces create the same organized directory structure: ``` Channel_Name/ @@ -115,12 +151,22 @@ Channel_Name/ ## 🔄 Resuming Downloads -The script automatically tracks downloaded videos in `download_archive.txt`. If a download is interrupted: +Both interfaces automatically track downloaded videos in `download_archive.txt`. If a download is interrupted: -1. Simply run the same command again +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 @@ -132,16 +178,20 @@ The script automatically tracks downloaded videos in `download_archive.txt`. If ### 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** -- The script should install it automatically +- Both interfaces should install it automatically - If not, manually install: `pip install yt-dlp` **Permission denied errors** -- On Unix systems: `chmod +x youtube_archiver.py` +- On Unix systems: `chmod +x *.py` - Run with appropriate permissions **Network/download errors** -- The script continues on errors - check the output for specific failures +- 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** @@ -151,10 +201,10 @@ The script automatically tracks downloaded videos in `download_archive.txt`. If ### Getting Help If you encounter issues: -1. Check the console output for specific error messages +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 `--quality worst` to test with smaller files +4. Try running with lower quality settings to test with smaller files ## 🤝 Contributing @@ -163,6 +213,7 @@ Contributions are welcome! Please feel free to: - Suggest features - Submit pull requests - Improve documentation +- Add new GUI features ## 📄 License @@ -171,6 +222,7 @@ This project is provided as-is for educational and personal archiving purposes. ## 🙏 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 ---