[![Python 3.10+](https://img.shields.io/badge/python-3.10+-1f2937?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) [![PyPI Downloads](https://img.shields.io/pepy/dt/ytsage?color=1f2937&style=for-the-badge&label=downloads&logo=python&logoColor=white)](https://pepy.tech/project/ytsage) [![GitHub Downloads](https://img.shields.io/github/downloads/oop7/YTSage/total?color=1f2937&style=for-the-badge&label=downloads&logo=github&logoColor=white)](https://github.com/oop7/YTSage/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-1f2937?style=for-the-badge&logo=opensource&logoColor=white)](https://opensource.org/licenses/MIT) [![Supported Platforms](https://img.shields.io/badge/platform-cross--platform-1f2937?style=for-the-badge&logo=github&logoColor=white)](https://github.com/oop7/YTSage/releases) [![GitHub Stars](https://img.shields.io/github/stars/oop7/YTSage?color=c90000&style=for-the-badge&logo=github&logoColor=white)](https://github.com/oop7/YTSage/stargazers) [![PyPI version](https://img.shields.io/pypi/v/ytsage?color=c90000&style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ytsage/) [![GitHub Sponsors](https://img.shields.io/github/sponsors/oop7?color=c90000&style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/oop7) **Modern YouTube downloader with a clean PySide6 interface.** Download videos in any quality, extract audio, fetch subtitles, and more. ### 🌍 README Languages English: [EN](README.md) | Arabic: [AR](readme-translations/README.ar.md) | German: [DE](readme-translations/README.de.md) | Spanish: [ES](readme-translations/README.es.md) | French: [FR](readme-translations/README.fr.md) | Hindi: [HI](readme-translations/README.hi.md) | Indonesian: [ID](readme-translations/README.id.md) | Italian: [IT](readme-translations/README.it.md) | Japanese: [JA](readme-translations/README.ja.md) | Polish: [PL](readme-translations/README.pl.md) | Portuguese: [PT](readme-translations/README.pt.md) | Russian: [RU](readme-translations/README.ru.md) | Turkish: [TR](readme-translations/README.tr.md) | Chinese: [ZH](readme-translations/README.zh.md)

Installation • Features • Usage • Screenshots • Troubleshooting • Sponsor • Contributing

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

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

## 🚀 Installation ### ⚡ Quick Install (Recommended) Install YTSage via PyPI: ```bash pip install ytsage ```

🔄 Update existing installation

```bash pip install --upgrade ytsage ```

Then launch the application: ```bash ytsage ``` ### 📦 Pre-built Executables > [👉 Download Latest Release](https://github.com/oop7/YTSage/releases/latest) #### 🪟 Windows | Format | Description | |--------|-------------| | ![Windows EXE](https://img.shields.io/badge/Windows-EXE-0078D6?style=for-the-badge&logo=windows&logoColor=white) | Standard Installer | | ![Windows FFmpeg](https://img.shields.io/badge/Windows-FFmpeg-0078D6?style=for-the-badge&logo=windows&logoColor=white) | With FFmpeg Included | | ![Windows Portable](https://img.shields.io/badge/Windows-Portable-0078D6?style=for-the-badge&logo=windows&logoColor=white) | Portable version, no installation needed | | ![Windows Portable FFmpeg](https://img.shields.io/badge/Windows-Portable%20FFmpeg-0078D6?style=for-the-badge&logo=windows&logoColor=white) | 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 launch `ytsage.exe`. 3. **FFmpeg Included**: Choose versions with FFmpeg included if you don't have FFmpeg installed on your system.

#### 🐧 Linux | Format | Description | |--------|-------------| | ![Linux DEB](https://img.shields.io/badge/Linux-DEB-FCC624?style=for-the-badge&logo=linux&logoColor=black) | Debian Package | | ![Linux AppImage](https://img.shields.io/badge/Linux-AppImage-FCC624?style=for-the-badge&logo=linux&logoColor=black) | AppImage, Portable | | ![Linux RPM](https://img.shields.io/badge/Linux-RPM-FCC624?style=for-the-badge&logo=linux&logoColor=black) | RPM Package | | ![Flathub](https://img.shields.io/badge/Linux-Flatpak-FCC624?style=for-the-badge&logo=flathub&logoColor=black) | Flatpak Bundle |

🛠️ Installation Steps

- **DEB (`.deb`)**: ```bash sudo dpkg -i ytsage_*.deb sudo apt-get install -f # Fix missing dependencies if needed ``` - **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 | |--------|-------------| | ![macOS ARM64 APP](https://img.shields.io/badge/macOS-ARM64%20APP-000000?style=for-the-badge&logo=apple&logoColor=white) | Zipped Application for Apple Silicon | | ![macOS ARM64 DMG](https://img.shields.io/badge/macOS-ARM64%20DMG-000000?style=for-the-badge&logo=apple&logoColor=white) | Disk Image Installer for Apple Silicon |

🛠️ Installation Steps

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

---

💻 Manual Source Installation

### 1. Clone the repository ```bash git clone https://github.com/oop7/YTSage.git cd YTSage ``` ### 2. Install dependencies #### ⚡ Using uv ```bash uv pip install . ``` #### 📦 Or using 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 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.

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

🌍 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. 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 URL validation inside YTSage. The target site must still be supported by your installed version of yt-dlp. - Some sites require cookies, login sessions, proxy, or extra yt-dlp arguments depending on the extractor. - If a site fails, update yt-dlp from the built-in updater tab first before reporting an issue.

🧰 Media & Download Options

- **Subtitle Options:** Filter languages and embed subtitles into the video file. - **Subtitle Merging:** Merge subtitles into the video file for hardcoded/burned-in 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 Sponsored Segments:** Remove sponsored 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 & File Settings

- **Speed Limiter:** Limit download speed, e.g., `500K` for 500 KB/s. - **Save Download Path:** Saves the default download path for future downloads. Available in **Download Settings → Download Path**. - **Default Video Resolution:** Set your preferred default video resolution for auto-selection (e.g., 1080p, 720p). Available in **Download Settings → Default Video Resolution**. - **Default Subtitle Languages:** Set default subtitle languages for auto-selection (comma-separated, e.g., `en,es`). Available in **Download Settings → Default Subtitle Languages**. - **Output Filename Format:** Customize the output filename format using variables like `%(title)s`, `%(uploader)s`, `%(playlist_index)s`, and `%(resolution)s`. Available in **Download Settings → Filename Format**. - **Force Output Format:** Force video downloads into a specific container format like `mp4`, `webm`, or `mkv`. Available in **Download Settings → Output Format Settings**. - **Audio Format Conversion:** Convert audio-only downloads into preferred formats such as `AAC`, `MP3`, `FLAC`, `WAV`, `Opus`, `M4A`, `Vorbis`, or `Best`. Available in **Download Settings → Audio Format Settings**. - **Audio Normalization:** Standardize volume for audio-only downloads using EBU R128. - **Concurrent Connections:** Dramatically increase download speed by downloading files in multiple fragments simultaneously. Available in **Download Settings → General → Concurrent Connections** (Default is 1, maximum recommended is 8-10 to avoid IP throttling).

🌐 Access & Network

- **Login with Cookies:** Log in 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 browser cookies using an extension like [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file) b. Copy cookies in Netscape format c. Create a file named `cookies.txt` and paste cookies d. Select the `cookies.txt` file in the app - **Proxy Support:** Use a proxy server for downloads, e.g., `http://:` - **Generic Mode:** Allows YTSage to analyze and download from non-YouTube sites supported by yt-dlp. Enable from **Download Settings → Generic Mode**.

🛠️ Tools & 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 toggle 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 detects paths and versions for FFmpeg, yt-dlp, and Deno from the About dialog. - **Download History:** View past downloads with thumbnails and statuses from the **History** button.

🌍 Localization

YTSage supports **14 languages** for global accessibility. Select your preferred language in **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` | ### README Translations | Language | File | Language | File | |----------|------|----------|------| | 🇺🇸 English | [README.md](README.md) | 🇪🇸 Spanish | [readme-translations/README.es.md](readme-translations/README.es.md) | | 🇸🇦 Arabic | [readme-translations/README.ar.md](readme-translations/README.ar.md) | 🇫🇷 French | [readme-translations/README.fr.md](readme-translations/README.fr.md) | | 🇩🇪 German | [readme-translations/README.de.md](readme-translations/README.de.md) | 🇮🇳 Hindi | [readme-translations/README.hi.md](readme-translations/README.hi.md) | | 🇮🇩 Indonesian | [readme-translations/README.id.md](readme-translations/README.id.md) | 🇮🇹 Italian | [readme-translations/README.it.md](readme-translations/README.it.md) | | 🇯🇵 Japanese | [readme-translations/README.ja.md](readme-translations/README.ja.md) | 🇵🇱 Polish | [readme-translations/README.pl.md](readme-translations/README.pl.md) | | 🇧🇷 Portuguese | [readme-translations/README.pt.md](readme-translations/README.pt.md) | 🇷🇺 Russian | [readme-translations/README.ru.md](readme-translations/README.ru.md) | | 🇹🇷 Turkish | [readme-translations/README.tr.md](readme-translations/README.tr.md) | 🇨🇳 Chinese | [readme-translations/README.zh.md](readme-translations/README.zh.md) | > 💡 **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 appearing:** Update yt-dlp to latest version and switch to nightly yt-dlp. - **Download failed:** 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:** Log in to your YouTube account to view age-restricted videos. - **Geo-Blocked Videos:** Consider using a VPN to bypass regional restrictions. - **Deleted Videos:** Video is no longer available on YouTube. - **Live Streams:** Live streams cannot be downloaded; wait for the broadcast 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 a YouTube Premium subscription. - **Copyright Blocks:** Content is blocked due to copyright restrictions. - **Video and Audio Files separate 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 `.exe` files as false positives. This is a **known limitation** of packaged applications. **Why this happens:** - Antivirus heuristics can mistakenly identify packaged executables as suspicious. **Safe Alternatives:** - ✅ **Use pip install:** `pip install ytsage` (Recommended) - ✅ **Build from Source**: by following this [guide](.github/CI_CD_README.md) - ✅ **Whitelist the app** in your antivirus software. #### 🍎 macOS: "Application is damaged and cannot 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 this 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. --- #### **Config Locations (Advanced)** - **Windows:** `%LOCALAPPDATA%\YTSage` - **macOS:** `~/Library/Application Support/YTSage` - **Linux:** `~/.local/share/YTSage`

## 💖 Sponsor If YTSage saves you time, please consider sponsoring the project. Sponsoring helps cover development time, testing across all platforms, and future improvements. - GitHub Sponsors: https://github.com/sponsors/oop7 - Sponsorship link is also available directly in the app via the About dialog. [![Sponsor YTSage](https://img.shields.io/badge/Sponsor-YTSage-EA4AAA?style=for-the-badge&logo=github&logoColor=white)](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 ### 🌍 Contributing Translations - Update the relevant localized README file (e.g., `readme-translations/README.fr.md`) - Keep app strings synced by editing `ytsage/languages/

.json`
- If your language is missing, start from `README.md` and create `readme-translations/README..md`


📂 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          # Release master workflow
│   └── 📄 CI_CD_README.md        # CI/CD documentation
├──  📁 branding/                 # Branding assets (Screenshots, SVGs)
│   ├── 📁 icons/                 # App icons
│   ├── 📁 screenshots/           # Documentation screenshots
│   └── 📁 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/              # App icons
    │   └── 📁 sound/             # Sound 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/                   # UI components
    │   ├── 📄 __init__.py        # GUI package init
    │   ├── 📄 ytsage_gui_main.py # Main app window
    │   └── 📁 ytsage_gui_dialogs/ # Dialog classes
    ├── 📁 utils/                 # Utility modules
    │   ├── 📄 __init__.py        # Utils package init
    │   ├── 📄 ytsage_config_manager.py # Config 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 big thanks to everyone who 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
    
    
        Deno
        Runtime for yt-dlp plugins
    
    Libraries & Frameworks
    
        PySide6
        GUI Framework
    
    
        Pillow
        Image Processing
    
    
        requests
        HTTP Requests
    
    
        packaging
        Version/Package Management
    
    
        markdown
        Markdown Rendering
    
    
        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 creator rights.

---



Made with ❤️ by [oop7](https://github.com/oop7)

Core Components
yt-dlp	Download Engine
FFmpeg	Media Processing
Deno	Runtime for yt-dlp plugins
Libraries & Frameworks
PySide6	GUI Framework
Pillow	Image Processing
requests	HTTP Requests
packaging	Version/Package Management
markdown	Markdown Rendering
loguru	Logging
Assets & Contributors
New Notification 09 by Universfield	Notification Sound
viru185	Code Contributor