# 🎥 YTSage YTSage Interface

[![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/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 • Features • Usage • Screenshots • Troubleshooting • Contributing

--- ## ❓ 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 ## ✨ Features

| 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 | |

## 🚀 Installation ### ⚡ 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

🛠️ 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 ```

## 📸 Screenshots


Main Interface	Playlist Download

Audio Format	Subtitle Options

## 📖 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 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)

## 🛠️ Troubleshooting

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. --- #### 🍎 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`

## 👥 Contributing 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)