Viren Hirpara
e9de913b47
* fix imports
remove unused imports
use full import path
sort import (1. Standard Library, 2. Third-Party, 3. Local) in alphabetic.
* - remove: Method 3 from src.core.ytsage_downlader:cleanup_subtitle_file
- it could delete the subtitle file of other movies if it present in same directory as it scane recursively.
- refactor: migrate from os.path to pathlib.Path for path handling
- Replaced os.path methods with pathlib.Path to improve readability,
- avoid repeatation.
- cross-platform compatibility, and maintain cleaner code.
- improve: enhance code readability
- Standardized string literals to use double quotes for consistency
- Removed unnecessary spaces to maintain cleaner formatting
- Applied code formatting for better readability and maintainability
* - add: ytsage_constants.py file for one place to store all constants.
- imporve: return type hint for function.
- remove: src/gui/ytsage_gui_dialogs.py file to avoid repetation
- src/gui/dialogs is renamed to src/gui/ytsage_gui_dialogs for same naming convection. (future import will remains same)
- use of src/gui/ytsage_gui_dialogs/__init__.py to import the dilogs modules.
- change: variable self.parent to self._parent so it does not overwrite the parent()
- add type hint checking.
* - refactor: QMetaObject.invokeMethod to Signal
- I encounter error with incokeMethod. Could not solve it.
- So, Changed it to Signal to match app code language.
- implement: the ytsage_constants.py to code
- remove: unnecessary logic
- remove: repetitive code logic.
- update: yt-dlp logic for src\gui\ytsage_gui_dialogs\ytsage_dialogs_update:_update_binary
- yt-dlp update logic will use `yt-dlp -U`
* refactor: remove unused imports and streamline code formatting across multiple files
* - **refactor: drop `pygame` in favor of built-in `PySide6` sound**
- Removed `pygame` dependency (too heavy just for notifications).
- Replaced with `QSoundEffect`, which is lightweight and built into `PySide6`.
- Dropped `pygame.mixer` + threading → Qt handles async playback.
- Implemented sound playback with `QUrl.fromLocalFile()` and `.play()`.
- Added `setVolume(0.9)` as a configurable example.
- Converted notification sound from `.mp3` to `.wav` (only format supported).
* **refactor(utils): simplify logger module**
- Moved `logger` to `src.utils`
- Removed unnecessary import checks (logger is always available)
- Replaced `raise` statements with error logging to prevent crashes
- Use `logger.exception()` in `except` blocks to capture traceback (logged as error)
**style: remove redundant str() in f-strings**
- Dropped explicit `str()` calls inside f-strings
- f-strings already call `str()` under the hood
**chore: add type hints for GUI mixins**
- Added type hints for `FormatTableMixin` (`src.gui.ytsage_gui_format_table`)
- Added type hints for `VideoInfoMixin` (`src.gui.ytsage_gui_video_info`)
- Improves autocomplete and type safety in IDEs
* - **introduce the `ytsage_config_manager.py` module to manage app setting.**
- Loads settings from a JSON config file (`APP_CONFIG_FILE`).
- Creates the config file with default values if missing or corrupt.
- Retrieves, sets, and deletes settings using simple dot-separated keys.
- Provides safe error handling with logging instead of raising exceptions.
- Persists updates back to disk automatically.
- **Usage**
```python
from src.utils.ytsage_config_manager import ConfigManager
download_path = ConfigManager.get("download_path")
ConfigManager.set("download_path", "D:/Downloads")
last_check = ConfigManager.get("cached_versions.ytdlp.last_check")
ConfigManager.delete("cached_versions.ffmpeg.path")
```
* **Refactore: pkg_resources with importlib.metadata.version**
- UserWarning: pkg_resources is deprecated as an API.
- See https://setuptools.pypa.io/en/latest/pkg_resources.html.
- The pkg_resources package is slated for removal as early as 2025-11-30.
* **refactore: notification sound**
- `QSoundEffect` is chnaged back to `pyglet` as per mainter `@oop7` choise.
- simplify the logic.
* remove: import check, it should always work.
* **fix: runtime error**
- yt_dlp moved from `--excludes` to `--packages` in `build-windows.yml`
- In frozen build, logger will not log to consol. insted will log to file.
- In frozen build, `app_dir` is next to `.exe` file.
* chang back to checking import for ytdlp
* Bump version to 4.8.1
Update version references from 4.8.0b to 4.8.1 in __init__.py, main app, and About dialog to reflect the new release.
* Update asset paths in build workflows
Changed asset inclusion and screenshot removal paths from 'assets' to 'lib/assets' in Linux, macOS, and Windows build workflows to reflect new directory structure and ensure screenshots are excluded from packaged builds.
* Bump version to 4.8.2
Update version references from 4.8.1 to 4.8.2 in source files and documentation to prepare for a new patch release.
* Fix asset include path in Windows build workflow
Corrects the syntax for including asset files in the build-windows.yml workflow by changing 'assets,lib/assets' to 'assets=lib/assets'. This ensures assets are properly mapped during the build process.
* Update release tag examples in CI/CD README
Changed the example git tag commands from v4.8.0 and v4.8.2 to v4.8.1 for consistency in the CI/CD documentation.
* Fix include-files mapping in Windows build workflow
Changed the cx_Freeze --include-files argument from '=' to ':' for source:destination mapping in build-windows.yml. This resolves an issue where '=' was treated as a literal path, ensuring assets are correctly copied to the destination directory.
* Remove redundant comments in build-windows workflow
Deleted comments explaining the colon usage for source:destination mapping in the cx_Freeze CLI, as the mapping is already clear from the context.
* Refactor Windows build to use cx_Freeze setup script
Replaces direct cx_Freeze CLI calls with dynamically generated setup scripts for both standard and FFmpeg builds. This improves maintainability and flexibility of build configuration in the GitHub Actions workflow.
* Bump version to 4.8.3
Updated version references from 4.8.2 to 4.8.3 in __init__.py, main app, and About dialog to reflect the new release.
* revert(build): move yt_dlp from --packages to --excludes in build-windows.yml
---------
Co-authored-by: Your Name <mohamed.mohamed112@ai.mnu.edu.eg>
A modern YouTube downloader with a clean PySide6 interface.
Download videos in any quality, extract audio, fetch subtitles, and more.
Installation • Features • Usage • Screenshots • Troubleshooting • Contributing
❓ 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
- Cross-platform support and easy installation
✨ Features
| Core Features | Advanced Features | Extra Features |
|---|---|---|
| 🎥 Format Table | 🚫 SponsorBlock Integration | 💾 Save Download Path |
| 🎵 Audio Extraction | 📝 Multi-Subtitle Select & Merge | 🔄 Auto-Update yt-dlp |
| ✨ Simple UI | 💾 Save Description | 🛠️ FFmpeg/yt-dlp Detection |
| 📋 Playlist Support | 🖼️ Save thumbnail | ⚙️ Custom Commands |
| 🖼️ Playlist Selector | 🚀 Speed Limiter | 🍪 Login with Cookies |
| 📑 Embed Chapters | ✂️ Trim Video Sections |
🚀 Installation
⚡ Quick Install (Recommended)
Install YTSage from PyPI:
pip install ytsage
Then launch the app:
ytsage
📦 Pre-built Executables
🪟 Windows
| Format | Description |
|---|---|
 |
Standard installer |
 |
With FFmpeg bundled |
 |
Portable version, no installation required |
 |
Portable with FFmpeg, zipped |
🐧 Linux
| Format | Description |
|---|---|
 |
Debian package |
 |
AppImage, portable |
 |
RPM package |
🍎 macOS
| Format | Description |
|---|---|
 |
Zipped application for ARM64 |
 |
Disk image installer for ARM64 |
 |
Zipped application for x64 |
 |
Disk image installer for x64 |
🛠️ Manual Installation from Source
1. Clone the Repository
git clone https://github.com/oop7/YTSage.git
cd YTSage
2. Install Dependencies
⚡ With uv
uv pip install -r requirements.txt
📦 Or with standard pip
pip install -r requirements.txt
3. Run the Application
python main.py
📸 Screenshots
|
 |
| Main Interface | Playlist Download |
 |
 |
| Audio Format | Subtitle Options |
📖 Usage
🎯 Basic Usage
- Launch YTSage
- Paste YouTube URL (or use "Paste URL" button)
- Click "Analyze"
- Select Format:
Videofor video downloadsAudio Onlyfor audio extraction
- Choose Options:
- Enable subtitles & select language
- Enable subtitle merge
- Save thumbnail
- Remove sponsor segments
- Save description
- Embed chapters
- Select Output Directory
- Click "Download"
📋 Playlist Download
- Paste Playlist URL
- Click "Analyze"
- Select videos from the playlist selector (optional, defaults to all)
- Choose desired format/quality
- Click "Download"
💡 The application automatically handles the download queue
🧰 Advanced Options
- Quality Selection: Choose the highest resolution for best quality
- Subtitle Options: Filter languages and embed into video
- Custom Commands: Access advanced yt-dlp features
- Save Description: Save the description of the video
- Save Thumbnail: Save the thumbnail of the video
- Embed Chapters: Embed chapter markers as metadata in the downloaded video file for compatible video players
- Remove Sponsor Segments: Remove sponsor segments from the video
- Speed Limiter: Limit the download speed
- Login with Cookies: Login 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. Select your browser (Chrome, Firefox, etc.) and then select Profile (optional).
- Alternatively, extract cookies manually:
a. Extract cookies from your browser using an extension like cookie-editor
b. Copy the cookies in Netscape format
c. Create a file named
cookies.txtand paste the cookies into it d. Select thecookies.txtfile in the app
- Save Download Path: Save the download path
- Update yt-dlp: Update yt-dlp
- FFmpeg/yt-dlp Detection: Automatically detect FFmpeg/yt-dlp
- Trim Video: Download only specific parts of a video by specifying time ranges (HH:MM:SS format)
🛠️ Troubleshooting
Click to view common issues and solutions
- Format table not displaying: Update yt-dlp to the latest version.
- 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<version>-ffmpeg.exefile, which comes bundled with FFmpeg.
- Solution: Ensure FFmpeg is installed and accessible in your system's PATH. For Windows users, the easiest option is to download the
🛡️ 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
- ✅ 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.
- Open Terminal (you can find it using Spotlight).
- Type the following command but do not press Enter yet. Make sure to include the space at the end:
xattr -d com.apple.quarantine - Drag the
YTSage.appfile from your Finder window and drop it directly into the Terminal window. This will automatically paste the correct file path. - Press Enter to run the command.
- 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
👥 Contributing
We welcome contributions! Here's how you can help:
- 🍴 Fork the repository
- 🌿 Create your feature branch:
git checkout -b feature/AmazingFeature
- 💾 Commit your changes:
git commit -m 'Add some AmazingFeature'
- 📤 Push to the branch:
git push origin feature/AmazingFeature
- 🔄 Open a Pull Request
📂 Project Structure
YTSage - Project Structure
This document describes the organized folder structure of YTSage.
📁 Project Structure
YTSage/
├── 📁 .github/ # GitHub configuration
│ ├── 📄 CI_CD_README.md # CI/CD documentation
│ ├── 📁 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
├── .gitignore # Git ignore rules
├── 📁 assets/ # Static assets and resources
│ ├── 📁 branding/ # Branding assets
│ │ ├── 📁 icons/ # Application icons
│ │ │ ├── icon.icns # macOS icon
│ │ │ ├── icon.png # PNG icon
│ │ │ └── YTSage.ico # Windows icon
│ │ └── 📁 screenshots/ # Screenshots for documentation
│ │ ├── audio_format.png
│ │ ├── main.png
│ │ ├── playlist.png
│ │ └── subtitle_options.png
│ │ └── 📁 svg/ # SVG assets
│ │ └── ytsage-wordmark.svg
│ ├── 📁 Icon/ # Legacy icon directory
│ │ └── icon.png
│ └── 📁 sound/ # Audio files
│ └── notification.mp3
├── 📄 LICENSE # License file
├── 📄 main.py # Application entry point
├── 📄 README.md # Project documentation
├── 📄 requirements.txt # Python dependencies
└── 📁 src/ # Source code
├── 📄 __init__.py # Main package init
├── 📁 core/ # Core business logic
│ ├── 📄 __init__.py # Core package init
│ ├── 📄 ytsage_downloader.py # Download functionality
│ ├── 📄 ytsage_ffmpeg.py # FFmpeg integration
│ ├── 📄 ytsage_logging.py # Logging utilities
│ ├── 📄 ytsage_style.py # UI styling
│ ├── 📄 ytsage_utils.py # Utility functions
│ └── 📄 ytsage_yt_dlp.py # yt-dlp integration
├── 📁 gui/ # User interface components
│ ├── 📄 __init__.py # GUI package init
│ ├── 📄 ytsage_gui_format_table.py # Format table functionality
│ ├── 📄 ytsage_gui_main.py # Main application window
│ ├── 📄 ytsage_gui_video_info.py # Video information display
│ └── 📁 ytsage_gui_dialogs/ # Dialog classes
│ ├── 📄 __init__.py # Dialogs package init
│ ├── 📄 ytsage_dialogs_base.py # Basic dialogs
│ ├── 📄 ytsage_dialogs_custom.py # Custom functionality dialogs
│ ├── 📄 ytsage_dialogs_ffmpeg.py # FFmpeg-related dialogs
│ ├── 📄 ytsage_dialogs_selection.py # Selection dialogs
│ ├── 📄 ytsage_dialogs_settings.py # Settings dialogs
│ └── 📄 ytsage_dialogs_update.py # Update dialogs
└── 📁 utils/ # Utility modules
├── 📄 __init__.py # Utils package init
└── 📄 ytsage_constants.py # Application constants
⭐️ Star History
Star History
📜 License
This project is licensed under the MIT License - see the 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.
| Core Components | |
|---|---|
| yt-dlp | Download Engine |
| FFmpeg | Media Processing |
| Libraries & Frameworks | |
| PySide6 | GUI Framework |
| Pillow | Image Processing |
| requests | HTTP Requests |
| packaging | Version & Package Handling |
| markdown | Markdown Rendering |
| pyglet | Audio Playback |
| 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 creators' rights.
Made with ❤️ by oop7