---
## ❓ 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
- Optional Generic Mode for yt-dlp-supported sites beyond YouTube
- Cross-platform support and easy installation
## ✨ Features
| 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 |
| 🌍 Generic Mode || 🌍 Localization in 14 Languages | |
## 🚀 Installation
### ⚡ Quick Install (Recommended)
Install YTSage from PyPI:
```bash
pip install ytsage
```
🔄 Update an existing installation
```bash
pip install --upgrade ytsage
```
Then launch the app:
```bash
ytsage
```
### 📦 Pre-built Executables
> [👉 Download Latest Release](https://github.com/oop7/YTSage/releases/latest)
#### 🪟 Windows
| Format | Description |
|--------|-------------|
|  | Standard installer |
|  | With FFmpeg bundled |
|  | Portable version, no installation required |
|  | Portable with FFmpeg, zipped |
🛠️ Installation Steps
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.
#### 🐧 Linux
| Format | Description |
|--------|-------------|
|  | Debian package |
|  | AppImage, portable |
|  | RPM package |
|  | Flatpak Bundle |
🛠️ Installation Steps
- **DEB (`.deb`)**:
```bash
sudo dpkg -i ytsage_*.deb
sudo apt-get install -f # Fix missing dependencies if any
```
- **RPM (`.rpm`)**:
```bash
sudo rpm -i ytsage-*.rpm
```
- **AppImage (`.AppImage`)**:
```bash
chmod +x YTSage-*.AppImage
./YTSage-*.AppImage
```
- **Flatpak**: Follow instructions on Flathub or run:
```bash
flatpak install flathub io.github.oop7.ytsage
```
#### 🍎 macOS
| Format | Description |
|--------|-------------|
|  | Zipped application for Apple Silicon |
|  | Disk image installer for Apple Silicon |
🛠️ Installation Steps
- **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](#troubleshooting) below.*
---
💻 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 .
```
#### 📦 Or with standard pip
```bash
pip install .
```
### 3. Run the Application
```bash
python -m ytsage.main
```
## 📸 Screenshots
Download Settings
Playlist Download
Audio Format
Custom 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"**
> 💡 The default download directory is the user's "Downloads" folder.
📋 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
🌍 Generic Mode for non-YouTube sites
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. Enable `Generic Mode`.
3. Paste a supported non-YouTube video or playlist URL.
4. Click `Analyze`.
5. Choose a format and download as usual.
Notes:
- Generic Mode only changes URL validation inside YTSage. The target site must still be supported by your installed yt-dlp version.
- Some sites require cookies, a login session, a proxy, or extra yt-dlp arguments depending on the extractor.
- If a site fails, update yt-dlp first from the built-in updater tab before reporting the issue.
🧰 Media and Download Options
- **Subtitle Options:** Filter languages and embed subtitles into the video file
- **Subtitle Merge:** Merge subtitles into the video file for hardcoded subtitles
- **Save Description:** Save the video description as a text file
- **Save Thumbnail:** Save the video thumbnail as an image file
- **Embed Chapters:** Embed chapter markers as metadata for compatible video players
- **Remove Sponsor Segments:** Remove sponsor segments from the video using SponsorBlock
- **Trim Video:** Download only specific parts of a video by specifying time ranges in `HH:MM:SS` format
⚙️ Output and File Settings
- **Speed Limiter:** Limit the download speed, for example `500K` for 500 KB/s
- **Save Download Path:** Save the default download path for future downloads. Available in **Download Settings → Download Path**.
- **Output Filename Format:** Customize the output filename format using variables like `%(title)s`, `%(uploader)s`, and `%(resolution)s`. Available in **Download Settings → Filename Format**.
- **Force Output Format:** Force video downloads into a specific container format such as `mp4`, `webm`, or `mkv`. Available in **Download Settings → Output Format Settings**.
- **Audio Format Conversion:** Convert audio-only downloads to preferred formats such as `AAC`, `MP3`, `FLAC`, `WAV`, `Opus`, `M4A`, `Vorbis`, or `Best`. Available in **Download Settings → Audio Format Settings**.
🌐 Access and Network
- **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, then select your browser and optionally a profile.
2. Alternatively, extract cookies manually:
a. Export cookies from your browser using an extension like [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file)
b. Copy the cookies in Netscape format
c. Create a file named `cookies.txt` and paste the cookies into it
d. Select the `cookies.txt` file in the app
- **Proxy Support:** Use a proxy server for downloads, for example `http://:`
- **Generic Mode:** Allow YTSage to analyze and download from non-YouTube sites supported by yt-dlp. Enable it from **Download Settings → Generic Mode**.
🛠️ Tools and Maintenance
- **Custom Commands:** Access advanced yt-dlp features via command line arguments
- **Updater Tab:** Manage built-in update tools from one place in Custom Options:
- **yt-dlp Updates:** Check for updates and switch between Stable and Nightly release channels
- **FFmpeg Version Checker:** Check your FFmpeg version and open installation guides
- **Deno Updates:** Check and update the Deno runtime
- **FFmpeg/yt-dlp/Deno Detection:** Automatically detect FFmpeg, yt-dlp, and Deno paths and versions from the About dialog.
- **Download History:** View past downloads with thumbnails and statuses from the **History** button.
🌍 Localization
YTSage supports **14 languages** for worldwide accessibility. Select your preferred language from **Custom Options → Language**.
### Supported Languages
| Language | Code | Language | Code |
|----------|------|----------|------|
| 🇺🇸 English | `en` | 🇪🇸 Spanish | `es` |
| 🇸🇦 Arabic | `ar` | 🇫🇷 French | `fr` |
| 🇩🇪 German | `de` | 🇮🇳 Hindi | `hi` |
| 🇮🇩 Indonesian | `id` | 🇮🇹 Italian | `it` |
| 🇯🇵 Japanese | `ja` | 🇵🇱 Polish | `pl` |
| 🇧🇷 Portuguese | `pt` | 🇷🇺 Russian | `ru` |
| 🇹🇷 Turkish | `tr` | 🇨🇳 Chinese | `zh` |
> 💡 **Want to contribute a translation?** Check out the [Contributing](#contributing) section to help us add more languages!
## 🛠️ Troubleshooting
Click to view common issues and solutions
- **Format table not displaying:** Update yt-dlp to the latest version, and switch to yt-dlp nightly.
- **Download fails:** Check your internet connection and ensure the video is available.
- **Specific download errors:**
- **Private videos:** Use cookie authentication to access private content.
- **Age-restricted content:** Login to YouTube account to view age-restricted videos.
- **Geo-blocked videos:** Consider using a VPN to bypass regional restrictions.
- **Removed/deleted videos:** Video is no longer available on YouTube.
- **Live streams:** Live streams cannot be downloaded; wait for the stream to end.
- **Network errors:** Check your internet connection and try again.
- **Invalid URLs:** Ensure the URL is correct and from a supported platform.
- **Premium content:** Requires YouTube Premium membership.
- **Copyright blocks:** Content is blocked due to copyright restrictions.
- **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 packaged applications.
**Why this happens:**
- Antivirus heuristics can misidentify packed executables as suspicious
**Safe alternatives:**
- ✅ **Use pip installation:** `pip install ytsage` (recommended)
- ✅ **Build from source**: by following this [guide](.github/CI_CD_README.md)
- ✅ **Whitelist the application** in your antivirus software
#### 🍎 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`
## 💖 Sponsor
If YTSage saves you time, consider sponsoring the project. Sponsorship helps cover development time, testing across platforms, and future improvements.
- GitHub Sponsors: https://github.com/sponsors/oop7
- The sponsor link is also available directly inside the app from the About dialog.
[](https://github.com/sponsors/oop7)
## 👥 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/
├── 📁 .github/ # GitHub configuration
│ ├── 📁 ISSUE_TEMPLATE/ # Issue templates
│ │ └── 🐛-bug-report.md # Bug report template
│ ├─── 📁 workflows/ # GitHub Actions workflows
│ │ ├── build-linux.yml # Linux build workflow
│ │ ├── build-macos.yml # macOS build workflow
│ │ │── build-windows.yml # Windows build workflow
| | └── release-all.yml # Master release workflow
│ └── 📄 CI_CD_README.md # CI/CD documentation
├── 📁 branding/ # Branding assets (Screenshots, SVGs)
│ ├── 📁 icons/ # Application icons
│ ├── 📁 screenshots/ # Screenshots for documentation
│ └── 📁 svg/ # SVG assets
├── 📄 LICENSE # License file
├── 📄 pyproject.toml # Project metadata and dependencies
├── 📄 README.md # Project documentation
├── 📄 requirements.txt # Python dependencies (dev)
└── 📁 ytsage/ # Source package
├── 📁 assets/ # Runtime assets
│ ├── 📁 Icon/ # Application icons
│ └── 📁 sound/ # Audio files
├── 📁 languages/ # Localization files
│ ├── 📄 ar.json # Arabic translation
│ ├── 📄 de.json # German translation
│ ├── 📄 en.json # English translation
│ └── ... # Other languages
├── 📁 core/ # Core business logic
│ ├── 📄 __init__.py # Core package init
│ ├── 📄 ytsage_deno.py # Deno integration
│ ├── 📄 ytsage_downloader.py # Download functionality
│ ├── 📄 ytsage_ffmpeg.py # FFmpeg integration
│ ├── 📄 ytsage_utils.py # Utility functions
│ └── 📄 ytsage_yt_dlp.py # yt-dlp integration
├── 📁 gui/ # User interface components
│ ├── 📄 __init__.py # GUI package init
│ ├── 📄 ytsage_gui_main.py # Main application window
│ └── 📁 ytsage_gui_dialogs/ # Dialog classes
├── 📁 utils/ # Utility modules
│ ├── 📄 __init__.py # Utils package init
│ ├── 📄 ytsage_config_manager.py # Configuration management
│ └── 📄 ytsage_logger.py # Logging utilities
├── 📄 __init__.py # Package entry point
└── 📄 main.py # Main execution script
```
## ⭐️ Star History
## 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.
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](https://github.com/oop7/YTSage/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/oop7/YTSage/releases)
[](https://github.com/oop7/YTSage/stargazers)
[](https://pypi.org/project/ytsage/)
[](https://github.com/sponsors/oop7)
**A modern YouTube downloader with a clean PySide6 interface.**
Download videos in any quality, extract audio, fetch subtitles, and more.
