YouTube Media для Home Assistant

Отдельный сервис, который запускает yt-dlp на машине с доступом к YouTube и отдаёт Home Assistant поиск, метаданные и аудио. Сетевой обход DPI остаётся в проекте zapret-lxc, а этот проект отвечает только за медиа: стриминг, кэш и API.

Архитектура

Home Assistant
   ↓ HTTP API :8099
YouTube Media (yt-dlp, стриминг/кэш, будущие плейлисты)
   ↓ socks5h://192.168.1.48:987
zapret-lxc (zapret + SOCKS5/HTTP proxy)
   ↓
YouTube

yt-dlp и ретранслятор используют один и тот же прокси, поэтому ссылка googlevideo и поток идут с одного IP — ошибки 403 из-за привязки к IP не возникают.

В отличие от HA-интеграции, здесь можно развивать кэш, стриминг, плейлисты, очередь и базу данных, не затрагивая ни Home Assistant, ни сетевой LXC.

Возможности

• Поиск YouTube (/search).
• Разрешение ссылки/запроса в метаданные (/resolve).
• Прямая ретрансляция потока через прокси: воспроизведение начинается сразу.
• Проксируемый поток параллельно сохраняется в кэш; после полного проигрывания повторный запуск идёт из файла.
• Режим download — полное скачивание в кэш (для офлайна и плейлистов).
• HTTP Range и HEAD для перемотки.
• Bearer-токен для доступа.
• Автоустановка и обновление в стиле community-scripts.

Требования

• Proxmox VE 8/9, запуск ct/youtube-media.sh от root;
• работающий прокси из проекта zapret-lxc (по умолчанию socks5h://192.168.1.48:987);
• доступ к Gitea и PyPI из контейнера;
• диск под кэш: по умолчанию 16 ГБ.

Установка

Из Gitea:

COMMUNITY_SCRIPTS_URL="http://192.168.1.111:3000/alex/youtube-media/raw/branch/main" \
  bash -c "$(curl -fsSL http://192.168.1.111:3000/alex/youtube-media/raw/branch/main/ct/youtube-media.sh)"

Из локальной копии:

bash /root/youtube-media/ct/youtube-media.sh

Другой прокси можно передать при создании:

YOUTUBE_MEDIA_PROXY="socks5h://192.168.1.48:987" \
  bash /root/youtube-media/ct/youtube-media.sh

Прокси записывается в /opt/youtube-media/bridge.env только при первой установке; позже его можно изменить там вручную.

Параметры контейнера

Переменная	По умолчанию	Описание
var_cpu	1	vCPU
var_ram	1024	RAM, МБ
var_disk	16	Диск, ГБ (кэш аудио)
var_os	debian	ОС
var_version	13	Версия Debian
var_unprivileged	1	Непривилегированный контейнер

Пример с большим кэшем:

var_disk=32 var_ram=2048 bash /root/youtube-media/ct/youtube-media.sh

После установки

API:   http://<IP>:8099
Health: http://<IP>:8099/health
Token: /opt/youtube-media/bridge.env

Сервис:

pct exec <CTID> -- systemctl status youtube-media --no-pager
pct exec <CTID> -- journalctl -u youtube-media -n 100 --no-pager
pct exec <CTID> -- systemctl restart youtube-media

Проверка:

curl http://<IP>:8099/health
curl -H "Authorization: Bearer <токен>" \
  "http://<IP>:8099/search?q=daft%20punk&limit=3"

Настройки

/opt/youtube-media/bridge.env:

Переменная	По умолчанию	Описание
BRIDGE_HOST	0.0.0.0	Адрес прослушивания.
BRIDGE_PORT	8099	Порт API.
BRIDGE_TOKEN	генерируется	Bearer-токен.
BRIDGE_STREAM_MODE	proxy	proxy — ретрансляция через прокси с фоновым кэшированием, download — сначала скачать в кэш.
BRIDGE_CACHE	/opt/youtube-media/cache	Каталог кэша.
BRIDGE_CACHE_TTL	604800	Время жизни кэша, секунды (7 дней).
YTDLP_FORMAT	bestaudio[ext=m4a]/bestaudio/best	Формат yt-dlp.
YTDLP_PROXY	socks5h://192.168.1.48:987	Прокси для yt-dlp и скачивания.
YTDLP_COOKIES	пусто	Путь к cookies.txt, если YouTube требует вход.

После изменения перезапустите сервис:

pct exec <CTID> -- systemctl restart youtube-media

API

• GET / — информация о сервисе.
• GET /health — статус, версия yt-dlp, наличие прокси.
• GET /search?q=...&limit=10 — результаты поиска, duration и признак cached (наличие файла в каталоге кэша); поле cache показывает, что сервис умеет отдавать статус кеша.
• GET /resolve?query=...&random=false — метаданные и stream_url.
• GET /stream/<video_id> — поток с поддержкой HTTP Range.

В режиме proxy (по умолчанию) /stream сразу ретранслирует подписанный googlevideo URL через YTDLP_PROXY; ожидания полной загрузки нет. Пока идёт полный ответ, байты параллельно пишутся в BRIDGE_CACHE; после завершения файл становится доступен как кеш. В режиме download /resolve запускает фоновую загрузку в кэш, а /stream ждёт файл.

Home Assistant

В интеграции youtube-ha укажите:

• URL моста — http://<IP>:8099;
• Токен моста — BRIDGE_TOKEN из /opt/youtube-media/bridge.env.

Поле прокси в интеграции при использовании этого сервиса игнорируется.

Обновление

Внутри контейнера:

update

update_script обновит server.py, зависимости (yt-dlp, aiohttp) и systemd-юнит, сохранив bridge.env и кэш.

Кэш

Кэш заполняется в обоих режимах: в download — до начала воспроизведения, в proxy — по мере проигрывания полного потока. /search возвращает для каждого ролика cached: true|false по фактическому наличию файла в каталоге кэша, чтобы клиент мог показать статус ещё до воспроизведения.

• Каталог: /opt/youtube-media/cache.
• TTL по умолчанию 7 дней; очистка при старте и перед новой загрузкой.
• Для кэша нужен отдельный диск; не используйте для этого контейнер zapret-lxc.

Безопасность

Сервис не предназначен для публикации в интернет. Держите его в локальной сети, ограничьте порт 8099 firewall'ом и задайте BRIDGE_TOKEN.

Структура

ct/youtube-media.sh                 # создание LXC, update
install/youtube-media-install.sh    # базовые пакеты внутри контейнера
server/server.py                    # HTTP API и yt-dlp
server/requirements.txt             # aiohttp, aiohttp-socks, PySocks, yt-dlp
server/setup.sh                     # venv, зависимости, env, systemd
server/youtube-media.service        # systemd-юнит