YTSage

<div align="center"> <img src="branding\svg\ytsage-wordmark.svg" width="400" alt="ytsage-wordmark"> <img src="branding\screenshots\main.png" width="800" alt="YTSage Interface"/>

A modern YouTube downloader with a clean PySide6 interface.
Download videos in any quality, extract audio, fetch subtitles, and more.

<p align="center"> <a href="#installation">Installation</a> • <a href="#features">Features</a> • <a href="#usage">Usage</a> • <a href="#screenshots">Screenshots</a> • <a href="#troubleshooting">Troubleshooting</a> • <a href="#contributing">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

<div align="center">

| Core Features | Advanced Features | Extra Features | |-----------------------------------|-----------------------------------------|------------------------------------| | 🎥 Format Table | 🚫 SponsorBlock Integration | 🎞️ FPS/HDR Display | | 🎵 Audio Extraction | 📝 Multi-Subtitle Select & Merge | 🔄 Auto-Update yt-dlp | | ✨ Simple UI | 💾 Save Description & Thumbnail | 🛠️ FFmpeg/yt-dlp/Deno Detection | | 📋 Playlist Support & Selector | 🚀 Speed Limiter | ⚙️ Custom Commands | | 📑 Embed Chapters | ✂️ Trim Video Sections | 🍪 Login with Cookies | | 📜 Download History | 🔄 Release Channel Selection | 🌐 Proxy Support | | 🎚️ Audio Format Conversion | 🎬 Video Format Settings | 🆙 Built-in Updater Tab |

</div>

<a id="installation"></a>

🚀 Installation

⚡ Quick Install (Recommended)

Install YTSage from PyPI:

pip install ytsage

<details> <summary>🔄 Update an existing installation</summary>

pip install --upgrade ytsage

</details>

Then launch the app:

ytsage

📦 Pre-built Executables

👉 Download Latest Release

🪟 Windows

| Format | Description | |--------|-------------| | | Standard installer | | | With FFmpeg bundled | | | Portable version, no installation required | | | Portable with FFmpeg, zipped |

<details> <summary>🛠️ Installation Steps</summary>

1. EXE Installer (.exe): Double-click the file and follow the setup wizard.
2. Portable Version (.zip): Extract the archive to your desired location and run ytsage.exe.
3. FFmpeg Bundled: Choose the FFmpeg bundled versions if you don't have FFmpeg installed on your system.

</details>

🐧 Linux

| Format | Description | |--------|-------------| | | Debian package | | | AppImage, portable | | | RPM package | | | Flatpak Bundle |

<details> <summary>🛠️ Installation Steps</summary>

• DEB (.deb):

  sudo dpkg -i ytsage_*.deb
  sudo apt-get install -f # Fix missing dependencies if any
  

• RPM (.rpm):

  sudo rpm -i ytsage-*.rpm
  

• AppImage (.AppImage):

  chmod +x YTSage-*.AppImage
  ./YTSage-*.AppImage
  

• Flatpak: Follow instructions on Flathub or run:

  flatpak install flathub io.github.oop7.ytsage
  

</details>

🍎 macOS

| Format | Description | |--------|-------------| | | Zipped application for Apple Silicon | | | Disk image installer for Apple Silicon |

<details> <summary>🛠️ Installation Steps</summary>

• DMG Installer (.dmg): Double-click to mount, then drag YTSage.app into your Applications folder.
• App Archive (.zip): Extract the zip and move YTSage.app to your Applications folder.

Note: If you encounter an "App is damaged" error, see the macOS troubleshooting section below.

</details>

---

<details> <summary>💻 Manual Installation from Source</summary>

1. Clone the Repository

git clone https://github.com/oop7/YTSage.git
cd YTSage

2. Install Dependencies

⚡ With uv

uv pip install .

📦 Or with standard pip

pip install .

3. Run the Application

python -m ytsage.main

</details>

<a id="screenshots"></a>

📸 Screenshots

<div align="center"> <table> <tr> <td><img src="branding\screenshots\Download-Settings.png" alt="Download Settings" width="400"/></td> <td><img src="branding\screenshots\playlist.png" alt="Playlist Download" width="400"/></td> </tr> <tr> <td align="center"><em>Download Settings</em></td> <td align="center"><em>Playlist Download</em></td> </tr> <tr> <td><img src="branding\screenshots\audio_format.png" alt="Audio Format Selection with Save Thumbnail" width="400"/></td> <td><img src="branding\screenshots\Custom-Option.png" alt="Custom Options" width="400"/></td> </tr> <tr> <td align="center"><em>Audio Format</em></td> <td align="center"><em>Custom Options</em></td> </tr> </table> </div>

<a id="usage"></a>

📖 Usage

<details> <summary>🎯 Basic Usage</summary>

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"

💡 The default download directory is the user's "Downloads" folder.

</details> <details> <summary>📋 Playlist Download</summary>

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

</details> <details> <summary>🧰 Advanced Options</summary>

• Subtitle Options: Filter languages and embed into video file
• Subtitle Merge: Merge subtitles into video file for hardcoded subtitles
• Custom Commands: Access advanced yt-dlp features via command line arguments
• Save Description: Save the description of the video as a text file
• Save Thumbnail: Save the thumbnail of the video as an image file
• 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 using SponsorBlock
• Speed Limiter: Limit the download speed (e.g., 500K for 500 KB/s)
• Login with Cookies: Login to YouTube using cookies to access private content
  How to use it:
  1. Recommended: Use the built-in "Extract cookies from browser" option in the app. Select your browser (Chrome, Firefox, etc.) and then select Profile (optional).
  2. Alternatively, extract cookies manually: a. Extract cookies from your browser using an extension like cookie-editor b. Copy the cookies