---
## ❓ Почему YTSage?
YTSage создан для пользователей, которым нужен **простой, но мощный загрузчик с YouTube**. В отличие от других инструментов, он предлагает:
- Современный и чистый интерфейс PySide6
- Загрузку видео, аудио и субтитров одним щелчком мыши
- Дополнительные функции, такие как SponsorBlock, объединение субтитров и выбор плейлиста
- Опциональный "Общий режим" (Generic Mode) для сайтов помимо YouTube, поддерживаемых yt-dlp
- Кроссплатформенную поддержку и простую установку
## ✨ Функции
| Основные функции | Продвинутые функции | Дополнительные возможности |
|-----------------------------------|-----------------------------------------|------------------------------------|
| 🎥 Таблица форматов | 🚫 Интеграция SponsorBlock | 🎞️ Отображение FPS/HDR |
| 🎵 Извлечение аудио | 📝 Выбор и объединение субтитров | 🔄 Автообновление yt-dlp |
| ✨ Простой пользовательский интерфейс | 💾 Сохранение описания и обложки | 🛠️ Обнаружение FFmpeg/yt-dlp/Deno |
| 📋 Поддержка и выбор плейлиста | 🚀 Ограничение скорости | ⚙️ Пользовательские команды |
| 📑 Интеграция разделов | ✂️ Обрезка видео | 🍪 Вход через Cookies |
| 📜 История загрузок | 🔄 Выбор канала выпуска | 🌐 Поддержка прокси |
| 🎚️ Конвертация аудиоформатов | 🎬 Настройки видеоформата | 🆙 Встроенная вкладка обновления |
| 🌍 Общий режим | 🔊 Нормализация звука (EBU R128) | 🌍 Локализация на 14 языков |
| 💾 Экспорт плейлиста | ⚙️ Качество и субтитры по умолчанию | |
## 🚀 Установка
### ⚡ Быстрая установка (Рекомендуется)
Установите YTSage через PyPI:
```bash
pip install ytsage
```
🔄 Обновить существующую установку
```bash
pip install --upgrade ytsage
```
Затем запустите приложение:
```bash
ytsage
```
### 📦 Готовые исполняемые файлы (Executable)
> [👉 Скачать последний релиз](https://github.com/oop7/YTSage/releases/latest)
#### 🪟 Windows
| Формат | Описание |
|--------|-------------|
|  | Стандартный установщик |
|  | С включенным FFmpeg |
|  | Портативная версия (не требует установки) |
|  | Портативная с FFmpeg, сжатая (ZIP) |
🛠️ Шаги по установке
1. **EXE установщик (`.exe`)**: Дважды щелкните файл и следуйте инструкциям мастера установки.
2. **Портативная версия (`.zip`)**: Распакуйте файл в нужное место и запустите `ytsage.exe`.
3. **Встроенный FFmpeg**: Если в вашей системе не установлен FFmpeg, выбирайте версии со встроенным FFmpeg.
#### 🐧 Linux
| Формат | Описание |
|--------|-------------|
|  | Пакет Debian |
|  | AppImage, Портативный |
|  | Пакет RPM |
|  | Пакет Flatpak |
🛠️ Шаги по установке
- **DEB (`.deb`)**:
```bash
sudo dpkg -i ytsage_*.deb
sudo apt-get install -f # Если нужно исправить зависимости
```
- **RPM (`.rpm`)**:
```bash
sudo rpm -i ytsage-*.rpm
```
- **AppImage (`.AppImage`)**:
```bash
chmod +x YTSage-*.AppImage
./YTSage-*.AppImage
```
- **Flatpak**: Следуйте инструкциям на Flathub или выполните:
```bash
flatpak install flathub io.github.oop7.ytsage
```
#### 🍎 macOS
| Формат | Описание |
|--------|-------------|
|  | Приложение ZIP для Apple Silicon |
|  | Установщик DMG для Apple Silicon |
🛠️ Шаги по установке
- **DMG установщик (`.dmg`)**: Дважды щелкните, чтобы смонтировать, и перетащите `YTSage.app` в папку Applications (Программы).
- **Приложение в архиве (`.zip`)**: Распакуйте ZIP и переместите `YTSage.app` в папку Applications.
*Примечание: Если вы получили ошибку "App is damaged", см. раздел по macOS ниже.*
---
💻 Ручная установка из исходного кода
### 1. Клонировать репозиторий
```bash
git clone https://github.com/oop7/YTSage.git
cd YTSage
```
### 2. Установить зависимости
#### ⚡ С помощью uv
```bash
uv pip install .
```
#### 📦 Или через стандартный pip
```bash
pip install .
```
### 3. Запустить приложение
```bash
python -m ytsage.main
```
## 📸 Скриншоты
Настройки загрузки
Загрузка плейлиста
Аудиоформат
Пользовательские опции
## 📖 Использование
🎯 Базовое использование
1. **Запустите YTSage**
2. **Вставьте ссылку на YouTube** (или используйте кнопку "Paste URL")
3. **Нажмите "Analyze"**
4. **Выберите формат:**
- `Video` для загрузки видео
- `Audio Only` для извлечения аудио
5. **Выберите опции:**
- Включите субтитры и выберите язык
- Включите объединение субтитров (Merge)
- Сохранить обложку (Save Thumbnail)
- Удалить спонсорские вставки (SponsorBlock)
- Сохранить описание (Save Description)
- Внедрить главы (Embed Chapters)
6. **Выберите папку для сохранения**
7. **Нажмите "Download"**
> 💡 Папка загрузок по умолчанию — папка "Загрузки" текущего пользователя.
📋 Загрузка плейлиста
1. **Вставьте ссылку на плейлист**
2. **Нажмите "Analyze"**
3. **Выберите видео в селекторе (по умолчанию выбраны все)**
4. **Выберите нужный формат/качество**
5. **Нажмите "Download"**
> 💡 Приложение автоматически управляет очередью загрузки, и вы можете экспортировать записи плейлиста в файлы `.txt`, `.csv`, `.m3u` или `.json`.
🌍 Общий режим для сайтов помимо YouTube
Используйте Общий режим (Generic Mode), когда хотите, чтобы YTSage принимал ссылки с других сайтов, поддерживаемых yt-dlp, таких как Dailymotion, TikTok и другие.
Как использовать:
1. Откройте `Download Settings`.
2. Включите `Generic Mode`.
3. Вставьте ссылку на видео или плейлист с поддерживаемого сайта (не YouTube).
4. Нажмите `Analyze`.
5. Выберите формат и скачайте как обычно.
Примечания:
- Общий режим только отключает строгую проверку URL внутри YTSage. Сайт все равно должен поддерживаться установленной версией yt-dlp.
- Некоторым сайтам требуются cookies, вход, прокси или дополнительные аргументы yt-dlp.
- Если сайт перестал работать, обновите yt-dlp во встроенной вкладке обновления, прежде чем сообщать о проблеме.
🧰 Опции медиа и загрузки
- **Опции субтитров:** Фильтруйте языки и внедряйте субтитры в видеофайл.
- **Объединение субтитров:** "Вшивает" субтитры в видеофайл (hardcode).
- **Сохранить описание:** Сохраняет описание видео в текстовый файл.
- **Сохранить обложку:** Сохраняет превью видео как изображение.
- **Внедрить главы:** Добавляет маркеры глав в метаданные для совместимых медиаплееров.
- **Удалить спонсорские вставки:** Использует SponsorBlock для удаления рекламных сегментов из видео.
- **Обрезать видео:** Загружайте только части видео, указав временной интервал в формате `HH:MM:SS`.
⚙️ Настройки вывода и файлов
- **Ограничение скорости:** Ограничьте скорость загрузки, например, `500K` для 500 КБ/с.
- **Путь загрузки:** Сохраните путь по умолчанию для будущих загрузок. Доступно в **Download Settings → Download Path**.
- **Разрешение по умолчанию:** Установите предпочитаемое разрешение для автовыбора (например, 1080p, 720p). Доступно в **Download Settings → Default Video Resolution**.
- **Языки субтитров по умолчанию:** Установите языки по умолчанию для автовыбора (через запятую, например, `ru,en`). Доступно в **Download Settings → Default Subtitle Languages**.
- **Формат имени файла:** Настройте формат имени выходного файла, используя переменные типа `%(title)s`, `%(uploader)s` и др. Доступно в **Download Settings → Filename Format**.
- **Принудительный формат вывода:** Принудительно скачивайте видео в определенном контейнере, например `mp4`, `webm` или `mkv`. Доступно в **Download Settings → Output Format Settings**.
- **Конвертация аудио:** Конвертируйте аудио в форматы `AAC`, `MP3`, `FLAC`, `WAV`, `Opus`, `M4A`, `Vorbis`, или `Best`. Доступно в **Download Settings → Audio Format Settings**.
- **Нормализация звука:** Выравнивает громкость аудио загрузок согласно EBU R128.
- **Одновременные соединения:** Значительно увеличивает скорость за счет загрузки в несколько потоков. Доступно в **Download Settings → General → Concurrent Connections** (рекомендуется 8-10).
🌐 Доступ и сеть
- **Вход через Cookies:** Войдите в YouTube через куки для доступа к приватному контенту.
Как использовать:
1. **Рекомендуется:** Используйте встроенную опцию `Extract cookies from browser`, выберите браузер и профиль.
2. Или вручную:
a. Экспортируйте куки через расширение [cookie-editor](https://github.com/moustachauve/cookie-editor).
b. Скопируйте куки в формате Netscape.
c. Создайте файл `cookies.txt` и вставьте их туда.
d. Выберите этот файл в приложении.
- **Поддержка прокси:** Используйте прокси-сервер для загрузок, например: `http://:`
- **Общий режим:** Позволяет скачивать с сайтов помимо YouTube. Включите в **Download Settings → Generic Mode**.
🛠️ Инструменты и обслуживание
- **Пользовательские команды:** Доступ к продвинутым функциям yt-dlp через аргументы командной строки.
- **Вкладка обновления:** Управляйте инструментами в одном месте (Custom Options):
- **Обновление yt-dlp:** Проверка обновлений, переключение между Stable и Nightly ветками.
- **Версия FFmpeg:** Проверка версии и инструкции по установке.
- **Обновление Deno:** Проверка и обновление Deno.
- **Обнаружение FFmpeg/yt-dlp/Deno:** Автоматически находит пути и версии в окне "About".
- **История загрузок:** Просматривайте историю с обложками и статусом через кнопку **History**.
🌍 Локализация
YTSage поддерживает **14 языков**. Выберите нужный в **Custom Options → Language**.
### Поддерживаемые языки
| Язык | Код | Язык | Код |
|----------|------|----------|------|
| 🇺🇸 Английский | `en` | 🇪🇸 Испанский | `es` |
| 🇸🇦 Арабский | `ar` | 🇫🇷 Французский | `fr` |
| 🇩🇪 Немецкий | `de` | 🇮🇳 Хинди | `hi` |
| 🇮🇩 Индонезийский | `id` | 🇮🇹 Итальянский | `it` |
| 🇯🇵 Японский | `ja` | 🇵🇱 Польский | `pl` |
| 🇧🇷 Португальский | `pt` | 🇷🇺 Русский | `ru` |
| 🇹🇷 Турецкий | `tr` | 🇨🇳 Китайский | `zh` |
### Переводы README
| Язык | Файл | Язык | Файл |
|----------|------|----------|------|
| 🇺🇸 Английский | [README.md](../README.md) | 🇪🇸 Испанский | [README.es.md](README.es.md) |
| 🇸🇦 Арабский | [README.ar.md](README.ar.md) | 🇫🇷 Французский | [README.fr.md](README.fr.md) |
| 🇩🇪 Немецкий | [README.de.md](README.de.md) | 🇮🇳 Хинди | [README.hi.md](README.hi.md) |
| 🇮🇩 Индонезийский | [README.id.md](README.id.md) | 🇮🇹 Итальянский | [README.it.md](README.it.md) |
| 🇯🇵 Японский | [README.ja.md](README.ja.md) | 🇵🇱 Польский | [README.pl.md](README.pl.md) |
| 🇧🇷 Португальский | [README.pt.md](README.pt.md) | 🇷🇺 Русский | [README.ru.md](README.ru.md) |
| 🇹🇷 Турецкий | [README.tr.md](README.tr.md) | 🇨🇳 Китайский | [README.zh.md](README.zh.md) |
> 💡 **Хотите помочь с переводом?** Ознакомьтесь с разделом [Участие в проекте](#участие-в-проекте), чтобы помочь нам добавить новые языки!
## 🛠️ Решение проблем
Нажмите, чтобы увидеть частые вопросы
- **Не появляется таблица форматов:** Обновите yt-dlp до последней версии и попробуйте переключиться на канал Nightly.
- **Загрузка не удалась:** Проверьте интернет-соединение и доступность видео.
- **Специфические ошибки:**
- **Приватные видео:** Используйте вход через Cookies.
- **Ограничение по возрасту:** Войдите в аккаунт YouTube.
- **Геоблокировка:** Используйте VPN.
- **Видео удалено:** Видео больше недоступно на YouTube.
- **Прямые трансляции:** Стримы нельзя скачать, пока они идут; дождитесь завершения.
- **Сетевые ошибки:** Проверьте подключение к интернету и повторите попытку.
- **Неверный URL:** Убедитесь, что URL указан правильно и принадлежит поддерживаемой платформе.
- **Премиум-контент:** Требуется подписка YouTube Premium.
- **Блокировка авторских прав:** Контент заблокирован из-за ограничений авторского права.
- **Видео и аудио разделены после загрузки:** Это происходит, если FFmpeg отсутствует или не обнаружен. YTSage нужен FFmpeg для объединения потоков.
- **Решение:** Убедитесь, что FFmpeg установлен и добавлен в PATH. Пользователям Windows проще всего скачать версию с `-ffmpeg.exe`.
---
#### 🛡️ Предупреждение Windows Defender / Антивируса
Некоторые антивирусы могут помечать `.exe` файлы как ложные срабатывания. Это **известная особенность** упакованных приложений.
**Причины:**
- Эвристические алгоритмы антивирусов могут ошибочно идентифицировать упакованные исполняемые файлы как подозрительные.
**Безопасные варианты:**
- ✅ **Установка через pip:** `pip install ytsage` (рекомендуется)
- ✅ **Сборка из исходников**: Инструкция [здесь](../.github/CI_CD_README.md)
- ✅ **Добавить в исключения** антивируса.
#### 🍎 macOS: "App is damaged and cannot be opened"
Если вы видите эту ошибку на macOS Sonoma или новее:
1. **Откройте Терминал**.
2. **Введите команду** (с пробелом в конце):
```bash
xattr -d com.apple.quarantine
```
3. **Перетащите `YTSage.app`** из Finder в окно Терминала.
4. **Нажмите Enter**.
5. Попробуйте открыть программу снова.
---
#### **Пути конфигурации (Продвинутым)**
- **Windows:** `%LOCALAPPDATA%\YTSage`
- **macOS:** `~/Library/Application Support/YTSage`
- **Linux:** `~/.local/share/YTSage`
## 💖 Спонсорство
Если YTSage экономит ваше время, поддержите разработку проекта. Спонсорство помогает поддерживать тестирование на всех платформах и внедрять новые функции.
- GitHub Sponsors: https://github.com/sponsors/oop7
- Ссылка на спонсорство также есть в окне "About" в приложении.
[](https://github.com/sponsors/oop7)
## 👥 Участие в проекте
Мы рады любой помощи!
1. 🍴 Сделайте Fork репозитория
2. 🌿 Создайте ветку: `git checkout -b feature/NewFeature`
3. 💾 Сделайте коммит: `git commit -m 'Add NewFeature'`
4. 📤 Отправите изменения: `git push origin feature/NewFeature`
5. 🔄 Создайте Pull Request
### 🌍 Помощь с переводами
- Обновите файл README (например, `readme-translations/README.ru.md`)
- Обновите строки интерфейса в `ytsage/languages/.json`
- Если ваш язык отсутствует, начните с `README.md` и создайте `README..md`
📂 Структура проекта
## YTSage - Структура проекта
Этот документ описывает организованную структуру папок YTSage.
### 📁 Схема проекта
```
YTSage/
├── 📁 .github/ # Настройки GitHub
│ ├── 📁 ISSUE_TEMPLATE/ # Шаблоны проблем
│ │ └── 🐛-bug-report.md # Шаблон отчета об ошибке
│ ├─── 📁 workflows/ # Рабочие процессы GitHub Actions
│ │ ├── build-linux.yml # Сборка для Linux
│ │ ├── build-macos.yml # Сборка для macOS
│ │ │── build-windows.yml # Сборка для Windows
| | └── release-all.yml # Основной процесс выпуска
│ └── 📄 CI_CD_README.md # Документация CI/CD
├── 📁 branding/ # Брендинг (скриншоты, SVG)
│ ├── 📁 icons/ # Иконки приложения
│ ├── 📁 screenshots/ # Скриншоты для документации
│ └── 📁 svg/ # SVG ассеты
├── 📄 LICENSE # Файл лицензии
├── 📄 pyproject.toml # Метаданные проекта и зависимости
├── 📄 README.md # Документация проекта
├── 📄 requirements.txt # Зависимости Python (разработка)
└── 📁 ytsage/ # Исходный код
├── 📁 assets/ # Ресурсы времени выполнения
│ ├── 📁 Icon/ # Иконки приложения
│ └── 📁 sound/ # Звуковые файлы
├── 📁 languages/ # Файлы локализации
│ ├── 📄 ar.json # Перевод на арабский
│ ├── 📄 de.json # Перевод на немецкий
│ ├── 📄 en.json # Перевод на английский
│ └── ... # Другие языки
├── 📁 core/ # Основная бизнес-логика
│ ├── 📄 __init__.py
│ ├── 📄 ytsage_deno.py # Интеграция Deno
│ ├── 📄 ytsage_downloader.py # Функционал загрузки
│ ├── 📄 ytsage_ffmpeg.py # Интеграция FFmpeg
│ ├── 📄 ytsage_utils.py # Вспомогательные функции
│ └── 📄 ytsage_yt_dlp.py # Интеграция yt-dlp
├── 📁 gui/ # Компоненты интерфейса
│ ├── 📄 __init__.py
│ ├── 📄 ytsage_gui_main.py # Главное окно приложения
│ └── 📁 ytsage_gui_dialogs/ # Классы диалогов
├── 📁 utils/ # Утилиты
│ ├── 📄 __init__.py
│ ├── 📄 ytsage_config_manager.py # Управление конфигурацией
│ └── 📄 ytsage_logger.py # Логирование
├── 📄 __init__.py # Точка входа в пакет
└── 📄 main.py # Основной скрипт запуска
```
## ⭐️ История звезд
## Star History
## 📜 Лицензия
Проект распространяется под лицензией MIT — подробности в файле [LICENSE](../LICENSE).
## 🙏 Благодарности
Показать благодарности
Большое спасибо всем, кто внес свой вклад в этот проект, открывая проблемы с предложениями по улучшению или отчетами об ошибках.
## ⚠️ Отказ от ответственности
Этот инструмент предназначен только для личного использования. Пожалуйста, соблюдайте Условия использования YouTube и права создателей контента.
---
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](https://github.com/oop7/YTSage/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/oop7/YTSage/releases)
[](https://github.com/oop7/YTSage/stargazers)
[](https://pypi.org/project/ytsage/)
[](https://github.com/sponsors/oop7)
**Современный загрузчик с YouTube с чистым интерфейсом на PySide6.**
Загружайте видео в любом качестве, извлекайте аудио, получайте субтитры и многое другое.
### 🌍 Языки README
Английский: [EN](../README.md)
| Арабский: [AR](README.ar.md)
| Немецкий: [DE](README.de.md)
| Испанский: [ES](README.es.md)
| Французский: [FR](README.fr.md)
| Хинди: [HI](README.hi.md)
| Индонезийский: [ID](README.id.md)
| Итальянский: [IT](README.it.md)
| Японский: [JA](README.ja.md)
| Польский: [PL](README.pl.md)
| Португальский: [PT](README.pt.md)
| Русский: [RU](README.ru.md)
| Турецкий: [TR](README.tr.md)
| Китайский: [ZH](README.zh.md)
