From 8d0de0dcd5c162a84d85687d39ee314e90dcd2a6 Mon Sep 17 00:00:00 2001 From: Muhamed <110548351+oop7@users.noreply.github.com> Date: Fri, 21 Feb 2025 19:03:24 +0200 Subject: [PATCH] update README --- README.md | 281 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 164 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index 3bd7bd0..a378362 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,198 @@ -# YTSage +
-A modern YouTube downloader with a clean PySide6 interface. Download videos in any quality, extract audio, fetch subtitles (including auto-generated), and view video metadata. Built with yt-dlp for reliable performance. +# đŸŽĨ YTSage -## Screenshots +YTSage Interface -### Main Interface +[![PyPI version](https://badge.fury.io/py/YTSage.svg)](https://badge.fury.io/py/YTSage) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/) +[![Downloads](https://pepy.tech/badge/ytsage)](https://pepy.tech/project/ytsage) -![Main Interface](https://github.com/user-attachments/assets/04959c77-695b-4a69-b8fc-7103fe530236) +**A modern YouTube downloader with a clean PySide6 interface.** +Download videos in any quality, extract audio, fetch subtitles, and more. -*Main interface with video metadata and thumbnail preview* +[Installation](#installation) â€ĸ +[Features](#features) â€ĸ +[Usage](#usage) â€ĸ +[Screenshots](#screenshots) â€ĸ +[Contributing](#contributing) -### Playlist download support with auto-detection +
-![Playlist download](https://github.com/user-attachments/assets/537b8553-9657-42b2-a452-051c4cb2e32a) +--- -*Playlist download with auto-detection* -### Audio Format Selection +## ✨ Features -![Audio Format](https://github.com/user-attachments/assets/51a6a613-6c97-4581-b728-38c91c0b2d24) +
-*Smart format selection with quality options* +| Core Features | Advanced Features | Extra Features | +|--------------|-------------------|----------------| +| đŸŽĨ Smart Video Quality | đŸšĢ SponsorBlock Integration | 💾 Save Download Path | +| đŸŽĩ Audio Extraction | 📝 Subtitle Support & Filtering | 🔄 Auto-Updates | +| 📊 Real-time Progress | ⚙ī¸ Custom Commands | 🛠ī¸ FFmpeg Tools | +| 📋 Playlist Support | đŸ–ŧī¸ Thumbnail Management | ⚠ī¸ Error Handling | -### Subtitle Options +
-![Subtitle Options](https://github.com/user-attachments/assets/4e8c686f-98e2-435a-add8-758e317b56fe) +## 🚀 Installation -*Support for both manual and auto-generated subtitles* - -## Features - -- đŸŽĨ Smart video quality selection with automatic audio merging -- đŸŽĩ Audio-only extraction -- 📝 Manual and auto-generated subtitle support with language filtering -- ℹī¸ Video metadata display (views, upload date, duration) -- đŸ–ŧī¸ Thumbnail preview -- 🎨 Clean, modern PySide6 interface -- 🚀 Built on yt-dlp for robust downloading -- ⏯ī¸ Download control (pause, resume, and cancel) -- 📊 Real-time progress tracking (speed, ETA, percentage) -- đŸ–ŧī¸ Save Thumbnail -- ⚙ī¸ Custom yt-dlp command support with real-time output -- 📋 Playlist download support with auto-detection -- 💾 Save download path memory -- 🔄 One-click yt-dlp updater -- ⚠ī¸ User-friendly error messages -- 🛠ī¸ FFmpeg installation checker and guide -- 📎 Quick URL paste button -- đŸŽ¯ Smart format filtering (Video/Audio) - -## Download - -You can download the latest executable from the [Releases](https://github.com/oop7/YTSage/releases) page. - -### Pre-built Executables -- Windows: `YTSage.exe` -- macOS: `YTSage.dmg` -- Linux: `YTSage.AppImage` -- No installation required - just download and run! - -### PyPI Package -You can also install YTSage directly from PyPI: +### Quick Install (Recommended) ```bash pip install YTSage ``` - - -### Installation - -1. Clone the repository: ```bash +# Run the application +ytsage +``` + +
+đŸ“Ļ Other Installation Methods + +### Pre-built Executables +- đŸĒŸ Windows: `YTSage.exe` +- 🍎 macOS: `YTSage.dmg` +- 🐧 Linux: `YTSage.AppImage` + +### Manual Installation +```bash +# Clone repository git clone https://github.com/oop7/YTSage.git +# Navigate to directory cd YTSage -``` -2. Install the required dependencies: -```bash + +# Install dependencies pip install -r requirements.txt + +# Run application +python main.py ``` -3. Run the application: -```bash -python YTSage.py +
+ +## 📸 Screenshots + +
+ + + + + + + + + + + + + + + + + +
Main InterfacePlaylist Download
Main InterfacePlaylist Download
Audio FormatSubtitle Options
Audio Format Selection with Save ThumbnailSubtitle Options merged with Remove Sponsor Segments
+
+ +## 📖 Usage + +
+đŸŽ¯ Basic Usage + +1. **Launch YTSage** +2. **Paste YouTube URL** (or use "Paste URL" button) +3. **Click "Analyze"** +4. **Select Format:** + - `Video` for video downloads + - `Audio Only` for audio extraction +5. **Choose Options:** + - Enable subtitles & select language + - Enable subtitle embedding + - Save thumbnail + - Remove sponsor segments +6. **Select Output Directory** +7. **Click "Download"** + +
+ +
+📋 Playlist Download + +1. **Paste Playlist URL** +2. **Click "Analyze"** +3. **Select Best Quality** +4. **Click "Download"** + +> 💡 The application automatically handles the download queue + +
+ +
+⚙ī¸ Advanced Options + +- **Quality Selection:** Choose highest resolution for best quality +- **Subtitle Options:** Filter languages and embed into video +- **SponsorBlock:** Automatically skip promotional content +- **Custom Commands:** Access advanced yt-dlp features +- **Output Directory:** Ensure sufficient storage space + +
+ +## 🛠ī¸ Requirements + +```plaintext +Python 3.7+ +PySide6 +yt-dlp +Pillow +requests +FFmpeg +packaging ``` -# Usage +## đŸ‘Ĩ Contributing -1. **Run the application** -2. **Paste a YouTube URL** into the input field -3. **Click "Analyze"** to load video information -4. **Select your desired format**: - - Choose **"Video"** for video downloads (will automatically merge with best audio) - - Choose **"Audio Only"** for audio extraction -5. **Enable subtitle download** if needed -6. **Select the output directory** -7. **Click "Download"** to start +We welcome contributions! Here's how you can help: ---- +1. 🍴 Fork the repository +2. đŸŒŋ Create your feature branch: + ```bash + git checkout -b feature/AmazingFeature + ``` +3. 💾 Commit your changes: + ```bash + git commit -m 'Add some AmazingFeature' + ``` +4. 📤 Push to the branch: + ```bash + git push origin feature/AmazingFeature + ``` +5. 🔄 Open a Pull Request -### Additional Steps for Playlist Download: - -1. **Paste the Playlist URL**: Instead of a single video URL, paste the URL of the entire YouTube playlist into the input field. -2. **Analyze the Playlist**: Click "Analyze" to load information for all videos in the playlist. -3. **Select Best Quality**: Ensure that the best quality option is selected for both video and audio. -4. **Download the Playlist**: Click "Download" to start downloading all videos in the playlist. The application should automatically handle the download queue. - ---- - -### Note: -- **Best Quality**: Always select the highest available resolution (e.g., 1080p, 4K) for video and the best audio format (e.g., 320kbps) for the best experience. -- **Subtitle Download**: If you need subtitles, enable this option before starting the download. -- **Output Directory**: Choose a directory with enough storage space, especially for large playlists. - -By following these steps, you can efficiently download entire playlists in the best quality without encountering issues. - -## Requirements - -- Python 3.7+ -- PySide6 -- yt-dlp -- Pillow -- requests -- FFmpeg -- packaging - -## Contributing - -Contributions are welcome! Please feel free to submit a Pull Request. - -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request - -## License +## 📜 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -## Acknowledgments +## 🙏 Acknowledgments -- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for the powerful downloading engine -- [PySide6](https://en.wikipedia.org/wiki/PySide) for the GUI framework -- [FFmpeg](https://ffmpeg.org/) for the audio and video processing -- [Pillow](https://pypi.org/project/Pillow/) for the image processing -- [requests](https://pypi.org/project/requests/) for the HTTP requests -- [packaging](https://pypi.org/project/packaging/) for the package management -- [PyInstaller](https://pypi.org/project/PyInstaller/) for the executable creation +
-## Disclaimer +| Technology | Purpose | +|------------|---------| +| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Download Engine | +| [PySide6](https://wiki.qt.io/Qt_for_Python) | GUI Framework | +| [FFmpeg](https://ffmpeg.org/) | Media Processing | +| [Pillow](https://python-pillow.org/) | Image Processing | + +
+ +## ⚠ī¸ Disclaimer This tool is for personal use only. Please respect YouTube's terms of service and content creators' rights. + +--- + +
+ +Made with ❤ī¸ by [oop7](https://github.com/oop7) + +