YTSage 4.9.1

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

Platform	File	Notes
	YTSage-v4.9.1-Setup.exe	Standard installer
	YTSage-v4.9.1-ffmpeg-Setup.exe	With FFmpeg bundled
	YTSage-v4.9.1-portable.zip	Portable version, no installation required
	YTSage-v4.9.1-ffmpeg-portable.zip	Portable with FFmpeg, zipped
	YTSage-v4.9.1-amd64.deb	Debian package
	YTSage-v4.9.1-x86_64.AppImage	AppImage, portable
	YTSage-v4.9.1-x86_64.rpm	RPM package
	YTSage-v4.9.1-arm64.app.zip	Zipped application for ARM64
	YTSage-v4.9.1-arm64.dmg	Disk image installer for ARM64
	YTSage-v4.9.1-x64.app.zip	Zipped application for x64
	YTSage-v4.9.1-x64.dmg	Disk image installer for x64

🚀 New Features

• Proxy: Added proxy support to enable users to route their downloads through a proxy server for enhanced privacy and bypass restrictions #47
  thanks to (@vitos1k)

• Open Folder: Added an "Open Folder" button to quickly access the download location after a download is complete #57 thanks to (@LifeDrainingCoding)

• Localization: Introduced localization support, allowing users to select their preferred language for the application interface. You can change the language in the Custom Options section. Supported languages include:

  • English (default)
  • Spanish
  • French
  • German
  • Chinese (Simplified)
  • Japanese
  • Russian
  • Portuguese (Brazilian)
  • Italian
  • Polish
  • Arabic
  • Hindi
  • Indonesian
  • Turkish

• FPS column in format selection: Added an FPS (Frames Per Second) column in the format selection dialog to help users choose video formats based on their frame rates.

• HDR column in format selection: Added an HDR (High Dynamic Range) column in the format selection dialog to indicate which video formats support HDR, assisting users in selecting high-quality video options.

🔧 Improvements

• Binary-Only yt-dlp Implementation: Transitioned to a binary-only approach for yt-dlp, removing the Python package dependency. This significantly reduces package size, speeds up installation, and simplifies dependency management. YTSage now exclusively uses its own managed yt-dlp binary located in the application's bin directory, eliminating conflicts with system-wide installations. Users who prefer a custom yt-dlp version can still specify the path to their own binary in the settings.

• Enhanced Stability & Error Handling (#41, @viru185): Improved robustness of yt-dlp and FFmpeg integrations with safer binary checks, better error messages, and more reliable subprocess handling for a smoother user experience.

• Streamlined Format Selection: Removed the Notes column from the format selection dialog to reduce clutter and make it easier to choose your preferred video format.

• Better Logging System: Implemented centralized, thread-safe logging infrastructure for improved debugging and troubleshooting.

• UI & UX Refinements: Enhanced path handling, improved playlist and format table stability, and polished the update dialog for a more responsive interface.

• Updated Dependencies: Updated GitHub Actions workflows and Python version (to 3.13.x) to ensure the application uses the latest, most stable versions of build and runtime dependencies.

🐛 Bug Fixes

• Windows File Locking Issues: Fixed file locking errors when deleting partial files by implementing safe deletion with retry logic and process termination delays

📖 Documentation

• Repository Screenshots: updated repository screenshots to reflect the latest UI changes

YTSage 4.8.3

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

Platform	File	Notes
	YTSage-v4.8.3-Setup.exe	Standard installer
	YTSage-v4.8.3-ffmpeg-Setup.exe	With FFmpeg bundled
	YTSage-v4.8.3-portable.zip	Portable version, no installation required
	YTSage-v4.8.3-ffmpeg-portable.zip	Portable with FFmpeg, zipped
	YTSage-v4.8.3-amd64.deb	Debian package
	YTSage-v4.8.3-x86_64.AppImage	AppImage, portable
	YTSage-v4.8.3-x86_64.rpm	RPM package
	YTSage-v4.8.3-arm64.app.zip	Zipped application for ARM64
	YTSage-v4.8.3-arm64.dmg	Disk image installer for ARM64
	YTSage-v4.8.3-x64.app.zip	Zipped application for x64
	YTSage-v4.8.3-x64.dmg	Disk image installer for x64

🚀 New Features

• Cookies Browser: Introduced a new feature to retrieve cookies using yt-dlp #31 (@Lucy-dot-dot)
• Refactored Custom Commands: Enhanced custom commands with an updated design, improvements, and bug fixes
• Trim Video Dialog: Removed the preview command from the trim video dialog for a streamlined interface
• Enhanced Error Handling: Improved error messages with detailed guidance for common issues:
  • Private videos: Directs users to cookie authentication
  • Age-restricted content: Explains the login requirement
  • Geo-blocked videos: Suggests using a VPN
  • Removed/deleted videos: Clarifies video unavailability
  • Live streams: Explains timing limitations
  • Network errors: Recommends checking connectivity
  • Invalid URLs: Guides on URL format correction
  • Premium content: Explains membership requirements
  • Copyright blocks: Describes content restrictions
• Migration to Pyglet: Replaced pygame with pyglet for reduced size, as pygame was overly heavy for simple notifications
• Migration to cx_Freeze: Switched from PyInstaller to cx_Freeze for improved load times
• CI/CD Pipeline: Implemented an automated pipeline workflow for building pre-executables
• Screenshots in Repository: Added screenshots to the repository for faster loading in the README
• Code Refactor and Cleanup #37 (@viru185):
  • Import Fixes: Eliminated unused imports, adopted full import paths, and sorted imports alphabetically (Standard Library > Third-Party > Local)
  • Removed Unsafe Method: Deleted Method 3 from src.core.ytsage_downloader:cleanup_subtitle_file to prevent accidental deletion of unrelated subtitle files due to recursive scanning
  • Path Handling Refactor: Migrated from os.path to pathlib.Path for better readability, reduced code repetition, and enhanced cross-platform compatibility
  • Code Readability Enhancements: Standardized string literals to double quotes, removed extraneous spaces, and enforced consistent formatting
  • Constants File: Created ytsage_constants.py as a centralized location for all constants
  • Type Hints: Added return type hints to functions for improved type checking and code clarity
  • GUI Module Restructuring: Renamed src/gui/dialogs to src/gui/ytsage_gui_dialogs for naming consistency, and added __init__.py for centralized dialog imports
  • Variable Renaming: Changed self.parent to self._parent to avoid conflicts with the built-in parent() method and added type checking
  • Signal Handling Update: Replaced QMetaObject.invokeMethod with Signal due to unresolved issues, aligning with the app's design patterns
  • Constants Integration: Replaced redundant logic with references to ytsage_constants.py
  • yt-dlp Update Logic: Updated src/gui/ytsage_gui_dialogs/ytsage_dialogs_update:_update_binary to use yt-dlp -U for streamlined updates

🔧 Improvements

• Build Automation: Streamlined the build process with automated CI/CD pipelines for pre-executables
• Windows Installer: Added new setup installer (Inno Setup) for easier installation.
• RPM Package: Introduced an RPM package for easier installation on RPM-based Linux distributions

📖 Documentation

• Repository Screenshots: Added screenshots to the repository to enhance the README with faster-loading visual aids
• wordmark svg: added wordmark svg to the repository for better branding
• OSs badges: added OSs badges to the repository for better visibility

YTSage 4.7.0

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

Platform	Download Link	Notes
	YTSage-v4.7.0.exe	Native Windows launcher
	YTSage-v4.7.0-ffmpeg.exe	Bundled with FFmpeg
	YTSage-v4.7.0.dmg	Standard macOS installer
	YTSage-v4.7.0-macOS-app.zip	Contains the .app bundle
	YTSage-v4.7.0-amd64.deb	For Debian/Ubuntu-based distros
	YTSage-v4.7.0-x86_64.AppImage	Run on any modern distro

🚀 New Features

• SponsorBlock Categories: Expanded segment selection options beyond just sponsor segments. Users can now select from multiple types of video segments to automatically remove during download using community-submitted data. Available categories include: Sponsor, Unpaid/Self Promotion, Interaction Reminder, Intro, Outro/End Cards, Preview/Recap, Non-Music Section, and Filler Tangent.
• Embed Chapters: Mark YouTube chapters that will be displayed by supported media players for better navigation.
• Enhanced About Dialog: Added ffmpeg path display with version checks for both yt-dlp and ffmpeg (#22, thanks to @scotenchen).

🔧 Improvements

• Logging System: Replaced print statements with loguru for improved efficiency and better debugging (#23, thanks to @viru185). Application logs are now stored in the YTSage\logs folder for better troubleshooting and monitoring of the application's operations.
• Code Structure: Comprehensive refactoring and optimization of ytsage_gui_dialogs.py and overall project architecture.
• FFmpeg Update: Updated ffmpeg to version 7.1.1-full_build in both bundled version and ytsage_ffmpeg.py installation module for latest features and improvements.

🐛 Bug Fixes

• Module Not Found: Fixed an error where the application would fail to launch due to a missing pkg_resources module (#25, thanks to @DrElvis).

🎨 UI/UX Enhancements

• FFmpeg Installation Dialog: Redesigned interface for a cleaner and more intuitive experience.
• About Dialog Redesign: Streamlined layout with clearer information presentation and system checks.
• Platform Badges: Replaced plain text with descriptive badges in the downloads section for a more modern look.
• Overall Polish: Various visual improvements throughout the application.

📖 Documentation

• Project Structure: Added comprehensive file structure documentation in README.
• macOS App Damaged Error: Implemented a fix to address the "App is damaged and can’t be opened" error on macOS (#27, thanks to @wenzelua).
• Installation Guide: Added uv option alongside pip in requirements.txt for users who prefer faster dependency installation (#21, thanks to @viru185).
• Configuration Reference: Documented application configuration paths across different operating systems.
• Troubleshooting: Added a section to the README to address common issues, including the "App is damaged and can’t be opened" error on macOS.
• Consistency: Improved the overall consistency and readability of the README file.

YTSage 4.6.0

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

🚀 New Features

• Dynamic yt-dlp Management: Pre-built executables now download the appropriate yt-dlp version for your OS at startup, enabling automatic updates without requiring new app releases
• Download Notifications: Added audio notification that plays when downloads complete
• Version Information: Added yt-dlp and ffmpeg version display in the About dialog for better transparency

🔧 Improvements

• Startup Performance: Auto-update process now runs asynchronously during startup, significantly reducing boot time
• Configuration Organization: Centralized app configuration and yt-dlp bundles in platform-specific directories:
  • Windows: %LOCALAPPDATA%\YTSage
  • macOS: ~/Library/Application Support/YTSage
  • Linux: ~/.local/share/YTSage
• Performance Optimization: Implemented caching for yt-dlp and ffmpeg versions, plus yt-dlp path resolution
• User Control: Added "Auto update yt-dlp" toggle in Download Settings for manual control over updates
• Multiple Instances Issue: Fixed multiple instances of YTSage when running the pre-built executables (#20, reported by @xjuanfxx, with thanks to the reporter)
• Table Formatting (Under Review): Addressed formatting issues in tables, pending further validation

🎨 UI/UX Enhancements

• Theme Consistency: Fixed update dialog layout to properly match the application theme
• Layout Improvements: Various visual refinements to the update interface

📖 Documentation

• Cookie Authentication Guide: Added detailed step-by-step instructions for using the "Log in with cookies" feature in README.md
• Improved cross-platform compatibility for configuration management

YTSage 4.5.7

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

✨ Improvements

• New Debian Package: Added a .deb package for easier installation on Debian, Ubuntu, and derivative distributions.
• Bundled yt-dlp Update: Updated the bundled yt-dlp included in the pre-built executables to the latest version, ensuring better compatibility and performance.
• UI Theming: The speed limit dropdown menu has been redesigned to match the application's theme, creating a more visually consistent and polished user interface.

YTSage 4.5.6

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

✨ Improvements

• Video Trimming: Introduced a new option to trim videos, allowing users to select specific segments for download.
• Startup yt-dlp Check: Implemented an automatic yt-dlp check on application startup for installations via PyPI or direct Python script usage, ensuring it's correctly configured.
• Custom Options Consolidation: Streamlined the interface by consolidating 'Login with Cookies' and 'Custom Command' functionalities into a new 'Custom Options' section.
• Notes Feature Enhancement: Refined the 'Notes' feature for improved usability and organization.

YTSage 4.5.2

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

✨ Improvements

• yt-dlp Path Detection: Improved the method for detecting the yt-dlp executable path for better reliability.
• Bundled yt-dlp Update: Updated the bundled yt-dlp included in the Pre-built Executables to the latest version.

🐛 Bug Fixes

• yt-dlp Update (Non-PyPI): Added an informative dialog to handle cases where users attempt to use the yt-dlp auto-update feature in non-PyPI installations (where this feature is unavailable).

YTSage 4.5.0

This release brings many new features, improvements, and bug fixes to enhance your downloading experience!

Install via PyPI:

pip install ytsage

Upgrade to the latest version:

pip install --upgrade ytsage

Downloads

🚀 Features

• Download Speed Limiter: Added an option to limit the download speed, giving you more control over bandwidth usage.
• Save Video Descriptions: You can now optionally save the video's description as a separate text file alongside the download.
• Multiple Subtitle Selection & Merging: Select and download multiple subtitle tracks simultaneously. Added the capability to merge selected subtitles directly into the output video file.
• Playlist Video Selection: Introduced the ability to select specific videos from a playlist for download, instead of downloading the entire list.
• Cookie-Based Login: Added support for logging in using browser cookies, enabling access to private or member-only content (#16).
• Dependency Detection: The "About" dialog now detects and displays whether ffmpeg and yt-dlp are found on the system.
• In-App Changelog: The update notification dialog now displays the changelog for the new version.
• Playlist Thumbnails: Playlist view now displays the thumbnail for the entire playlist.
• Video Like Counter Display: Added a display to show the number of likes for the selected video.

✨ Improvements

• New UI Theme: Refreshed the user interface with a new theme for a more modern look and feel.
• Enhanced Audio Download Safety: Improved error handling and UI guidance in the audio-only section to prevent selecting incompatible formats that previously led to download failures.
• Improved yt-dlp Update Process: Streamlined the process for checking and updating the bundled yt-dlp.
• More Detailed Download Progress: Enhanced the download progress indicator to provide more granular feedback.
• Simplified About Dialog: Removed the features list entirely from the "About" dialog for a cleaner and more focused presentation.
• Corrected Playlist View Information: Removed inaccurate file size and extension details from the playlist view (previously only reflected the first video).
• Consistent Iconography: Replaced the generic download icon with the YTSage application icon.
• Optimized Cleanup: Improved the temporary file cleanup process after downloads complete.

🐛 Bug Fixes

• Output Format: Fixed an issue where the output format was always defaulting to .mp4, ignoring user selection.
• Audio Download Error: Resolved error code 2 failures that occurred during certain audio-only downloads.
• Format Table Layout: Corrected layout and alignment issues within the format selection table.
• Audio Format Naming: Fixed inconsistencies between format names (e.g., resolution labels) and file extensions in the audio-only selection list.

🔧 Internal & Build Changes

• Updated Python Version: The Python version used for building pre-compiled executables has been updated.
• Bundled ffmpeg (Windows): New pre-built Windows executables now include ffmpeg, simplifying setup for Windows users.
• Build Process Enhancements: Implemented improvements to the build process for Linux and macOS executables.

YTSage v4.2.1

This patch release addresses an issue with format listing.

Bug Fixes 🐛

• Updated the bundled yt-dlp in Pre-built Executables to fix an issue where the format list wasn't displaying (resolves #15). Thanks to @snowshoes for the report!
• For PyPI users: To ensure you also have this fix, please update your yt-dlp installation. You can do this via the YTSage app's updater or manually with pip:

  pip install --upgrade yt-dlp

YTSage v4.2.0 🎉

This release brings significant improvements and fixes to YTSage, focusing on enhanced stability, error handling, format selection, and addressing macOS compatibility.

Here's a breakdown of the changes:

Bug Fixes 🐛

• ✅ Fixed: FFmpeg Detection on macOS (#10) - Improved FFmpeg check, specifically addressing issues where FFmpeg wasn't being correctly detected on macOS. Thanks to the reporter of issue #10!
• ✅ Fixed: Incorrect Output Format (MP4 vs WebM) - Resolved an issue where the output was consistently MP4 instead of the selected WebM format.
• ✅ Fixed: Thumbnail Layout in Fullscreen Mode - Corrected the thumbnail layout when viewing in fullscreen mode for a better visual experience.
• 🛡️ Improved: Download Thread Stability - Enhanced download thread stability with better exception handling to prevent crashes and ensure more reliable downloads.

Enhancements ✨

• 💬 Added: "Video Already Downloaded" Pop-up - Implemented a pop-up message to inform users when they attempt to download a video that has already been downloaded. This prevents accidental duplicate downloads and improves user workflow.
• 🔄 Changed: Default Merge Format to MP4 - The default merge format for downloads is now MP4 instead of MKV, offering wider compatibility and potentially better playback across devices.
• 📦 Updated: yt-dlp Update Method - The yt-dlp update method is now via PYPI
• ➕ Added: Format Selection Checkbox - Introduced a checkbox to allow users to easily select their desired format directly within the format table, streamlining the selection process.
• ➕ Added: Quality Column in Format Table - A new "Quality" column has been added to the format table. This column clarifies the quality differences between various available formats, making format selection more informed.
• ➕ Added: Notes Column in Format Table - A "Notes" column is now present in the format table. This column provides helpful notes and context for each format, guiding users to choose the best option for their needs.
• 🔲 Replaced: Merge Subtitle Button with Checkbox - The "Merge Subtitle" functionality is now controlled by a checkbox instead of a button, providing a more intuitive and consistent user interface.
• 🛠️ Improved: Robust FFmpeg Checks - Further strengthened FFmpeg checks to ensure it is correctly detected and functioning across different operating systems.
• 🧹 Improved: Resource Cleanup on App Close - Implemented proper cleanup of resources when the application is closed, contributing to better system stability and preventing potential resource leaks.
• 🚀 Added: Auto-Install FFmpeg - YTSage now attempts to automatically install FFmpeg if it is not found on the system, simplifying the setup process for new users.

Stability & Error Handling 🚦

• 🚨 Improved: Comprehensive Error Handling - Implemented comprehensive error handling in the main entry point of the application. This significantly enhances the application's robustness by gracefully managing unexpected errors and providing more informative feedback.

Code Refactoring 📂

• 📂 Refactored: Split ytsage_gui.py into Multiple Modules - The large ytsage_gui.py file has been split into smaller, more manageable modules: ytsage_gui_dialogs.py, ytsage_gui_format_table.py, ytsage_gui_main.py, and ytsage_gui_video_info.py. This improves code organization, maintainability, and makes future development easier.

Removed 🗑️

• ➖ Removed: FormatID Column - The "FormatID" column has been removed from the format table. This column was deemed less relevant for most users and its removal simplifies the table and improves readability.

Thank you for using YTSage! ❤️