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 & select language
   • Enable subtitle merge
   • Save thumbnail
   • Remove sponsor segments
   • Save description
   • Embed chapters
6. Select Output Directory
7. Click "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

• 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:
  1. Extract cookies from your browser using an extension like cookie-editor
  2. Copy the cookies in Netscape format
  3. Create a file named cookies.txt and paste the cookies into it
  4. Select the cookies.txt file 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)

• Format table not displaying: Update yt-dlp to the latest version.
• Download fails: Check your internet connection and ensure the video is available.
• 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.exe file, which comes bundled with FFmpeg.

Some antivirus software may flag the .exe files as false positives. This is a known limitation of PyInstaller-packaged applications.

Why this happens:

• PyInstaller bundles Python runtime and libraries together
• Antivirus heuristics can misidentify packed executables as suspicious
• This affects many legitimate Python applications built with PyInstaller

Safe alternatives:

• ✅ Use pip installation: pip install ytsage (recommended)
• ✅ Build from source
• ✅ Whitelist the application in your antivirus software

📋 Related Issues: #33 - This is a known PyInstaller limitation, not a security issue with YTSage itself.

If you see this error on macOS Sonoma or newer, you need to remove the quarantine attribute.

1. Open Terminal (you can find it 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.

• Windows: %LOCALAPPDATA%\YTSage
• macOS: ~/Library/Application Support/YTSage
• Linux: ~/.local/share/YTSage

This document describes the organized folder structure of YTSage.

YTSage-main/
├── 📁 assets/                    # Static assets and resources
│   ├── 📁 Icon/                  # Application icons
│   │   └── icon.png
│   └── 📁 sound/                 # Audio files
│       └── notification.mp3
│
├── 📁 src/                       # Source code
│   ├── 📁 core/                  # Core business logic
│   │   ├── __init__.py           # Core package init
│   │   ├── ytsage_downloader.py  # Download functionality
│   │   ├── ytsage_ffmpeg.py      # FFmpeg integration
│   │   ├── ytsage_style.py       # UI styling
│   │   ├── ytsage_utils.py       # Utility functions
│   │   └── ytsage_yt_dlp.py      # yt-dlp integration
│   │
│   ├── 📁 gui/                   # User interface components
│   │   ├── 📁 dialogs/           # Dialog classes
│   │   │   ├── __init__.py       # Dialogs package init (re-exports all)
│   │   │   ├── ytsage_dialogs_base.py     # Basic dialogs (Log, About)
│   │   │   ├── 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
│   │   │
│   │   ├── __init__.py           # GUI package init
│   │   ├── ytsage_gui_dialogs.py # Dialog aggregator (backward compatibility)
│   │   ├── ytsage_gui_format_table.py # Format table functionality
│   │   ├── ytsage_gui_main.py    # Main application window
│   │   └── ytsage_gui_video_info.py # Video information display
│   │
│   └── __init__.py               # Main package init
│
├── 📄 main.py                    # Application entry point
├── 📄 requirements.txt           # Python dependencies
├── 📄 README.md                  # Project documentation
├── 📄 LICENSE                    # License file
└── 📄 .gitignore                 # Git ignore rules