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

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:

pip install ytsage

🔄 Update existing installation

pip install --upgrade ytsage

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

🛠️ 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
	Debian Package
	AppImage, Portable
	RPM Package
	Flatpak Bundle

🛠️ Installation Steps

• 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
  

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

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

📸 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 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://<proxy-server>:<port>
• 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	🇪🇸 Spanish	README.es.md
🇸🇦 Arabic	README.ar.md	🇫🇷 French	README.fr.md
🇩🇪 German	README.de.md	🇮🇳 Hindi	README.hi.md
🇮🇩 Indonesian	README.id.md	🇮🇹 Italian	README.it.md
🇯🇵 Japanese	README.ja.md	🇵🇱 Polish	README.pl.md
🇧🇷 Portuguese	README.pt.md	🇷🇺 Russian	README.ru.md
🇹🇷 Turkish	README.tr.md	🇨🇳 Chinese	README.zh.md

💡 Want to contribute a translation? Check out the 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<version>-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
• ✅ 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:

   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.

👥 Contributing

We welcome contributions! Here’s how you can help:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch:

git checkout -b feature/AmazingFeature

3. 💾 Commit your changes:

git commit -m 'Add some AmazingFeature'

4. 📤 Push to the branch:

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/<code>.json
• If your language is missing, start from README.md and create README.<code>.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 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