Building, upstream tracking and YTSage's own README moved to the wiki; README
points there.
The history is not rewritten, unlike every other repository here. This one
still merges from oop7/YTSage and a rewrite would change every commit id, which
costs more than a clean history is worth in a fork. .github/ and
readme-translations/ are upstream's files and stay where upstream put them.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The internal ytsage package name is kept deliberately - renaming it
would touch every file and destroy the ability to merge upstream
YTSage changes.
- pyproject: distribution name sagetube v0.1.0, sagetube entrypoint
(ytsage alias retained), URLs point at the Gitea repo with an
Upstream link to YTSage.
- Data dirs move to SageTube/ (fresh fork, fresh state) and the config
file becomes sagetube_config.json; QApplication name and window
title read SageTube.
- About dialog credits Houmeres and links "Based on YTSage by oop7".
- App self-update check against the upstream PyPI package is disabled
by default; yt-dlp/deno/ffmpeg update flows are unaffected.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-25 02:45:58 +02:00
10 changed files with 91 additions and 652 deletions
A watch-first YouTube client for the desktop — search, browse channels and playlists, follow subscriptions, and stream videos in an embedded mpv player, with full yt-dlp download capability inherited from [YTSage](https://github.com/oop7/YTSage).
A watch-first YouTube client for the desktop. Search, browse channels and
playlists, follow subscriptions, and stream videos in an embedded mpv player —
with the full yt-dlp download feature set inherited from
[YTSage](https://github.com/oop7/YTSage).
SageTube is a fork of [YTSage](https://github.com/oop7/YTSage) by [oop7](https://github.com/oop7) (MIT). The original YTSage documentation is preserved at [docs/UPSTREAM_README.md](docs/UPSTREAM_README.md).
## Features
## Status
**Watching**
- 📺 Embedded mpv player (Wayland/X11/Windows/macOS) with quality selector,
speed, volume, subtitles, fullscreen
- 🔍 In-app YouTube search with thumbnail card grid
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
```
</details>
#### 🍎 macOS
| Format | Description |
|--------|-------------|
|  | Zipped Application for Apple Silicon |
|  | Disk Image Installer for Apple Silicon |
<details>
<summary>🛠️ Installation Steps</summary>
- **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.*
- **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).
</details>
<details>
<summary>🌐 Access & Network</summary>
- **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://<proxy-server>:<port>`
- **Generic Mode:** Allows YTSage to analyze and download from non-YouTube sites supported by yt-dlp. Enable from **Download Settings → Generic Mode**.
</details>
<details>
<summary>🛠️ Tools & Maintenance</summary>
- **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.
</details>
<details>
<summary>🌍 Localization</summary>
YTSage supports **14 languages** for global accessibility. Select your preferred language in **Custom Options → Language**.
> 💡 **Want to contribute a translation?** Check out the [Contributing](#contributing) section to help us add more languages!
</details>
<a id="troubleshooting"></a>
## 🛠️ Troubleshooting
<details>
<summary>Click to view common issues and solutions</summary>
- **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<version>-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.
- ✅ **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.
If YTSage saves you time, please consider sponsoring the project. Sponsoring helps cover development time, testing across all platforms, and future improvements.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Homer
Jaroslav Beneš