diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..164ac74 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +Kept as the work happens, not assembled at release time. Format is +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow +[SemVer](https://semver.org/spec/v2.0.0.html). + +**The `vX.Y.Z` tags already on this repository are upstream YTSage's**, inherited +with its history. SageTube's own versions start below and are the ones this file +records. + +## Unreleased + +### Changed + +- The documentation left the repository: `docs/BUILDING.md`, `docs/UPSTREAM.md` + and `docs/UPSTREAM_README.md` are now the + [wiki](https://git.houmeres.sk/Houmeres/SageTube/wiki). +- **The history was deliberately not rewritten.** Every other repository in this + org had its documentation removed from every commit on 2026-08-08. SageTube is + a fork that still merges from `oop7/YTSage`, and a rewrite changes every commit + id — which would end that. The files leave in an ordinary commit instead. +- `.github/` and `readme-translations/` are upstream's and were left alone, so + the next merge does not conflict over them. diff --git a/README.md b/README.md index 2c80414..3be45ef 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ with the full yt-dlp download feature set inherited from **Downloading** (from YTSage) - Format table, audio extraction, subtitles, SponsorBlock, chapters, playlists, trimming, speed limits, proxies, cookies, custom yt-dlp commands, - download history — see the [upstream README](docs/UPSTREAM_README.md) + download history — see the [upstream README](https://git.houmeres.sk/Houmeres/SageTube/wiki/Upstream-README) ## Install @@ -30,14 +30,14 @@ sagetube ``` Requires **libmpv** for playback (Arch: `pacman -S mpv`) — see -[docs/BUILDING.md](docs/BUILDING.md). Without it the app works as a downloader. +[Building](https://git.houmeres.sk/Houmeres/SageTube/wiki/Building). Without it the app works as a downloader. ## Fork notes SageTube is a fork of [YTSage](https://github.com/oop7/YTSage) by [oop7](https://github.com/oop7) (MIT). The internal package keeps the `ytsage` name so upstream fixes remain mergeable — see -[docs/UPSTREAM.md](docs/UPSTREAM.md). The fork also fixes a number of +[Tracking upstream](https://git.houmeres.sk/Houmeres/SageTube/wiki/Tracking-upstream). The fork also fixes a number of upstream bugs (unsafe partial-file cleanup, unverified binary updates, thread-safety issues, PATH corruption on Windows — see the git log). diff --git a/docs/BUILDING.md b/docs/BUILDING.md deleted file mode 100644 index 13421af..0000000 --- a/docs/BUILDING.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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/docs/UPSTREAM.md b/docs/UPSTREAM.md deleted file mode 100644 index a007249..0000000 --- a/docs/UPSTREAM.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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/docs/UPSTREAM_README.md b/docs/UPSTREAM_README.md deleted file mode 100644 index 5272e7a..0000000 --- a/docs/UPSTREAM_README.md +++ /dev/null @@ -1,624 +0,0 @@ -
- -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](README.md) -| Arabic: [AR](readme-translations/README.ar.md) -| German: [DE](readme-translations/README.de.md) -| Spanish: [ES](readme-translations/README.es.md) -| French: [FR](readme-translations/README.fr.md) -| Hindi: [HI](readme-translations/README.hi.md) -| Indonesian: [ID](readme-translations/README.id.md) -| Italian: [IT](readme-translations/README.it.md) -| Japanese: [JA](readme-translations/README.ja.md) -| Polish: [PL](readme-translations/README.pl.md) -| Portuguese: [PT](readme-translations/README.pt.md) -| Russian: [RU](readme-translations/README.ru.md) -| Turkish: [TR](readme-translations/README.tr.md) -| Chinese: [ZH](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](README.md) | 🇪🇸 Spanish | [readme-translations/README.es.md](readme-translations/README.es.md) | -| 🇸🇦 Arabic | [readme-translations/README.ar.md](readme-translations/README.ar.md) | 🇫🇷 French | [readme-translations/README.fr.md](readme-translations/README.fr.md) | -| 🇩🇪 German | [readme-translations/README.de.md](readme-translations/README.de.md) | 🇮🇳 Hindi | [readme-translations/README.hi.md](readme-translations/README.hi.md) | -| 🇮🇩 Indonesian | [readme-translations/README.id.md](readme-translations/README.id.md) | 🇮🇹 Italian | [readme-translations/README.it.md](readme-translations/README.it.md) | -| 🇯🇵 Japanese | [readme-translations/README.ja.md](readme-translations/README.ja.md) | 🇵🇱 Polish | [readme-translations/README.pl.md](readme-translations/README.pl.md) | -| 🇧🇷 Portuguese | [readme-translations/README.pt.md](readme-translations/README.pt.md) | 🇷🇺 Russian | [readme-translations/README.ru.md](readme-translations/README.ru.md) | -| 🇹🇷 Turkish | [readme-translations/README.tr.md](readme-translations/README.tr.md) | 🇨🇳 Chinese | [readme-translations/README.zh.md](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](.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](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) - -