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"

💡 The default download directory is the user's "Downloads" folder.

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

• Subtitle Options: Filter languages and embed into video file
• Subtitle Merge: Merge subtitles into video file for hardcoded subtitles
• Custom Commands: Access advanced yt-dlp features via command line arguments
• Save Description: Save the description of the video as a text file
• Save Thumbnail: Save the thumbnail of the video as an image file
• 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 using SponsorBlock
• Speed Limiter: Limit the download speed (e.g., 500K for 500 KB/s)
• Login with Cookies: Login 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. Select your browser (Chrome, Firefox, etc.) and then select Profile (optional).
  2. 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.txt and paste the cookies into it d. Select the cookies.txt file in the app
• Save Download Path: Save the default download path for future downloads. Available in Download Settings → Download Path.
• Updater Tab: Unified tab in Custom Options for managing all updates:
  • yt-dlp Updates: Check and update yt-dlp to the latest version, with release channel selection (Stable/Nightly)
  • FFmpeg Version Checker: Check your FFmpeg version with direct links to installation guides
  • Deno Updates: Check and update Deno runtime to the latest version
• FFmpeg/yt-dlp/Deno Detection: Automatically detect FFmpeg/yt-dlp/Deno path and version. You can use this option by clicking on about button.
• Trim Video: Download only specific parts of a video by specifying time ranges (HH:MM:SS format)
• Proxy Support: Use a proxy server for downloads (e.g., http://<proxy-server>:<port>)
• Force Output Format: Force video downloads in a specific container format (e.g., mp4, webm, mkv). Available in Download Settings → Audio Format Settings.
• Audio Format Conversion: Convert audio-only downloads to preferred formats (AAC, MP3, FLAC, WAV, Opus, M4A, Vorbis, or Best). Ideal for video editing software like DaVinci Resolve. Available in Download Settings → Audio Format Settings.
• Download History: View past downloads with thumbnails and statuses. You can use this option by clicking on download settings button.

YTSage supports 14 languages for worldwide accessibility. Select your preferred language from Custom Options → Language.

💡 Want to contribute a translation? Check out the Contributing section to help us add more languages!

• Format table not displaying: Update yt-dlp to the latest version, and switch to yt-dlp nightly.
• 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.exe file, which comes bundled with FFmpeg.

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

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/
├── 📁 .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
│   └── 📄 CI_CD_README.md        # CI/CD documentation
├──  📁 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
│   │   │   ├── Custom-Option.png
│   │   │   ├── Download-Settings.png
│   │   │   ├── playlist.png
│   │   │   └── main.png
│   │   └── 📁 svg/               # SVG assets
│   │       └── ytsage-wordmark.svg
│   │       └── ytsage-wordmark.svg
│   ├── 📁 Icon/                  # Legacy icon directory
│   │   └── icon.png
│   └── 📁 sound/                 # Audio files
│       └── notification.mp3
├── 📁 languages/                 # Localization files
│   ├── 📄 ar.json                # Arabic translation
│   ├── 📄 de.json                # German translation
│   ├── 📄 en.json                # English translation
│   ├── 📄 es.json                # Spanish translation
│   ├── 📄 fr.json                # French translation
│   ├── 📄 hi.json                # Hindi translation
│   ├── 📄 id.json                # Indonesian translation
│   ├── 📄 it.json                # Italian translation
│   ├── 📄 ja.json                # Japanese translation
│   ├── 📄 pl.json                # Polish translation
│   ├── 📄 pt.json                # Portuguese translation
│   ├── 📄 ru.json                # Russian translation
│   ├── 📄 tr.json                # Turkish translation
│   └── 📄 zh.json                # Chinese translation
├── 📄 LICENSE                    # License file
├── 📄 main.py                    # Application entry point
├── 📄 README.md                  # Project documentation
├── 📄 .gitignore                 # Git ignore rules
├── 📄 requirements.txt           # Python dependencies
└── 📁 src/                       # Source code
    |
    ├── 📁 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/                   # 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_history.py  # History dialogs
    │       ├── 📄 ytsage_dialogs_selection.py # Selection dialogs
    │       ├── 📄 ytsage_dialogs_settings.py  # Settings dialogs
    │       ├── 📄 ytsage_dialogs_update.py    # Update dialogs
    │       └── 📄 ytsage_dialogs_updater.py    # Updater dialogs
    └── 📁 utils/                 # Utility modules
        ├── 📄 __init__.py        # Utils package init
        ├── 📄 ytsage_config_manager.py # Configuration management
        ├── 📄 ytsage_constants.py # Application constants
        ├── 📄 ytsage_history_manager.py # History management
        ├── 📄 ytsage_localization.py # Localization utilities
        └── 📄 ytsage_logger.py   # Logging utilities