github.com/oop7/YTSage @v5.2.0 sqlite

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): 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
	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:
5. Video for video downloads
6. Audio Only for audio extraction
7. Choose Options:
8. Enable Subtitles and select language
9. Enable Subtitle Merging
10. Save Thumbnail
11. Remove Sponsored Segments
12. Save Description
13. Embed Chapters
14. Select Output Directory
15. 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:
• Recommended: Use the built-in Extract cookies from browser option in the app, then select your browser and optionally a profile.
• 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