Houmeres/SageTube
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Revamp README with improved structure and details

Browse Source 
Enhanced the README with a new 'Why YTSage?' section, improved installation instructions, added troubleshooting steps, and expanded feature descriptions. Updated project structure, acknowledgments, and star history sections for better clarity and navigation. Improved formatting and added advanced usage notes for cross-platform support.
This commit is contained in:
Your Name
2025-08-16 15:03:42 +03:00
parent d72685ca28
commit 989a070782
1 changed files with 224 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+213 -49
View File
@@ -7,22 +7,35 @@
[![PyPI version](https://img.shields.io/pypi/v/ytsage?color=dc2626&style=for-the-badge&logo=pypi&logoColor=white)](https://badge.fury.io/py/ytsage)
[![License: MIT](https://img.shields.io/badge/License-MIT-374151?style=for-the-badge&logo=opensource&logoColor=white)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-1f2937?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![Downloads](https://img.shields.io/pypi/dm/ytsage?color=4b5563&style=for-the-badge&logo=download&logoColor=white)](https://pepy.tech/project/ytsage)
[![Downloads](https://img.shields.io/pepy/dt/ytsage?color=4b5563&style=for-the-badge&label=downloads&logo=download&logoColor=white)](https://pepy.tech/project/ytsage)
[![GitHub Stars](https://img.shields.io/github/stars/oop7/YTSage?color=dc2626&style=for-the-badge&logo=github&logoColor=white)](https://github.com/oop7/YTSage/stargazers)
**A modern YouTube downloader with a clean PySide6 interface.**
Download videos in any quality, extract audio, fetch subtitles, and more.
[Installation](#installation) •
[Features](#features) •
[Usage](#usage) •
[Screenshots](#screenshots) •
[Contributing](#contributing)
<p align="center">
<a href="#installation" style="color: #D94343; text-decoration: none;">Installation</a> •
<a href="#features" style="color: #D94343; text-decoration: none;">Features</a> •
<a href="#usage" style="color: #D94343; text-decoration: none;">Usage</a> •
<a href="#screenshots" style="color: #D94343; text-decoration: none;">Screenshots</a> •
<a href="#troubleshooting" style="color: #D94343; text-decoration: none;">Troubleshooting</a> •
<a href="#contributing" style="color: #D94343; text-decoration: none;">Contributing</a>
</p>
</div>
---
<a id="why-ytsage"></a>
## ❓ Why YTSage?
YTSage is designed for users who want a **simple yet powerful YouTube downloader**. Unlike other tools, it offers:
- A clean, modern PySide6 interface
- One-click downloads for video, audio, and subtitles
- Advanced features like SponsorBlock, subtitle merging, and playlist selection
- Cross-platform support and easy installation
<a id="features"></a>
## ✨ Features
@@ -35,46 +48,64 @@ Download videos in any quality, extract audio, fetch subtitles, and more.
| ✨ Simple UI | 💾 Save Description | 🛠️ FFmpeg/yt-dlp Detection |
| 📋 Playlist Support | 🖼️ Save thumbnail | ⚙️ Custom Commands |
| 🖼️ Playlist Selector | 🚀 Speed Limiter | 🍪 Login with Cookies |
| | ✂️ Trim Video Sections | |
| 📑 Embed Chapters | ✂️ Trim Video Sections | |
</div>
<a id="installation"></a>
## 🚀 Installation
### Quick Install (Recommended)
### ⚡ Quick Install (Recommended)
Install YTSage from PyPI:
```bash
pip install ytsage
```
Then launch the app:
```bash
# Run the application
ytsage
```
### 📦 Other Installation Methods
### 📦 Pre-built Executables
### Pre-built Executables
- 🪟 Windows: `YTSage.exe`
- 🪟 Windows: `YTSage-ffmpeg.exe` (Includes FFmpeg)
- 🐧 Linux: `YTSage_{version}_amd64.deb`
- 🐧 Linux: `YTSage-x86_64.AppImage`
- 🍎 macOS: `YTSage-macOS-app.zip`
- 🍎 macOS: `YTSage-{version}.dmg`
- 🪟 **Windows:** <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;.exe</code> / <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;-ffmpeg.exe</code> (with FFmpeg)
- 🐧 **Linux:** <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;-amd64.deb</code> / <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;-x86_64.AppImage</code>
- 🍎 **macOS:** <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;-macOS.zip</code> / <code style="background-color: #333842; color: #C9D1D9; padding: 3px 6px; border-radius: 6px; font-family: monospace;">YTSage-v&lt;version&gt;.dmg</code>
> <a href="https://github.com/oop7/YTSage/releases/latest" style="color: #D94343; text-decoration: none;">
<span>👉</span> <span style="text-decoration: underline;">Download Latest Release</span>
</a>
<details>
<summary>🛠️ Manual Installation from Source</summary>
### 1. Clone the Repository
```bash
# Clone repository
git clone https://github.com/oop7/YTSage.git
# Navigate to directory
cd YTSage
```
# Install dependencies
### 2. Install Dependencies
#### ⚡ With uv
```bash
uv pip install -r requirements.txt
```
#### 📦 Or with standard pip
```bash
pip install -r requirements.txt
```
# Run application
### 3. Run the Application
```bash
python main.py
```
@@ -122,6 +153,7 @@ python main.py
- Save thumbnail
- Remove sponsor segments
- Save description
- Embed chapters
6. **Select Output Directory**
7. **Click "Download"**
@@ -148,6 +180,7 @@ python main.py
- **Custom Commands:** Access advanced yt-dlp features
- **Save Description:** Save the description of the video
- **Save Thumbnail:** Save the thumbnail of the video
- **Embed Chapters:** Embed chapter markers as metadata in the downloaded video file for compatible video players
- **Remove Sponsor Segments:** Remove sponsor segments from the video
- **Speed Limiter:** Limit the download speed
- **Login with Cookies:** Login to YouTube using cookies to access private content
@@ -159,29 +192,44 @@ python main.py
- **Save Download Path:** Save the download path
- **Update yt-dlp:** Update yt-dlp
- **FFmpeg/yt-dlp Detection:** Automatically detect FFmpeg/yt-dlp
- **Custom Commands:** Access advanced yt-dlp features
- **Trim Video:** Download only specific parts of a video by specifying time ranges (HH:MM:SS format)
</details>
<a id="troubleshooting"></a>
## 🛠️ Troubleshooting
<details>
<summary>🛠️ Troubleshooting</summary>
<summary>Click to view common issues and solutions</summary>
- **Format table not displaying:** Update yt-dlp to the latest version
- **Download fails:** Check your internet connection and ensure the video is available
- **Audio extraction issues:** Verify FFmpeg is properly installed
- **Format table not displaying:** Update yt-dlp to the latest version.
- **Download fails:** Check your internet connection and ensure the video is available.
- **Separate video and audio files after download:** This happens when FFmpeg is missing or not detected. YTSage requires FFmpeg to merge high-quality video and audio streams.
- **Solution:** Ensure FFmpeg is installed and accessible in your system's PATH. For Windows users, the easiest option is to download the `YTSage-v<version>-ffmpeg.exe` file, which comes bundled with FFmpeg.
---
#### 🍎 macOS: "App is damaged and can’t be opened"
If you see this error on macOS Sonoma or newer, you need to remove the quarantine attribute.
1. **Open Terminal** (you can find it using Spotlight).
2. **Type the following command** but **do not** press Enter yet. Make sure to include the space at the end:
```bash
xattr -d com.apple.quarantine
```
3. **Drag the `YTSage.app` file** from your Finder window and drop it directly into the Terminal window. This will automatically paste the correct file path.
4. **Press Enter** to run the command.
5. **Try opening YTSage.app again.** It should now launch correctly.
---
#### **Configuration Locations (Advanced)**
- **Windows:** `%LOCALAPPDATA%\YTSage`
- **macOS:** `~/Library/Application Support/YTSage`
- **Linux:** `~/.local/share/YTSage`
</details>
## 🧩 Requirements
- **Python:** 3.7 or higher
- **GUI Framework:** PySide6
- **Download Engine:** yt-dlp
- **Media Processing:** FFmpeg
- **Additional Libraries:** Pillow, requests, packaging, markdown, pygame
<a id="contributing"></a>
## 👥 Contributing
@@ -202,11 +250,69 @@ We welcome contributions! Here's how you can help:
```
5. 🔄 Open a Pull Request
## 📊 Star History
<details>
<summary>📂 Project Structure</summary>
## YTSage - Project Structure
This document describes the organized folder structure of YTSage.
### 📁 Project Structure
```
YTSage-main/
├── 📁 assets/ # Static assets and resources
│ ├── 📁 Icon/ # Application icons
│ │ └── icon.png
│ └── 📁 sound/ # Audio files
│ └── notification.mp3
│
├── 📁 src/ # Source code
│ ├── 📁 core/ # Core business logic
│ │ ├── __init__.py # Core package init
│ │ ├── ytsage_downloader.py # Download functionality
│ │ ├── ytsage_ffmpeg.py # FFmpeg integration
│ │ ├── ytsage_style.py # UI styling
│ │ ├── ytsage_utils.py # Utility functions
│ │ └── ytsage_yt_dlp.py # yt-dlp integration
│ │
│ ├── 📁 gui/ # User interface components
│ │ ├── 📁 dialogs/ # Dialog classes
│ │ │ ├── __init__.py # Dialogs package init (re-exports all)
│ │ │ ├── ytsage_dialogs_base.py # Basic dialogs (Log, About)
│ │ │ ├── ytsage_dialogs_custom.py # Custom functionality dialogs
│ │ │ ├── ytsage_dialogs_ffmpeg.py # FFmpeg-related dialogs
│ │ │ ├── ytsage_dialogs_selection.py # Selection dialogs
│ │ │ ├── ytsage_dialogs_settings.py # Settings dialogs
│ │ │ └── ytsage_dialogs_update.py # Update dialogs
│ │ │
│ │ ├── __init__.py # GUI package init
│ │ ├── ytsage_gui_dialogs.py # Dialog aggregator (backward compatibility)
│ │ ├── ytsage_gui_format_table.py # Format table functionality
│ │ ├── ytsage_gui_main.py # Main application window
│ │ └── ytsage_gui_video_info.py # Video information display
│ │
│ └── __init__.py # Main package init
│
├── 📄 main.py # Application entry point
├── 📄 requirements.txt # Python dependencies
├── 📄 README.md # Project documentation
├── 📄 LICENSE # License file
└── 📄 .gitignore # Git ignore rules
```
</details>
## ⭐️ Star History
<div align="center">
[![Star History Chart](https://api.star-history.com/svg?repos=oop7/YTSage&type=Date)](https://star-history.com/#oop7/YTSage&Date)
<a href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history?repo_id=896163475" target="_blank" style="display: block" align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=896163475&image_size=auto&color_scheme=dark" width="721" height="auto">
<img alt="Star History of oop7/YTSage" src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-history/thumbnail.png?repo_id=896163475&image_size=auto&color_scheme=light" width="721" height="auto">
</picture>
</a>
</div>
@@ -216,23 +322,81 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
## 🙏 Acknowledgments
<details>
<summary>Show Acknowledgments</summary>
<div align="center">
| 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 |
| [requests](https://requests.readthedocs.io/) | HTTP Requests |
| [packaging](https://packaging.python.org/) | Packaging |
| [markdown](https://python-markdown.github.io/) | Markdown Processing |
| [pygame](https://www.pygame.org/) | Audio Playback |
| [New Notification 09 by Universfield](https://pixabay.com/sound-effects/new-notification-09-352705/) | Notification Sound |
<style>
body { font-family: sans-serif; color: #ddd; }
table { border-collapse: collapse; width: 100%; }
td { text-align: left; padding: 8px; vertical-align: top; border-bottom: 1px solid #444; }
a { color: #3e8acc; text-decoration: none; }
a:hover { text-decoration: underline; }
.section th {
font-size: 1.1em;
text-align: left;
padding: 12px 8px 5px 0px;
border-bottom: 1px solid #555;
}
</style>
<p>A heartfelt thank you to everyone who has contributed to this project by opening an issue to suggest an improvement or report a bug.</p>
<table>
<tr class="section"><th colspan="2">Core Components</th></tr>
<tr>
<td width="35%"><a href="https://github.com/yt-dlp/yt-dlp">yt-dlp</a></td>
<td>Download Engine</td>
</tr>
<tr>
<td><a href="https://ffmpeg.org/">FFmpeg</a></td>
<td>Media Processing</td>
</tr>
<tr class="section"><th colspan="2">Libraries & Frameworks</th></tr>
<tr>
<td><a href="https://wiki.qt.io/Qt_for_Python">PySide6</a></td>
<td>GUI Framework</td>
</tr>
<tr>
<td><a href="https://python-pillow.org/">Pillow</a></td>
<td>Image Processing</td>
</tr>
<tr>
<td><a href="https://requests.readthedocs.io/">requests</a></td>
<td>HTTP Requests</td>
</tr>
<tr>
<td><a href="https://packaging.python.org/">packaging</a></td>
<td>Version & Package Handling</td>
</tr>
<tr>
<td><a href="https://python-markdown.github.io/">markdown</a></td>
<td>Markdown Rendering</td>
</tr>
<tr>
<td><a href="https://www.pygame.org/">pygame</a></td>
<td>Audio Playback</td>
</tr>
<tr>
<td><a href="https://github.com/Delgan/loguru">loguru</a></td>
<td>Logging</td>
</tr>
<tr class="section"><th colspan="2">Assets & Contributors</th></tr>
<tr>
<td><a href="https://pixabay.com/sound-effects/new-notification-09-352705/">New Notification 09 by Universfield</a></td>
<td>Notification Sound</td>
</tr>
<tr>
<td><a href="https://github.com/viru185">viru185</a></td>
<td>Code Contributor</td>
</tr>
</table>
</div>
</details>
## ⚠️ Disclaimer
This tool is for personal use only. Please respect YouTube's terms of service and content creators' rights.