YouTube для Home Assistant

Кастомная интеграция, которая позволяет искать и слушать музыку с YouTube на любом медиаплеере Home Assistant. Есть два режима: локальный yt-dlp через SOCKS5-прокси (по умолчанию socks5h://192.168.1.48:987) и режим моста, когда yt-dlp работает на отдельном LXC с рабочим доступом к YouTube.

Как это работает

Локальный режим:

1. Сервис youtube_ha.play ищет видео (или принимает ссылку) через yt-dlp.
2. yt-dlp получает прямой адрес аудиодорожки через прокси.
3. Home Assistant сам скачивает поток через прокси и отдаёт его плееру по локальному адресу http://<HA>/api/youtube_ha/stream/<token>/audio.m4a.
4. Медиаплееру не нужен доступ к YouTube и не нужен прокси — достаточно доступа к Home Assistant.

Режим моста:

1. Home Assistant отправляет поиск и запрос метаданных на HTTP-мост в LXC.
2. Мост запускает yt-dlp, получает ссылку и ретранслирует поток через тот же прокси, которым пользовался при resolve.
3. Home Assistant забирает поток с моста и отдаёт его плееру по своему локальному адресу с токеном.
4. Медиаплееру по-прежнему нужен только Home Assistant.

Ссылки на поток живут 5 часов, защищены случайным токеном и поддерживают HTTP Range (перемотку).

Возможности

• Поиск и воспроизведение по названию или ссылке на видео.
• Случайный трек из результатов поиска.
• Очередь: play, add, next, replace (поддерживается плеером).
• Работа через SOCKS5, SOCKS4 и HTTP-прокси; прокси не обязателен.
• Режим моста: yt-dlp на отдельном LXC, если там есть доступ к YouTube.
• Поддержка файла cookies для случаев, когда YouTube требует подтверждения входа.
• Медиабраузер: последние поисковые запросы доступны в разделе Медиа → YouTube.
• Lovelace-карточка youtube-ha-search-card: прямоугольные превью 16:9, длительность, статус кеша моста, закреплённый плеер и компактный список для узких колонок.
• Ошибки YouTube возвращаются в лог и в ответ сервиса.

Установка

HACS

1. HACS → Интеграции → меню → Пользовательские репозитории.
2. Добавьте репозиторий с этим проектом, категория Integration.
3. Установите интеграцию и перезапустите Home Assistant.

HACS умеет работать только с репозиториями на github.com. Ссылку на self-hosted Gitea/Forgejo добавить нельзя — используйте установку через git ниже.

Из Gitea через git

HACS не поддерживает Gitea, поэтому интеграцию нужно забрать из репозитория http://192.168.1.111:3000/alex/youtube-ha вручную.

Команды выполняются на хосте Home Assistant (в HA OS — через дополнение Advanced SSH & Web Terminal или Terminal & SSH):

cd /config
git clone http://192.168.1.111:3000/alex/youtube-ha /config/youtube-ha-src
mkdir -p /config/custom_components
rm -rf /config/custom_components/youtube_ha
cp -r /config/youtube-ha-src/custom_components/youtube_ha /config/custom_components/

Если репозиторий в Gitea приватный, используйте токен доступа (Gitea → Настройки → Приложения → Создать токен):

git clone http://alex:<ТОКЕН>@192.168.1.111:3000/alex/youtube-ha /config/youtube-ha-src

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

ha core restart

или через интерфейс: Настройки → Система → Перезагрузить.

Обновление из Gitea:

cd /config/youtube-ha-src
git pull
rm -rf /config/custom_components/youtube_ha
cp -r custom_components/youtube_ha /config/custom_components/
ha core restart

Вместо копирования можно один раз создать симлинк — тогда для обновления достаточно git pull и перезапуска:

ln -s /config/youtube-ha-src/custom_components/youtube_ha /config/custom_components/youtube_ha

Симлинки поддерживаются не всеми способами резервного копирования и дополнениями HA. Если сомневаетесь, используйте копирование.

Вручную

Скопируйте каталог custom_components/youtube_ha в <config>/custom_components/youtube_ha и перезапустите Home Assistant. Зависимости (yt-dlp, aiohttp-socks, PySocks) установятся автоматически при первом запуске.

В каталоге brand/ лежат icon.png и icon@2x.png: Home Assistant 2026.3+ показывает эту иконку в списке медиаисточников и в карточке интеграции. После обновления иконок может понадобиться жёсткое обновление страницы (Ctrl+F5).

Требуется Home Assistant 2024.12 или новее.

Настройка

Настройки → Устройства и службы → Добавить интеграцию → YouTube.

Параметр	Описание
URL моста YouTube	Необязательно. Адрес yt-dlp-моста на LXC, например http://<IP медиа-LXC>:8099. Если задан, интеграция использует мост, а прокси/локальный yt-dlp игнорируются.
Токен моста	Необязательный общий секрет, если на мосте задан BRIDGE_TOKEN.
Прокси	socks5h://192.168.1.48:987 по умолчанию. Используется только без моста. Можно указать host:port — схема socks5h:// добавится автоматически.
Базовый URL Home Assistant	Адрес, по которому плееры видят Home Assistant, например http://192.168.1.10:8123. Если пусто, используется internal_url из настроек сети.
Количество результатов поиска	Сколько результатов запрашивать и использовать для случайного выбора.
Формат аудио yt-dlp	По умолчанию bestaudio[ext=m4a]/bestaudio/best — M4A/AAC понимают почти все плееры.
Файл cookies	Необязательно. Путь к cookies.txt в формате Netscape. Относительный путь считается от каталога конфигурации.
Скачивать поток напрямую	Разрешать и скачивать аудио без прокси, если прокси пропускает youtube.com, но блокирует googlevideo.com. Поиск остаётся через прокси, а resolve и загрузка аудио идут напрямую одним маршрутом.
URL репозитория обновлений	Gitea-репозиторий для сущности обновления, по умолчанию http://192.168.1.111:3000/alex/youtube-ha. Пустое значение отключает обновление из интерфейса.
Токен репозитория обновлений	Необязательно. Gitea-токен, если репозиторий приватный.

Параметры можно изменить позже: Настройки → Устройства и службы → YouTube → Настроить.

Важно: base_url (или internal_url) должен быть доступен с медиаплеера. Для Chromecast, Sonos и колонок обычно нужен IP-адрес Home Assistant в локальной сети, а не localhost.

Режим моста на LXC

Если на LXC уже есть рабочая сеть до YouTube, надёжнее запустить yt-dlp там, а не гонять медиа-CDN через прокси из Home Assistant. Мост входит в проект youtube-media и ставится вместе с контейнером: он ищет видео, получает метаданные и ретранслирует аудиопоток через yt-dlp и прокси. Ссылка на googlevideo.com запрашивается с того же IP, что её получил, поэтому 403 исчезают; воспроизведение начинается сразу.

Схема:

HA → /search, /resolve, /stream → LXC:8099 (yt-dlp + zapret)
HA → /api/youtube_ha/stream/... → браузер/плеер

Мост поднимается на http://<IP LXC>:8099 как сервис youtube-media. Токен генерируется при установке LXC и хранится в /opt/youtube-media/bridge.env.

Затем в настройках интеграции укажите URL моста (например, http://<IP медиа-LXC>:8099) и токен из bridge.env. Поле прокси можно оставить как есть — в режиме моста оно не используется.

Мост использует SOCKS5-прокси из zapret-lxc (socks5h://192.168.1.48:987), поэтому yt-dlp и скачивание идут через zapret. Если понадобится другой маршрут, измените YTDLP_PROXY в /opt/youtube-media/bridge.env и перезапустите youtube-media.

Сервисы

youtube_ha.play

Ищет или загружает трек и включает его на выбранных плеерах.

service: youtube_ha.play
target:
  entity_id: media_player.kitchen
data:
  query: "Daft Punk — Instant Crush"
  enqueue: play
  random: false

Поле	Обязательное	Описание
query	да	Поисковый запрос или ссылка на YouTube.
enqueue	нет	play (по умолчанию), add, next, replace.
random	нет	Выбрать случайный результат из выдачи.

Сервис возвращает title, video_id, url и duration, если вызван с return_response.

youtube_ha.search

Возвращает результаты поиска без воспроизведения.

service: youtube_ha.search
data:
  query: "lofi hip hop"
  limit: 5
response_variable: yt

Результат:

results:
  - title: "lofi hip hop radio"
    url: "https://www.youtube.com/watch?v=..."
    video_id: "..."
    duration: 3600
    uploader: "..."
    thumbnail: "https://..."

Пример использования в шаблоне:

service: youtube_ha.play
target:
  entity_id: media_player.kitchen
data:
  query: "{{ yt.results[3].url }}"

Примеры автоматизаций

Воспроизведение случайного трека по кнопке:

automation:
  - alias: "Случайная музыка с YouTube"
    triggers:
      - trigger: state
        entity_id: input_button.youtube_random
    actions:
      - service: youtube_ha.play
        target:
          entity_id: media_player.kitchen
        data:
          query: "best of daft punk"
          random: true

Утреннее включение плейлиста:

automation:
  - alias: "Музыка на завтрак"
    triggers:
      - trigger: time
        at: "07:30:00"
    actions:
      - service: youtube_ha.play
        target:
          entity_id: media_player.kitchen
        data:
          query: "morning acoustic playlist"

Медиабраузер

Откройте Медиа → YouTube. На главной странице источника есть быстрые подборки («Хиты», «Lo-Fi», «Рок», «Джаз») и последние поисковые запросы. В версиях Home Assistant, где медиаисточники поддерживают поиск, сверху появляется поле поиска: введите запрос и нажмите «Найти» — интеграция выполнит поиск через yt-dlp и покажет треки, которые можно сразу отправить на плеер.

Если поле поиска не отображается, значит ваша версия Home Assistant ещё не поддерживает поиск в медиаисточниках — обновите HA или используйте сервис youtube_ha.play / youtube_ha.search. Быстрые подборки и недавние запросы работают на любой поддерживаемой версии.

Карточка поиска YouTube

Встроенный медиабраузер Home Assistant рисует квадратные превью и не умеет показывать длительность или статус кеша. Для YouTube-подобного вида в интеграцию входит Lovelace-карточка custom:youtube-ha-search-card.

Ресурс подключается автоматически при запуске интеграции, вручную добавлять его в Ресурсы не нужно. После обновления файлов интеграции перезапустите Home Assistant и обновите страницу через Ctrl+F5.

type: custom:youtube-ha-search-card
entity_id: media_player.kitchen
title: YouTube
query: Rammstein
limit: 12

Для воспроизведения прямо в браузере уберите entity_id:

type: custom:youtube-ha-search-card
title: YouTube
limit: 12

Параметр	Описание
entity_id	Необязательно. Медиаплеер (или список), на который отправляется трек. Если не задан, карточка играет звук прямо в браузере через встроенный <audio>.
title	Заголовок карточки. По умолчанию YouTube.
query	Начальный поисковый запрос; карточка выполнит его при загрузке.
limit	Сколько результатов запрашивать, 1..25. По умолчанию 12.
page_size	Сколько результатов показывать сразу; остальные открываются кнопкой «Показать ещё». По умолчанию min(limit, 6).
layout	auto (по умолчанию), grid или list. В auto узкая карточка (уже ~520px) переключается на компактный список с маленькими превью.
max_height	Максимальная высота прокручиваемой области результатов: число (px) или CSS-длина. По умолчанию 58vh.
autofocus	Ставить курсор в поле поиска при загрузке на устройствах с мышью. По умолчанию true; false отключает.

Если entity_id не указан, нажатие на ролик запускает воспроизведение в текущей вкладке браузера. Это работает без отдельной media_player-сущности; звук идёт через /api/youtube_ha/stream/... на том же origin. Для телевизоров/плееров, которые не умеют играть URL (например, lg_netcast), оставьте entity_id пустым или выберите Chromecast/VLC/Browser Mod.

Карточка показывает прямоугольные превью 16:9 и длительность в правом нижнем углу. В пустом состоянии показываются чипы последних запросов, а во время поиска — скелетоны вместо резкого появления списка. Плеер и статус закреплены сверху, а список результатов прокручивается внутри карточки, поэтому при поиске она больше не растягивается на весь экран. Пока играет трек, над результатами видна панель «Сейчас играет» с названием, исполнителем и кнопкой «Стоп»; она также отслеживает состояние media_player, если задан entity_id. Бейдж «В кеше» показывается зелёным, а отсутствие кеша — малозаметной иконкой, которая подсвечивается при наведении. Бейдж отражает фактическое наличие файла в кеше моста. В режиме proxy файл попадает в кеш после первого полного проигрывания, в download — до начала воспроизведения; в локальном режиме файлового кеша нет, поэтому бейдж показывает «Без кеша». Нажатие на ролик вызывает youtube_ha.play для указанного плеера. Для статуса кеша обновите и перезапустите youtube-media: старые версии моста не возвращают поле cached, и карточка покажет «Без кеша».

Обновление из интерфейса

Интеграция создаёт сущность update.youtube_update, если задан update_url (по умолчанию — этот Gitea-репозиторий). Она проверяет последний коммит ветки main и позволяет скачать и установить обновление без SSH.

1. Откройте Настройки → Система → Обновления или Настройки → Устройства и службы → YouTube.
2. У сущности YouTube update нажмите Установить.
3. Дождитесь уведомления и перезапустите Home Assistant.
4. После перезапуска обновите страницу через Ctrl+F5.

Обновление заменяет только custom_components/youtube_ha; youtube-media на LXC обновляется отдельно. Для приватного Gitea укажите токен в настройках интеграции. Скачивается архив закреплённого коммита, поэтому обновление можно повторить и оно не зависит от локального git.

Ограничения

• Прямые трансляции YouTube не поддерживаются: для них yt-dlp возвращает HLS- манифест, сегменты которого плеер должен скачивать сам, а значит, они снова упрутся в блокировку. Используйте обычные видео и завершённые трансляции.
• Очередь и перемотка зависят от возможностей вашего медиаплеера.
• Ссылки на поток живут 5 часов. После этого повторите вызов сервиса.
• В режиме моста по умолчанию поток идёт сразу; режим полного скачивания в кэш включается на стороне youtube-media через BRIDGE_STREAM_MODE=download.
• Поиск прямо в медиабраузере доступен только в тех версиях Home Assistant, где медиаисточники поддерживают async_search_media; на старых версиях остаются последние поиски и сервисы.
• Список последних поисков хранится в памяти и очищается при перезапуске HA.

Решение проблем

HTTP 403 / HTTP 410 при воспроизведении. Ссылка на аудио подписана под IP, с которого выполнялся resolve. Интеграция использует один маршрут для resolve и загрузки (при включённой опции Скачивать поток напрямую — оба идут напрямую), но 403 всё равно возможен, если прокси меняет exit IP между запросами или YouTube требует подтверждения входа. Проверьте стабильность прокси, обновите yt-dlp и укажите файл cookies.

Если победить 403 не получается, используйте режим моста на LXC (см. выше): там и resolve, и поток идут через один прокси с одного IP.

HTTP 410 при воспроизведении. Ссылки YouTube живут ограниченное время. Обновите интеграцию или yt-dlp и перезапустите Home Assistant.

Прокси отдаёт youtube.com, но не googlevideo.com (TLS reset / таймаут). Некоторые прокси и VPN разрешают сайт YouTube, но блокируют медиа-CDN. Включите опцию Скачивать поток напрямую — поиск и метаданные останутся через прокси, а аудио Home Assistant будет загружать напрямую.

Sign in to confirm you're not a bot. Укажите файл cookies в настройках интеграции. Экспортируйте cookies из браузера в формате Netscape и положите, например, в /config/youtube_cookies.txt.

Плеер ничего не воспроизводит. Проверьте, что base_url/internal_url доступен с плеера. Попробуйте формат bestaudio[ext=m4a]/bestaudio — некоторые плееры не поддерживают WebM/Opus.

Home Assistant internal URL is not configured. Задайте base_url в настройках интеграции или настройте внутренний URL в Настройки → Система → Сеть.

Your browser's media player does not support this type of media. Медиабраузер Home Assistant проигрывает поток через браузерный <audio>, а интеграция отдаёт для него относительный URL — тот же origin и протокол, что у самого Home Assistant, поэтому base_url и смешивание HTTP/HTTPS здесь не мешают. Если ошибка осталась, проверьте, что браузер поддерживает AAC/M4A (Chrome и Edge поддерживают; в Firefox на Linux может понадобиться системный кодек AAC), и откройте URL из ответа youtube_ha.play в новой вкладке.

Прокси недоступен. Интеграция проверяет TCP-подключение к прокси при сохранении настроек. Убедитесь, что Home Assistant может достучаться до 192.168.1.48:987.

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

Эндпоинт потока /api/youtube_ha/stream/... не требует авторизации, потому что медиаплееры не умеют передавать токен Home Assistant. Доступ защищён случайным токеном (32 байта) и ограничен по времени. Не публикуйте Home Assistant в интернет без дополнительной защиты; по возможности ограничьте доступ к /api/youtube_ha/ на уровне обратного прокси или firewall.

Структура

custom_components/youtube_ha/
  __init__.py       # настройка, сервисы, runtime
  brand/            # иконки интеграции для Home Assistant
  bridge.py         # клиент HTTP-моста (youtube-media)
  config_flow.py    # мастер настройки и параметры
  const.py          # константы
  media_source.py   # медиабраузер: поиск, подборки, последние запросы
  stream.py         # локальный HTTP-ретранслятор через прокси
  util.py           # разбор и проверка прокси
  update.py         # сущность обновления из Gitea
  websocket.py      # WebSocket API для Lovelace-карточки
  www/              # Lovelace-карточка youtube-ha-search-card
  yt.py             # обёртка над yt-dlp
  services.yaml
  strings.json
  translations/

Серверная часть моста (bridge.py, systemd-юнит и установка) находится в проекте youtube-media.