diff --git a/Building.md b/Building.md new file mode 100644 index 0000000..13421af --- /dev/null +++ b/Building.md @@ -0,0 +1,48 @@ +# Building & running SageTube + +## Requirements + +- Python >= 3.10 +- **libmpv** (system library; `python-mpv` binds to it at runtime) + - Arch: `sudo pacman -S mpv` + - Debian/Ubuntu: `sudo apt install libmpv2` + - Fedora: `sudo dnf install mpv-libs` + - macOS: `brew install mpv` + - Windows: place `libmpv-2.dll` next to the executable (builds from + https://github.com/shinchiro/mpv-winbuild-cmake/releases), or install mpv + and add it to PATH +- ffmpeg (for download merging; the app can auto-install it) + +Without libmpv the app still runs — the Watch tab shows an install hint and +search/browse/download work normally. + +## Run from source + +```bash +python -m venv .venv && source .venv/bin/activate +pip install -e . +sagetube +``` + +On first start the app downloads its own SHA256-verified `yt-dlp` binary and +the Deno runtime (yt-dlp's JS challenge solver) into the SageTube data dir: + +- Linux: `~/.local/share/SageTube/bin/` +- macOS: `~/Library/Application Support/SageTube/bin/` +- Windows: `%LOCALAPPDATA%\SageTube\bin\` + +## Notes on YouTube playback reliability + +Playback resolves streams through mpv's `ytdl_hook` using the managed yt-dlp. +YouTube's CDN intermittently serves stalled streams to non-browser clients; +the player retries automatically (twice, after 25 s of no playback). Keeping +yt-dlp updated (built-in updater, stable or nightly channel) is the long-term +fix channel for extractor breakage. + +## Release workflows + +The `.github/workflows/` files are inherited from upstream YTSage and target +GitHub runners; they do not run on Gitea. If you set up Gitea Actions, note +that the upstream Linux/Windows workflows download appimagetool and a bundled +ffmpeg **without checksum verification** — add hash checks before reusing +them for release artifacts. diff --git a/Home.md b/Home.md index a3e8842..bbd273f 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,33 @@ -Placeholder. Replaced by the first push. \ No newline at end of file +# SageTube + +A watch-first desktop YouTube client with an embedded **mpv** player — a fork of +[oop7/YTSage](https://github.com/oop7/YTSage) that keeps the upstream git history +and the internal `ytsage` package name so improvements can still be merged in. + +Source: [`Houmeres/SageTube`](https://git.houmeres.sk/Houmeres/SageTube) · +what it is and how to install it is in the +[README](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/README.md). + +| Page | What it is | +|---|---| +| [Building](Building) | Requirements, building and running from source — including the mpv piece, without which the app is a downloader rather than a player. | +| [Tracking-upstream](Tracking-upstream) | How the fork relates to YTSage, and how a merge from upstream is done. | +| [Upstream-README](Upstream-README) | YTSage's own README, kept verbatim for reference. | + +## This repository is a fork, and it is treated as one + +**Its history has not been rewritten.** Every other repository in this org had +its documentation removed from every commit on 2026-08-08; SageTube did not, +because rewriting changes every commit id and would end the ability to merge from +upstream. The documentation moved here in an ordinary commit instead, and the +history behind it is untouched and still shares ancestry with YTSage. + +Two consequences worth knowing: + +- The `vX.Y.Z` tags on this repository are **upstream's**, not SageTube's. They + came with the history. +- `upstream` is a real remote pointing at GitHub. **Never push to it.** A local + read-only clone of it lives at `Github/YTSage` in the same tree. + +`.github/` and `readme-translations/` are upstream's files and are deliberately +left where they are — moving them would only create conflicts on the next merge. diff --git a/Tracking-upstream.md b/Tracking-upstream.md new file mode 100644 index 0000000..a007249 --- /dev/null +++ b/Tracking-upstream.md @@ -0,0 +1,38 @@ +# Tracking upstream YTSage + +SageTube keeps the full git history of [YTSage](https://github.com/oop7/YTSage) +and the internal `ytsage` package name so upstream improvements can be merged. + +## Syncing + +```bash +git fetch upstream # upstream = https://github.com/oop7/YTSage.git +git merge upstream/main +``` + +## Expected conflict zones + +Most SageTube features live in **new files** and merge cleanly. Conflicts are +likely only in: + +| File | Reason | +|---|---| +| `ytsage/gui/ytsage_gui_main.py` | tab-shell edit in `init_ui` (`_setup_main_tabs`), closeEvent hook | +| `ytsage/gui/ytsage_gui_analysis.py` | delegates subprocess execution to `YtdlpClient` | +| `ytsage/utils/ytsage_constants.py` | SageTube data dirs, PATH prepend for managed binaries | +| `ytsage/utils/ytsage_config_manager.py` | atomic save, defaults merge, player/feed/advanced keys | +| `pyproject.toml` | name, version, deps (python-mpv), URLs | +| `ytsage/languages/en.json` | added sections: player, cards, main_tabs, search, watch, browse, feed | + +Bug fixes made in this fork (see git log between the merge commit and the +first feature commit) may also conflict if upstream fixes them differently — +prefer whichever version is stricter about verification and thread safety. + +## SageTube-only modules (never conflict) + +- `ytsage/core/ytsage_client.py` — shared yt-dlp JSON invocation layer +- `ytsage/core/ytsage_mpv.py` — libmpv probe +- `ytsage/gui/ytsage_gui_player.py` — embedded mpv player +- `ytsage/gui/ytsage_gui_watch.py` / `_search.py` / `_browse.py` / `_feed.py` — tabs +- `ytsage/gui/ytsage_gui_router.py` / `_cards.py` — navigation + video cards +- `ytsage/utils/ytsage_library_manager.py` — subscriptions/history/queue DB diff --git a/Upstream-README.md b/Upstream-README.md new file mode 100644 index 0000000..6699f0a --- /dev/null +++ b/Upstream-README.md @@ -0,0 +1,624 @@ +
+ +ytsage-wordmark +YTSage Interface + +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-1f2937?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) +[![PyPI Downloads](https://img.shields.io/pepy/dt/ytsage?color=1f2937&style=for-the-badge&label=downloads&logo=python&logoColor=white)](https://pepy.tech/project/ytsage) +[![GitHub Downloads](https://img.shields.io/github/downloads/oop7/YTSage/total?color=1f2937&style=for-the-badge&label=downloads&logo=github&logoColor=white)](https://github.com/oop7/YTSage/releases) +[![License: MIT](https://img.shields.io/badge/License-MIT-1f2937?style=for-the-badge&logo=opensource&logoColor=white)](https://opensource.org/licenses/MIT) +[![Supported Platforms](https://img.shields.io/badge/platform-cross--platform-1f2937?style=for-the-badge&logo=github&logoColor=white)](https://github.com/oop7/YTSage/releases) +[![GitHub Stars](https://img.shields.io/github/stars/oop7/YTSage?color=c90000&style=for-the-badge&logo=github&logoColor=white)](https://github.com/oop7/YTSage/stargazers) +[![PyPI version](https://img.shields.io/pypi/v/ytsage?color=c90000&style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ytsage/) +[![GitHub Sponsors](https://img.shields.io/github/sponsors/oop7?color=c90000&style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/oop7) + +**Modern YouTube downloader with a clean PySide6 interface.** +Download videos in any quality, extract audio, fetch subtitles, and more. + +### 🌍 README Languages + +English: [EN](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/README.md) +| Arabic: [AR](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ar.md) +| German: [DE](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.de.md) +| Spanish: [ES](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.es.md) +| French: [FR](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.fr.md) +| Hindi: [HI](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.hi.md) +| Indonesian: [ID](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.id.md) +| Italian: [IT](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.it.md) +| Japanese: [JA](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ja.md) +| Polish: [PL](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.pl.md) +| Portuguese: [PT](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.pt.md) +| Russian: [RU](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ru.md) +| Turkish: [TR](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.tr.md) +| Chinese: [ZH](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.zh.md) + +

+ 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: + +```bash +pip install ytsage +``` + +
+🔄 Update existing installation + +```bash +pip install --upgrade ytsage +``` + +
+ +Then launch the application: + +```bash +ytsage +``` + +### 📦 Pre-built Executables + +> [👉 Download Latest Release](https://github.com/oop7/YTSage/releases/latest) + +#### 🪟 Windows + +| Format | Description | +|--------|-------------| +| ![Windows EXE](https://img.shields.io/badge/Windows-EXE-0078D6?style=for-the-badge&logo=windows&logoColor=white) | Standard Installer | +| ![Windows FFmpeg](https://img.shields.io/badge/Windows-FFmpeg-0078D6?style=for-the-badge&logo=windows&logoColor=white) | With FFmpeg Included | +| ![Windows Portable](https://img.shields.io/badge/Windows-Portable-0078D6?style=for-the-badge&logo=windows&logoColor=white) | Portable version, no installation needed | +| ![Windows Portable FFmpeg](https://img.shields.io/badge/Windows-Portable%20FFmpeg-0078D6?style=for-the-badge&logo=windows&logoColor=white) | 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 | +|--------|-------------| +| ![Linux DEB](https://img.shields.io/badge/Linux-DEB-FCC624?style=for-the-badge&logo=linux&logoColor=black) | Debian Package | +| ![Linux AppImage](https://img.shields.io/badge/Linux-AppImage-FCC624?style=for-the-badge&logo=linux&logoColor=black) | AppImage, Portable | +| ![Linux RPM](https://img.shields.io/badge/Linux-RPM-FCC624?style=for-the-badge&logo=linux&logoColor=black) | RPM Package | +| ![Flathub](https://img.shields.io/badge/Linux-Flatpak-FCC624?style=for-the-badge&logo=flathub&logoColor=black) | 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 | +|--------|-------------| +| ![macOS ARM64 APP](https://img.shields.io/badge/macOS-ARM64%20APP-000000?style=for-the-badge&logo=apple&logoColor=white) | Zipped Application for Apple Silicon | +| ![macOS ARM64 DMG](https://img.shields.io/badge/macOS-ARM64%20DMG-000000?style=for-the-badge&logo=apple&logoColor=white) | 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 + +```bash +git clone https://github.com/oop7/YTSage.git +cd YTSage +``` + +### 2. Install dependencies + +#### ⚡ Using uv + +```bash +uv pip install . +``` + +#### 📦 Or using standard pip + +```bash +pip install . +``` + +### 3. Run the application + +```bash +python -m ytsage.main +``` + +
+ + +## 📸 Screenshots + +
+ + + + + + + + + + + + + + + + + +
Download SettingsPlaylist Download
Download SettingsPlaylist Download
Audio Format SelectionCustom Options
Audio FormatCustom Options
+
+ + +## 📖 Usage + +
+🎯 Basic Usage + +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 and select language + - Enable Subtitle Merging + - Save Thumbnail + - Remove Sponsored Segments + - Save Description + - Embed Chapters +6. **Select Output Directory** +7. **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: + 1. **Recommended:** Use the built-in `Extract cookies from browser` option in the app, then select your browser and optionally a profile. + 2. Alternatively, extract cookies manually: + a. Export browser cookies using an extension like [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file) + 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://:` +- **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 thumbnails and statuses from the **History** button. + +
+ +
+🌍 Localization + +YTSage supports **14 languages** for global accessibility. Select your preferred language in **Custom Options → Language**. + +### Supported Languages + +| Language | Code | Language | Code | +|----------|------|----------|------| +| 🇺🇸 English | `en` | 🇪🇸 Spanish | `es` | +| 🇸🇦 Arabic | `ar` | 🇫🇷 French | `fr` | +| 🇩🇪 German | `de` | 🇮🇳 Hindi | `hi` | +| 🇮🇩 Indonesian | `id` | 🇮🇹 Italian | `it` | +| 🇯🇵 Japanese | `ja` | 🇵🇱 Polish | `pl` | +| 🇧🇷 Portuguese | `pt` | 🇷🇺 Russian | `ru` | +| 🇹🇷 Turkish | `tr` | 🇨🇳 Chinese | `zh` | + +### README Translations + +| Language | File | Language | File | +|----------|------|----------|------| +| 🇺🇸 English | [README.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/README.md) | 🇪🇸 Spanish | [readme-translations/README.es.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.es.md) | +| 🇸🇦 Arabic | [readme-translations/README.ar.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ar.md) | 🇫🇷 French | [readme-translations/README.fr.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.fr.md) | +| 🇩🇪 German | [readme-translations/README.de.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.de.md) | 🇮🇳 Hindi | [readme-translations/README.hi.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.hi.md) | +| 🇮🇩 Indonesian | [readme-translations/README.id.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.id.md) | 🇮🇹 Italian | [readme-translations/README.it.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.it.md) | +| 🇯🇵 Japanese | [readme-translations/README.ja.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ja.md) | 🇵🇱 Polish | [readme-translations/README.pl.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.pl.md) | +| 🇧🇷 Portuguese | [readme-translations/README.pt.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.pt.md) | 🇷🇺 Russian | [readme-translations/README.ru.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.ru.md) | +| 🇹🇷 Turkish | [readme-translations/README.tr.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.tr.md) | 🇨🇳 Chinese | [readme-translations/README.zh.md](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/readme-translations/README.zh.md) | + +> 💡 **Want to contribute a translation?** Check out the [Contributing](#contributing) section to help us add more languages! + +
+ + +## 🛠️ Troubleshooting + +
+Click to view common issues and solutions + +- **Format table not appearing:** Update yt-dlp to latest version and switch to nightly yt-dlp. +- **Download failed:** 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:** Log in to your YouTube account to view age-restricted videos. + - **Geo-Blocked Videos:** Consider using a VPN to bypass regional restrictions. + - **Deleted Videos:** Video is no longer available on YouTube. + - **Live Streams:** Live streams cannot be downloaded; wait for the broadcast 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 a YouTube Premium subscription. + - **Copyright Blocks:** Content is blocked due to copyright restrictions. +- **Video and Audio Files separate 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-ffmpeg.exe` file, which comes bundled with FFmpeg. + +--- + +#### 🛡️ Windows Defender / Antivirus Warning + +Some antivirus software may flag `.exe` files as false positives. This is a **known limitation** of packaged applications. + +**Why this happens:** +- Antivirus heuristics can mistakenly identify packaged executables as suspicious. + +**Safe Alternatives:** +- ✅ **Use pip install:** `pip install ytsage` (Recommended) +- ✅ **Build from Source**: by following this [guide](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/github/CI_CD_README.md) +- ✅ **Whitelist the app** in your antivirus software. + +#### 🍎 macOS: "Application is damaged and cannot be opened" +If you see this error on macOS Sonoma or newer, you need to remove the quarantine attribute. + +1. **Open Terminal** (you can find this using Spotlight). +2. **Type the following command** but **do not** press Enter yet. Make sure to include the space at the end: + ```bash + 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. + +--- + +#### **Config Locations (Advanced)** +- **Windows:** `%LOCALAPPDATA%\YTSage` +- **macOS:** `~/Library/Application Support/YTSage` +- **Linux:** `~/.local/share/YTSage` + +
+ + +## 💖 Sponsor + +If YTSage saves you time, please consider sponsoring the project. Sponsoring helps cover development time, testing across all platforms, and future improvements. + +- GitHub Sponsors: https://github.com/sponsors/oop7 +- Sponsorship link is also available directly in the app via the About dialog. + +[![Sponsor YTSage](https://img.shields.io/badge/Sponsor-YTSage-EA4AAA?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/oop7) + + +## 👥 Contributing + +We welcome contributions! Here’s how you can help: + +1. 🍴 Fork the repository +2. 🌿 Create your feature branch: + ```bash + git checkout -b feature/AmazingFeature + ``` +3. 💾 Commit your changes: + ```bash + git commit -m 'Add some AmazingFeature' + ``` +4. 📤 Push to the branch: + ```bash + git push origin feature/AmazingFeature + ``` +5. 🔄 Open a Pull Request + +### 🌍 Contributing Translations + +- Update the relevant localized README file (e.g., `readme-translations/README.fr.md`) +- Keep app strings synced by editing `ytsage/languages/.json` +- If your language is missing, start from `README.md` and create `readme-translations/README..md` + +
+📂 Project Structure + +## YTSage - Project Structure + +This document describes the organized folder structure of YTSage. + +### 📁 Project Structure + +``` +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 +| | └── release-all.yml # Release master workflow +│ └── 📄 CI_CD_README.md # CI/CD documentation +├── 📁 branding/ # Branding assets (Screenshots, SVGs) +│ ├── 📁 icons/ # App icons +│ ├── 📁 screenshots/ # Documentation screenshots +│ └── 📁 svg/ # SVG assets +├── 📄 LICENSE # License file +├── 📄 pyproject.toml # Project metadata and dependencies +├── 📄 README.md # Project documentation +├── 📄 requirements.txt # Python dependencies (dev) +└── 📁 ytsage/ # Source package + ├── 📁 assets/ # Runtime assets + │ ├── 📁 Icon/ # App icons + │ └── 📁 sound/ # Sound files + ├── 📁 languages/ # Localization files + │ ├── 📄 ar.json # Arabic translation + │ ├── 📄 de.json # German translation + │ ├── 📄 en.json # English translation + │ └── ... # Other languages + ├── 📁 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/ # UI components + │ ├── 📄 __init__.py # GUI package init + │ ├── 📄 ytsage_gui_main.py # Main app window + │ └── 📁 ytsage_gui_dialogs/ # Dialog classes + ├── 📁 utils/ # Utility modules + │ ├── 📄 __init__.py # Utils package init + │ ├── 📄 ytsage_config_manager.py # Config management + │ └── 📄 ytsage_logger.py # Logging utilities + ├── 📄 __init__.py # Package entry point + └── 📄 main.py # Main execution script +``` + +
+ +## ⭐️ Star History + +
+ +## Star History + + + + + + Star History Chart + + + +
+ +## 📜 License + +This project is licensed under the MIT License - see the [LICENSE](https://git.houmeres.sk/Houmeres/SageTube/src/branch/main/LICENSE) file for details. + +## 🙏 Acknowledgments + +
+Show Acknowledgments + +
+ +

A big thanks to everyone who contributed to this project by opening an issue to suggest an improvement or report a bug.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Core Components
yt-dlpDownload Engine
FFmpegMedia Processing
DenoRuntime for yt-dlp plugins
Libraries & Frameworks
PySide6GUI Framework
PillowImage Processing
requestsHTTP Requests
packagingVersion/Package Management
markdownMarkdown Rendering
loguruLogging
Assets & Contributors
New Notification 09 by UniversfieldNotification Sound
viru185Code Contributor
+ +
+ +
+ +## ⚠️ Disclaimer + +This tool is for personal use only. Please respect YouTube's Terms of Service and content creator rights. + +--- + +
+ +Made with ❤️ by [oop7](https://github.com/oop7) + +