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

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

🌍 README Languages

English: EN | Arabic: AR | German: DE | Spanish: ES | French: FR | Hindi: HI | Indonesian: ID | Italian: IT | Japanese: JA | Polish: PL | Portuguese: PT | Russian: RU | Turkish: TR | Chinese: ZH | Persian: FA

<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="#sponsor">Sponsor</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 modern and clean PySide6 interface
• One-click downloads for video, audio, and subtitles
• Advanced features like SponsorBlock, subtitle merging, and playlist selection
• Optional Generic Mode for sites supported by yt-dlp beyond YouTube
• 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 | 📝 Subtitle Selection & Merging | 🔄 Auto Update yt-dlp | | ✨ Simple UI | 💾 Save Description & Thumbnail | 🛠️ FFmpeg/yt-dlp/Deno Detection | | 📋 Playlist Support & Selector | 🚀 Speed Limiter | ⚙️ Custom Commands | | 📑 Chapter Integration | ✂️ Video Section Trimming | 🍪 Login with Cookies | | 📜 Download History | 🔄 Version Channel Selection | 🌐 Proxy Support | | 🎚️ Audio Format Conversion | 🎬 Video Format Settings | 🆙 Built-in Updater Tab | | 🌍 Generic Mode | 🔊 Audio Normalization (EBU R128) | 🌍 Localized in 14 Languages | | 💾 Playlist Export | ⚙️ Default Quality & Subtitles | |

</div>

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

🚀 Installation

⚡ Quick Install (Recommended)

Install YTSage via PyPI:

pip install ytsage

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

pip install --upgrade ytsage

</details>

Then launch the application:

ytsage

📦 Pre-built Executables

👉 Download Latest Release

🪟 Windows

| Format | Description | |--------|-------------| | | Standard Installer | | | With FFmpeg Included | | | Portable version, no installation needed | | | 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 launch ytsage.exe.
3. FFmpeg Included: Choose versions with FFmpeg included 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 needed
  

• 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 to your Applications folder.
• Application Archive (.zip): Extract the zip and move YTSage.app to your Applications folder.

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

</details>

---

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

1. Clone the repository

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

2. Install dependencies

⚡ Using uv

uv pip install .

📦 Or using 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" 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 and select language
   • Enable Subtitle Merging
   • Save Thumbnail
   • Remove Sponsored Segments
   • Save Description
   • Embed Chapters
6. Select Output Directory
7. Click "Download"

💡 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, and you can export playlist entries as .txt, .csv, .m3u, or .json.

</details> <details> <summary>🌍 Generic Mode for Non-YouTube Sites</summary>

Use Generic Mode when you want YTSage to accept URLs from sites supported by yt-dlp, such as Dailymotion, CBC Gem, TikTok, and others.

How to use it:

1. Open Download Settings.
2. Toggle on Generic Mode.
3. Paste a supported video or playlist URL that is not from YouTube.
4. Click Analyze.
5. Choose a format and download as usual.

Notes:

• Generic mode only changes the UR