https://github.com/oop7/YTSage
Modern YouTube downloader with a clean PySide6 interface. Download videos in any quality, extract audio, fetch subtitles, sponserBlock, and view video metadata. Built with yt-dlp for reliable performance.
https://github.com/oop7/YTSage
pyside6 python youtube-dl youtube-downloader yt-dlp yt-dlp-gui
Last synced: about 2 months ago
JSON representation
Modern YouTube downloader with a clean PySide6 interface. Download videos in any quality, extract audio, fetch subtitles, sponserBlock, and view video metadata. Built with yt-dlp for reliable performance.
- Host: GitHub
- URL: https://github.com/oop7/YTSage
- Owner: oop7
- License: mit
- Created: 2024-11-29T17:15:45.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-16T12:32:52.000Z (about 2 months ago)
- Last Synced: 2025-08-16T14:01:31.072Z (about 2 months ago)
- Topics: pyside6, python, youtube-dl, youtube-downloader, yt-dlp, yt-dlp-gui
- Language: Python
- Homepage:
- Size: 346 KB
- Stars: 1,950
- Watchers: 11
- Forks: 120
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎥 YTSage
[](https://badge.fury.io/py/ytsage)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](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 •
Features •
Usage •
Screenshots •
Troubleshooting •
Contributing
---
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
| Core Features | Advanced Features | Extra Features |
|-----------------------------------|-----------------------------------------|------------------------------------|
| 🎥 Format Table | 🚫 SponsorBlock Integration | 💾 Save Download Path |
| 🎵 Audio Extraction | 📝 Multi-Subtitle Select & Merge | 🔄 Auto-Update yt-dlp |
| ✨ Simple UI | 💾 Save Description | 🛠️ FFmpeg/yt-dlp Detection |
| 📋 Playlist Support | 🖼️ Save thumbnail | ⚙️ Custom Commands |
| 🖼️ Playlist Selector | 🚀 Speed Limiter | 🍪 Login with Cookies |
| 📑 Embed Chapters | ✂️ Trim Video Sections | |
### ⚡ Quick Install (Recommended)
Install YTSage from PyPI:
```bash
pip install ytsage
```
Then launch the app:
```bash
ytsage
```
### 📦 Pre-built Executables
- 🪟 **Windows:** YTSage-v<version>.exe / YTSage-v<version>-ffmpeg.exe (with FFmpeg)
- 🐧 **Linux:** YTSage-v<version>-amd64.deb / YTSage-v<version>-x86_64.AppImage
- 🍎 **macOS:** YTSage-v<version>-macOS.zip / YTSage-v<version>.dmg
> [👉 Download Latest Release](https://github.com/oop7/YTSage/releases/latest)
🛠️ Manual Installation from Source
### 1. Clone the Repository
```bash
git clone https://github.com/oop7/YTSage.git
cd YTSage
```
### 2. Install Dependencies
#### ⚡ With uv
```bash
uv pip install -r requirements.txt
```
#### 📦 Or with standard pip
```bash
pip install -r requirements.txt
```
### 3. Run the Application
```bash
python main.py
```
Main Interface
Playlist Download
Audio Format
Subtitle Options
🎯 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 merge
- Save thumbnail
- Remove sponsor segments
- Save description
- Embed chapters
6. **Select Output Directory**
7. **Click "Download"**
📋 Playlist Download
1. **Paste Playlist URL**
2. **Click "Analyze"**
3. **Select videos from the playlist selector (optional, defaults to all)**
4. **Choose desired format/quality**
5. **Click "Download"**
> 💡 The application automatically handles the download queue
🧰 Advanced Options
- **Quality Selection:** Choose the highest resolution for best quality
- **Subtitle Options:** Filter languages and embed into video
- **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
How to use it:
1. Extract cookies from your browser using an extension like [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file)
2. Copy the cookies in Netscape format
3. Create a file named `cookies.txt` and paste the cookies into it
4. Select the `cookies.txt` file in the app
- **Save Download Path:** Save the download path
- **Update yt-dlp:** Update yt-dlp
- **FFmpeg/yt-dlp Detection:** Automatically detect FFmpeg/yt-dlp
- **Trim Video:** Download only specific parts of a video by specifying time ranges (HH:MM:SS format)
Click to view common issues and solutions
- **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-ffmpeg.exe` file, which comes bundled with FFmpeg.
---
#### 🛡️ Windows Defender / Antivirus Warning
Some antivirus software may flag the `.exe` files as false positives. This is a **known limitation** of PyInstaller-packaged applications.
**Why this happens:**
- PyInstaller bundles Python runtime and libraries together
- Antivirus heuristics can misidentify packed executables as suspicious
- This affects many legitimate Python applications built with PyInstaller
**Safe alternatives:**
- ✅ **Use pip installation:** `pip install ytsage` (recommended)
- ✅ **Build from source**
- ✅ **Whitelist the application** in your antivirus software
> 📋 **Related Issues:** [#33](https://github.com/oop7/YTSage/issues/33) - This is a known PyInstaller limitation, not a security issue with YTSage itself.
---
#### 🍎 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`
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
📂 Project Structure
## 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
```
## ⭐️ Star History
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
Show Acknowledgments
A heartfelt thank you to everyone who has contributed to this project by opening an issue to suggest an improvement or report a bug.
Core Components
yt-dlp
Download Engine
FFmpeg
Media Processing
Libraries & Frameworks
PySide6
GUI Framework
Pillow
Image Processing
requests
HTTP Requests
packaging
Version & Package Handling
markdown
Markdown Rendering
pygame
Audio Playback
loguru
Logging
Assets & Contributors
New Notification 09 by Universfield
Notification Sound
viru185
Code Contributor
## ⚠️ 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)