YouTubeDL/INSTALL.md

# Установка YouTubeDL

Нужны **Windows 10/11 x64** и **Microsoft Edge или Google Chrome 120+**.
Firefox, macOS, Linux и Windows ARM не входят в эту сборку.

Скачивания доступны в [релизах проекта](https://git.lonarpgproxy.space/OwnerLink/YouTubeDL/releases/latest).
Помощник распространяется **отдельно**: внутри архива расширения EXE нет.

1. Скачайте **YouTubeDL-1.4.5.zip** и распакуйте его в постоянную папку. Не удаляйте и не перемещайте её после установки.
2. Откройте `edge://extensions` или `chrome://extensions`. Включите **Режим разработчика**, нажмите **Загрузить распакованное расширение** и выберите папку **extension** внутри распакованного архива.
3. На странице релиза отдельно скачайте **YouTubeDL-Helper-Setup.exe**. Это автономный комплект: Python, yt-dlp, EJS, Node.js, FFmpeg и FFprobe уже внутри.
4. Запустите EXE вручную и дождитесь окончания установки. Администратор и интернет для установки комплекта не требуются. Программы устанавливаются для текущего пользователя в `%LOCALAPPDATA%\YouTubeDL\Helper`.
5. Обновите вкладку YouTube, откройте **⚙** рядом с кнопкой скачивания или значок расширения. Мастер первого запуска проверит помощник и предложит выбрать папку, качество и формат.
6. Если меню было открыто во время установки, нажмите **Проверить подключение** в мастере или **Запустить** в обычном меню. Зелёный статус означает реальный ответ помощника. Перезагрузка страницы для переподключения не нужна.

Загрузчик использует сохранённые параметры. Кнопка **Скачать** запускает загрузку, а **⚙** открывает настройки.
На превью и в Shorts доступны эти же действия в виде значков.

## Проверка скачанных файлов

Скачивайте файлы из релизов `git.lonarpgproxy.space/OwnerLink/YouTubeDL`.
Чтобы проверить целостность файла, сравните его SHA256 с `SHA256SUMS.txt` в том же релизе.

```powershell
Get-FileHash -Algorithm SHA256 -LiteralPath '.\YouTubeDL-Helper-Setup.exe'
```

## Обновления

- **Расширение:** скачайте новый ZIP из Releases, распакуйте поверх прежней папки, нажмите кнопку перезагрузки на странице расширений и обновите вкладки YouTube. Автоматической установки ZIP нет.
- **Сам помощник:** скачайте новый EXE из Releases и запустите его вручную. Кнопки установки и восстановления открывают страницу Releases.
- **Обновление компонентов** проверяет официальные источники и обновляет Python в ветке 3.13, Node.js в ветке 24 LTS, yt-dlp с зависимостями, EJS и FFmpeg с FFprobe. Запустить его вручную можно кнопкой «Обновить компоненты». По умолчанию такая проверка выполняется раз в сутки, пока помощник работает, между операциями. Её можно выключить в меню. Нужен интернет.

## Удаление

Нажмите **Удалить** в меню помощника или удалите YouTubeDL Helper в установленных приложениях Windows,
затем удалите расширение на странице управления браузера.
Скачанные ролики и локальная история помощника сохраняются.
Чтобы удалить и историю после удаления помощника, удалите `%LOCALAPPDATA%\YouTubeDL\Helper\data`.
Настройки расширения удаляются вместе с расширением. Подробнее — [PRIVACY.md](PRIVACY.md).

## Если что-то не работает

| Симптом | Что проверить |
| --- | --- |
| Помощник не установлен | Скачан и запущен именно `YouTubeDL-Helper-Setup.exe`, а не только ZIP. Установка выполнена в том же пользователе Windows, где открыт браузер. |
| Помощник не отвечает | Нажмите «Запустить». При повреждении комплекта скачайте EXE из Releases и переустановите. Не удаляйте `key` из manifest.json: ID расширения должен быть `ndnoeiaecgmjnjneekaeapeecmmjheli`. |
| Нет кнопок на YouTube | Перезагрузите расширение, затем обновите вкладку. YouTube меняет разметку; приложите к issue адрес страницы, версии браузера и расширения. |
| YouTube просит подтвердить вход | Откройте ролик в текущем профиле, пройдите проверку сайта. При необходимости включите «Использовать вход в YouTube» в меню и разрешите необязательный доступ к cookies. Это не гарантирует доступ к любому ролику. |
| GPU недоступен | Проверьте драйвер, список проверенных кодеков и режим «Авто». В режиме «Авто» возможен переход на CPU. Принудительный GPU-режим сообщает об ошибке. |
| Скачивание медленное | GPU ускоряет перекодирование видео; скорость сети и ограничения YouTube от видеокарты не зависят. |

Не прикладывайте cookies, токены, личные ссылки и полные пути с именем пользователя к публичным обращениям.
Сообщить об ошибке: [Задачи проекта](https://git.lonarpgproxy.space/OwnerLink/YouTubeDL/issues).

## Диски и временные файлы

В меню ⚙ поле «Сохранить в» задаёт папку готового файла. Поле «Рабочая папка для загрузки и обработки» задаёт место для скачанных дорожек и временных файлов FFmpeg. Оба поля допускают выбор папки на любом доступном диске. Если рабочая папка пуста, используется папка сохранения. Настройки действуют для следующих загрузок.

При разных дисках результат сначала копируется во временную папку на диске сохранения, затем публикуется под итоговым именем. Прогресс копирования виден в уведомлении; частичный файл не появляется под готовым именем. При отмене помощник завершает группу процессов данной задачи и удаляет её временные папки.

Для отдельной рабочей папки, подробного прогресса слияния и исправленной отмены установите помощник 1.3.2 и расширение 1.4.5. Обновление компонентов не заменяет программный код помощника; для этой версии запустите новый установщик помощника.

## История и ошибки

Кнопка **«История загрузок и ошибок»** под настройками открывает отдельную вкладку. Раздел **«Загрузки»** показывает завершённые и отменённые скачивания, дату, имя, размер и путь файла; **«Показать файл»** открывает его в проводнике через помощник. Раздел **«Ошибки»** содержит сообщения о сбоях скачивания, получения качества, установки и обновления компонентов.

История хранится локально в браузере: до 30 последних операций. Просмотр работает и без помощника, новые результаты появляются без перезагрузки страницы. Текущие операции и прогресс остаются в настройках и уведомлениях.

## Совместимость версий

В настройках и мастере первого запуска отображаются версии расширения и помощника. Расширение 1.4.5 поддерживает помощник 1.3.2. При старом помощнике появится кнопка «Обновить помощник», при более новом помощнике или устаревшем расширении — «Обновить расширение». Пока совместимость не подтверждена, новая загрузка не запускается.

После установки помощника нажмите «Проверить»: статус изменится без перезагрузки страницы. После замены файлов расширения нажмите «Обновить» на странице расширений браузера и перезагрузите вкладку YouTube. Обновление компонентов обновляет инструменты внутри комплекта и не заменяет само расширение или код помощника.

## Когда работает видеокарта

Видеокарта используется при перекодировании видео. В режиме «Авто» совместимое видео сохраняется без перекодирования: уведомление показывает «Подготовка файла · без перекодирования». Слияние дорожек и финализация файла также не требуют видеокодировщика.

Для проверки выберите поддерживаемый кодек, например H.264 или HEVC, и «NVIDIA NVENC» в поле ускорения. При обработке появится «Перекодирование · NVIDIA NVENC». В диспетчере задач откройте «Производительность» → GPU и выберите график Video Encode / «Кодирование видео». Если обрабатывается только звук, уведомление покажет «Обработка аудио · CPU».