EPG для OTT middleware

Программа передач из базы EPG выдаётся внешним системам — приставкам, приложениям и OTT middleware — двумя способами: полным документом XMLTV через выделенный EPG-сервер и суточной программой канала в JSON через HTTP API узла.

Выдача XMLTV

XMLTV раздаёт отдельный встроенный EPG-сервер. Он включается на экране «EPG-сервер» (EPG-сервер): «Включить EPG-сервер», HTTP-порт (по умолчанию 43973), при необходимости HTTPS с сертификатом (порт по умолчанию 43983) и «Имя хоста». Включение и выключение действуют сразу, без перезапуска службы; выключенный сервер не открывает ни HTTP-, ни HTTPS-порт.

Доступ — по учётным записям (вкладка «Учётные записи» экрана «Настройки EPG», Настройки EPG): логин и пароль, «Набор каналов», «Дата окончания» действия, «Разрешённый IP» и признак «Приостановлен». Состав выдачи определяется набором каналов:

  • наборы создаются на вкладке «Наборы каналов»;

  • каналы включаются в наборы в базе данных EPG (База данных EPG); канал может входить в несколько наборов;

  • учётной записи назначается один набор — без него выдача пуста;

  • набор, назначенный учётной записи, удалить нельзя; при удалении набора удаляется и его состав.

Документ доступен по пути /xmltv (и /xmltv.gz — сжатый файл); авторизация — HTTP Digest либо через параметры запроса. Время передач выдаётся с часовым поясом канала; в документ попадают только текущие и будущие события. Если один и тот же идентификатор канала пришёл из разных источников, канал выдаётся один раз, о пропуске сообщает журнал. С версии 2.0.2.418 вместе с каналом пропускаются и его передачи; раньше они попадали в документ под идентификатором выданного канала, рядом с его собственными передачами, и передача могла повториться.

Полная выгрузка с данными привязки

С версии 2.0.2.418 EPG-сервер отдаёт и полную выгрузку XMLTV для привязки эфирных каналов к программе передач: путь /xmltv-src (и /xmltv-src.gz — сжатый файл). В отличие от /xmltv, в неё попадают каналы всех источников (или выбранных), с данными, по которым канал связывают с источником:

  • идентификатор канала в выгрузке — <источник>:<канал>, он уникален, даже если один и тот же канал есть в нескольких источниках;

  • у каждого канала — номер и имя источника (src-id, src-name), собственный идентификатор канала в ленте (channel-id, ключ привязки), дополнительный идентификатор (channel-id2), если он задан, часовой пояс (time-zone) и время окончания последней передачи (last-stop);

  • все названия и значки канала; канал выдаётся, даже если передач у него нет, а канал без названия получает название, равное его идентификатору;

  • время передач — в UTC (+0000), часовой пояс канала не применяется и передаётся атрибутом; у передачи выдаются все названия, описания, жанры и возрастные рейтинги. С версии 2.0.2.419 подзаголовок передачи (например, название серии) выдаётся отдельным элементом <sub-title>, а <title> — без него; какой подзаголовок выделяется, описано ниже, в Суточная программа в JSON.

Параметры запроса:

  • src — all (по умолчанию) или номера источников через запятую; 0 — встроенный источник «поток-импорт». Выключенные источники и неизвестные номера пропускаются;

  • programmes — 1 (по умолчанию) выдаёт каналы и передачи, 0 — только каталог каналов;

  • days-back — 0 (по умолчанию) выдаёт текущие и будущие передачи, как /xmltv; N — начиная с полуночи UTC N суток назад, но не глубже срока хранения истории («Хранить историю, дней», Настройка источников).

Неверное значение параметра отклоняется с кодом 400. Доступ — по учётным записям EPG-сервера, как к /xmltv: учётная запись с признаком all-channels (в файле настроек или через API; с версии 2.0.2.419 — переключатель «Все каналы в /xmltv-src», Настройки EPG) получает все каналы выбранных источников, остальные — только каналы своего набора. Запрос с самого узла (с локального адреса) получает все каналы без учётной записи — только на этом пути.

Выгрузка собирается на сервере и кешируется до изменения данных её источников или настроек, но не дольше 5 минут. Повторный запрос того же содержимого с заголовком If-None-Match получает ответ 304. Большая выгрузка с прошлыми сутками собирается минутами; одновременно собирается одна выгрузка с передачами, остальные ждут. Если собрать выгрузку сейчас нельзя (служба останавливается, источник удаляется, очередь занята), сервер отвечает 503 с заголовком Retry-After: 30. Формат /xmltv не меняется.

Суточная программа в JSON

Для интерфейсов middleware узел отдаёт программу канала за сутки одним запросом к HTTP API в формате JSON (авторизация — как у остальных запросов API):

GET /data/epg/channel?src=<источник>&ch=<канал>&lang=<язык>&t=<время>

Возвращается список событий суток (по UTC), в которые попадает время t: начало, конец, название и описание каждой передачи на запрошенном языке; если перевода нет, используется язык по умолчанию, затем любой доступный. С версии 2.0.2.418 у передачи с возрастным рейтингом есть и он — объект rating: age (возраст в годах, 16 для рейтинга 16+, 0 для 0+) и system (система рейтинга из ленты XMLTV или код страны DVB, если он известен). Рейтинг берётся из элемента <rating> ленты XMLTV или из родительского рейтинга DVB EIT; если у передачи их несколько, выдаётся наибольший возраст. У передачи без рейтинга этого объекта нет.

С версии 2.0.2.419 подзаголовок передачи (элемент <sub-title> ленты XMLTV, например название серии) выдаётся отдельным полем sub на языке названия, а title — уже без подзаголовка. До версии 2.0.2.418 включительно подзаголовок дописывался к названию: Новости. Выпуск 1. У передачи без подзаголовка поля sub нет.

Отдельно выдаётся только подзаголовок на языке названия или без указания языка. Подзаголовок на другом языке (например, английский под русским названием) по-прежнему дописывается к названию, и отдельного поля у него нет. Если у передачи два подзаголовка — на языке названия и следом иностранный, — отдельное поле содержит оба через точку: A. B.

Обычная выдача /xmltv, EIT на выходе и веб-интерфейс по-прежнему показывают название вместе с подзаголовком. После обновления узла база EPG дополняется на месте, данные не теряются; подзаголовки появляются после очередного обновления каждого источника.

Пустые сутки — валидный пустой список. Ответы кешируются сервером и обновляются автоматически при поступлении новых данных EPG.

Встроенный кеш рассчитан примерно на тысячу одновременных клиентов; для более крупных установок и XMLTV-, и JSON-выдачу рекомендуется закрывать кеширующим обратным прокси или CDN.

Воспроизведение архива DVR по событию программы передач (параметр epg в URL воспроизведения) описано в Воспроизведение архива (VOD).