Документация YouTube Player

Это приложение было написано для себя и поначалу представляло маленький скрипт из трёх сотен строк, поэтому его публикация не предполагалась. Сейчас же проделано много труда для того, чтобы оно стало более удобным и функциональным, и я хочу надёжно его сохранить.

Что это

Программа для воспроизведения YouTube видео по очереди на стриме, standalone-альтернатива таким сервисам, как Trula Music. Позволяет зрителям добавлять музыкальные клипы в очередь, есть поддержка донатов через Donatty, можно загрузить плейлист. Встроенный веб-интерфейс для управления и оверлей для вставки в OBS.

Важно: Программа работает только с музыкальными видео YouTube. Другие категории воспроизводиться не будут.

Быстрый старт

Минимальная настройка

Для запуска программы обязательно нужны только два параметра:

port - порт для веб-интерфейса
youtube_api_key - ключ YouTube API

Если какие-то параметры вам не нужны, можно просто удалить эти строки.

Минимальный config.json:

{
  "port": 8093,
  "youtube_api_key": "ВАШ_КЛЮЧ_YOUTUBE_API"
}

С такой конфигурацией программа запустится, но:

Не будет ограничений на длину видео и количество просмотров
Музыка за донаты работать не будет
Плейлист по умолчанию не загрузится
Очередь может быть сколь угодно большой

Полная настройка

Пример со всеми возможными параметрами:

{
  "port": 8093,
  "max_duration_minutes": 9,
  "min_views": 1000,
  "repeat_limit": 3,
  "cleanup_after_hours": 48,
  "max_queue_size": 100,
  "donation_widget_url": "https://widgets.donatty.com/donations/?ref=ВАШ_REF&token=ВАШ_TOKEN",
  "donation_min_amount": 50,
  "youtube_api_key": "ВАШ_КЛЮЧ_YOUTUBE_API",
  "fallback_playlist_url": "https://www.youtube.com/playlist?list=ID_ПЛЕЙЛИСТА"
}

Описание параметров config.json

Обязательные параметры

port (число) - порт для веб-интерфейса. По умолчанию 8093, можете указать любой свободный.
youtube_api_key (строка) - ключ для YouTube Data API v3, инструкция по получению: документация Google. Используется для определения длительности, количества просмотров и т.д.

Необязательные параметры

Ограничения на треки

max_duration_minutes (число) - максимальная длина видео в минутах. 0 = без ограничений.
min_views (число) - минимальное количество просмотров у видео. 0 = без ограничений.
repeat_limit (число) - сколько раз подряд можно воспроизвести одно и то же видео. 0 = без ограничений.

Управление очередью

cleanup_after_hours (число) - через сколько часов удалять старые треки. 0 = не удалять.
max_queue_size (число) - максимальное количество треков в очереди. По умолчанию: 100.

Донаты (Donatty)

donation_widget_url (строка) - ссылка на виджет уведомлений Donatty. Формат: https://widgets.donatty.com/donations/?ref=ВАШ_REF&token=ВАШ_TOKEN
donation_min_amount (число) - минимальная сумма доната в рублях для добавления трека. По умолчанию: 50.

Плейлист

fallback_playlist_url (строка) - ссылка на плейлист YouTube, который будет играть, когда очередь пуста.

Настройка донатов Donatty

Программа поддерживает платформу Donatty для автоматического добавления треков за донаты.

Как настроить

Зайти в личный кабинет Donatty
Открыть раздел с виджетами
Найти виджет оповещений "Новый донат"
Скопировать ссылку на этот виджет
Вставить в donation_widget_url в config.json

Важно: Нужна именно ссылка на виджет оповещений, а не самостоятельно созданный виджет! Эта ссылка никогда не меняется, можно использовать постоянно.

Пример ссылки:

https://widgets.donatty.com/donations/?ref=409b60e8-8880-4e36-b6fd-0e8XXXXX9c69&token=8uOUSDcXXXXXXXXXXXXXXXlWWnh4yz

Как работает

Зритель отправляет донат (не меньше donation_min_amount)
В сообщении доната указывает ссылку на YouTube или ID видео
Программа автоматически находит видео и добавляет в очередь
Треки от донатов имеют приоритет — играют первыми

Запуск программы

Обычный запуск

Создать файл config.json с настройками (можно скачать из репозитория config.sample.json, убрать .sample из названия и отредактировать)
Положить в каталог с программой
Запустить:
- Windows: двойной клик на yt-player.exe
- Консоль: ./yt-player.exe
Открыть браузер на http://localhost:8093

Установка как сервис

Чтобы программа запускалась автоматически при старте системы и работала в фоне.

Windows (через Servy)

Скачать Servy
После установки сконфигурируйте сервис, заполнив минимально необходимые поля:
- Название сервиса
- Путь к файлу yt-player.exe
- Путь к каталогу (иначе приложение не сможет читать файл конфигурации, который должен лежать в том же каталоге)
- Поочерёдно нажмите Install, Start

Windows (NSSM)

Скачать NSSM
Распаковать nssm.exe
Открыть командную строку от администратора в каталоге с nssm.exe

Установить сервис:

nssm.exe install YouTubePlayer "C:\путь\к\yt-player.exe"

Настроить рабочую директорию:

nssm.exe set YouTubePlayer AppDirectory "C:\путь\к\папке"

Запустить сервис:
```
nssm.exe start YouTubePlayer
```

Управление:

Остановить: nssm.exe stop YouTubePlayer
Перезапустить: nssm.exe restart YouTubePlayer
Удалить: nssm.exe remove YouTubePlayer confirm

Linux (systemd)

Для удобства установки я написал скрипт systemd_service_creator.sh. Справка вызывается с аргументом -h.

Краткий пример:

./systemd_service_creator.sh ./yt-player --name yt-player --config /path/to/config.json

Скрипт скопирует приложение и файл конфигурации в /opt/yt-player, создаст файл юнита и запустит сервис.

Управление:

Проверить статус: sudo systemctl status yt-player.service
Остановить: sudo systemctl stop yt-player.service
Перезапустить: sudo systemctl restart yt-player.service
Посмотреть логи: sudo journalctl -u yt-player.service -f

Веб-интерфейс

Главная панель — http://localhost:8093

Основной интерфейс для управления. Левая колонка содержит поле добавления треков и настройки плейлиста, центр — текущий трек, кнопки управления и очередь. Если fallback-плейлист загружен, справа выезжает панель с его треками.

Оверлей для OBS — http://localhost:8093/overlay

Прозрачная страница с видеоплеером для вставки в OBS.

Как добавить в OBS:

Создать новый источник → Browser
URL: http://localhost:8093/overlay
Размер: ширина 400, высота 225 (можно больше, сохраняя пропорции 16:9)
Включить "Shutdown source when not visible"
Включить "Refresh browser when scene becomes active"

Важно: оверлей прозрачен когда ничего не играет — это ожидаемое поведение.

Dok-панель для OBS — http://localhost:8093/dock

Компактная панель управления для встраивания в OBS как Custom Browser Dock.

Как добавить в OBS:

View → Docks → Custom Browser Docks
Dock Name: YouTube Player
URL: http://localhost:8093/dock
Нажать "Apply"

Что показывает:

Текущий трек и следующий (если есть)
Кнопки управления: предыдущий, играть/пауза, следующий

Управление через интерфейс

Добавление трека

Вставить ссылку YouTube или ID видео (11 символов) в поле "Add track"
Указать имя (опционально)
Нажать "Add to queue"

Кнопки управления

Play/Pause — кнопка в центре
Previous / Next — стрелки
Remove — появляется при наведении на трек в очереди
Clear all — очистить всю очередь

Горячие клавиши

Работают когда фокус не в поле ввода:

Пробел — пауза/играть
→ — следующий
← — предыдущий

Управление плейлистом

Вставить ссылку плейлиста YouTube в поле "Fallback playlist"
Нажать "Load playlist" и подождать (500–800 треков загружаются около минуты)
Нажать "Enable" — плейлист начнёт играть когда очередь опустеет

Панель с треками плейлиста появляется справа автоматически после загрузки. Клик по треку переключает на него немедленно.

Метки на треках

Зелёная рамка — играет сейчас
Золотая полоска слева — трек от доната
Синяя полоска слева — трек из плейлиста
Полупрозрачный — уже проигран

API

Управление воспроизведением

curl -X POST http://localhost:8093/api/play
curl -X POST http://localhost:8093/api/pause
curl -X POST http://localhost:8093/api/stop
curl -X POST http://localhost:8093/api/next
curl -X POST http://localhost:8093/api/previous

Очередь

# Добавить трек
curl -X POST "http://localhost:8093/api/add-url?url=ССЫЛКА&user=ИМЯ"

# Добавить платный трек
curl -X POST "http://localhost:8093/api/add-url?url=ССЫЛКА&user=ИМЯ&paid=true"

# Получить очередь
curl -X GET http://localhost:8093/api/queue

# Удалить трек (index с 0, считается от текущего)
curl -X POST "http://localhost:8093/api/remove?index=0"

# Очистить всё
curl -X POST http://localhost:8093/api/clear

Эндпоинты плейлиста

curl -X POST "http://localhost:8093/api/playlist/set?url=ССЫЛКА"
curl -X POST http://localhost:8093/api/playlist/enable
curl -X POST http://localhost:8093/api/playlist/disable
curl -X POST http://localhost:8093/api/playlist/reload
curl -X GET  http://localhost:8093/api/playlist/tracks
curl -X POST "http://localhost:8093/api/playlist/jump?index=5"
curl -X POST http://localhost:8093/api/playlist/shuffle

Информация

curl -X GET http://localhost:8093/api/status
curl -X GET http://localhost:8093/api/nowplaying
curl -X GET http://localhost:8093/api/donation/status

WebSocket

const ws = new WebSocket("ws://localhost:8093/ws");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.action   — playing / paused / stopped
  // data.current  — текущий трек
  // data.queue    — вся очередь
  // data.position — индекс текущего трека в очереди
};

ws.onclose = () => setTimeout(() => connectWebSocket(), 3000);

Возможные проблемы

Не запускается — проверить валидность config.json, доступность порта, корректность youtube_api_key.

Треки не добавляются — проверить youtube_api_key и ограничения (max_duration_minutes, min_views). Программа работает только с музыкальными видео.

Донаты не работают — проверить donation_widget_url (должны быть ref и token), donation_min_amount. В сообщении доната должна быть ссылка на YouTube.

Плейлист не загружается — плейлист должен быть публичным. При большом количестве треков загрузка может занять около минуты.

В OBS не показывается видео — убедиться что что-то играет (оверлей прозрачен в паузе/стопе). Попробовать ПКМ → Refresh на источнике.

Дополнительно

Приоритет треков: платные (донаты) → обычные → плейлист.

Горячее обновление конфига: при изменении config.json настройки применяются без перезапуска.

Кэш: информация о видео и плейлистах кэшируется на диске (cache.db) на 7 дней. Повторные запросы к YouTube API не выполняются до истечения TTL. При первом запуске после обновления удалите cache.db если видео перестали воспроизводиться.

Музыка за баллы: для настройки наград рекомендую Firebot. По вопросам настройки — Telegram-канал Key Twitch.

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github/workflows		.github/workflows
DOCS		DOCS
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
LICENSE		LICENSE
README.md		README.md
api.go		api.go
cache.go		cache.go
config.go		config.go
config.sample.json		config.sample.json
dashboard.html		dashboard.html
dashboard.png		dashboard.png
dock.html		dock.html
dock.png		dock.png
donation.go		donation.go
go.mod		go.mod
go.sum		go.sum
main.go		main.go
overlay.html		overlay.html
player.go		player.go
playlist.go		playlist.go
queue.go		queue.go
youtube.go		youtube.go

Folders and files

Latest commit

History

Repository files navigation