OTT API

Статус документа

Оглавление

Общая информация

OTT API - специальный API для конфигурирования HLS-AAA (он же OTT-Auth), который позволяет оператору целиком и полностью управлять каналами и потоками вещания.

Требования

Общие

• Формат ответа: JSON;
• Кодировка: UTF–8;
• Рекомендуемый Content-Type: application/json; charset=UTF-8.

К сериализации в JSON

• не допускается переименовывание полей, изменение стиля (например, на camelCase) и регистра;
• boolean сериализуется как true | false;
• ENUM сериализуется с преобразованием в integer;
• спецсимволы в строках должны быть экранированы согласно стандартам JSON (ECMA–404, RFC4627).

Методы

channels - получение информации о каналах и потоках

Формат ответа

Сообщение ChannelList

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

Подробнее: Protocol Buffers

Сообщение Channel

Подробнее: Protocol Buffers

Сообщение StreamSource

Подробнее: Protocol Buffers

Сообщение UserAgentRegexps

Подробнее: [Protocol Buffers][p-useragentregexps]

Сообщение Category

Подробнее: [Protocol Buffers][p-category]

Описания форматов способом Google Protocol Buffers

ChannelList - список каналов и категорий

message ChannelList {
    required string title = 1;                     // Человекочитаемое название плейлиста
    repeated Channel channels = 2;
    repeated Category categories = 3;
    repeated Settings settings = 4;
}

Channel - описание канала

message Channel {
    // Порядок сортировки каналов в выводе API будет использован для позиционирования части каналов, не попавших ни в одну категорию, в списке.
    required uint32 id = 1;                       // Единый постоянный идентификатор канала, совпадающий с использующимся RADIUS-сервером
    required string alias = 2;                    // Единый постоянный текстовый идентификатор канала
    required string title = 3;                    // Человекочитаемое название канала
    repeated StreamSource streams = 4;            // Источники вещания канала, обязательный параметр

    optional string identifier_url = 5;           // Ссылка на сущность (страница канала на сайте)
    optional string schedule_url = 6;             // Ссылка на программу телепередач
    optional string logo_url = 7;                 // Ссылка на логотип канала

    enum ChannelStatus {
        TESTING = 0;
        LAUNCHED = 1;
    }

    optional ChannelStatus status = 8;            // Статус канала: тестовое / боевое вещание
}

StreamSource - описание источника

message StreamSource {
    required uint32 id = 1;                       // Постоянный идентификатор (например, порядковый номер) потока в рамках канала
    required string url = 2;                      // URL источника.
                                                  // Если тип источника = HLS_VARIANT:
                                                  // * Если передать пустую строку, URL будет автоматически сгенерирован согласно конфигурации HLS-AAA.
                                                  // * Настоятельно рекомендуется использование макроса "%(session_id)s", если дается ссылка на раздатчик HLS-AAA. Пример: http://hls.zomg.fqdn/masterindex/?sid=%(session_id)s

    optional string protected_path = 3;           // Путь для отдачи файлов (сегментов) через nginx по HTTP посредством X-Accel-Redirect.
                                                  // Это поле *требуется* для раздачи HLS, но совершенно бесполезно для потоков типа UDP|HLS_VARIANT|RAW.
                                                  // Требуется присутствие макроса "%(filename)s", который будет заменяться именем отдаваемого файла. Пример: "/protected/1kanal/tvrec/%(filename)s"

    enum StreamSourceType {
        HLS = 0;
        UDP = 1;
        HLS_VARIANT = 2;
        RAW = 3;                                  // Источник неподдерживаемого формата и/или без авторизации, адрес которого отдается "как есть". Тип на будущее, например, для HLS без ААА.
    }

    required StreamSourceType type = 4 [default = HLS];

    optional StreamSource substreams = 5;         // Максимально допустимый уровень вложенности: 1 (channel -> streams -> substreams)

    optional uint32 bandwidth = 6;                // Согласно стандарту HLS
    optional string resolution = 7;               // Согласно стандарту HLS
    optional string codecs = 8;                   // Согласно стандарту HLS
    optional string audio = 9;                    // Согласно стандарту HLS
    optional string name = 10;                    // Опциональный хак: LQ | MQ | HQ, подробнее: http://drug/iwiki/pages/viewpage.action?pageId=13567356

    // Регулярные выражения должны поддерживаться стандартным Python'овским модулем re: https://docs.python.org/2/library/re.html
    optional UserAgentRegexps user_agents = 11;   // Список User-Agent'ов, которым можно/нельзя отдавать источник

    optional bool recordable = 12;                // Флаг наличия записей телепередач для этого потока
    optional string aspect_ratio = 13;            // Соотношение сторон для правильного отображения (растягивания/сужения) картинки, например, "16:9"
    optional string crop = 14;                    // Ширина:высота части кадра, которую необходимо гарантированно показать при кадрировании изображения, в процентах, например, "100:70"
    optional bool has_timeshift = 15;             // Флаг поддержки источником технологии Timeshift
    optional uint32 territory_id = 16;            // ID территории
    optional string timeshift_url = 17;           // URL для получения списка сегментов по технологии Timeshift. Обязателен, если has_timeshift=True. Требуется наличие макро %(program_id)s
    optional string timeshift_header = 18;        // Заголовок, который необходимо отправлять при отдаче списка сегментов источника, который поддерживает timeshift. Если строка пуста или отсутствует, заголовок будет сгенерирован автоматически согласно шаблону из настроек HLS-AAA. Поддерживается макро: %(alias)s, %(stream_id)d, %(substream_id)d, %(session_id)s
    optional string records_protected_path = 19;  // Полная аналогия `protected_path`, только для архива записей телепередач. Обязателен, если `recordable` = `True`. Требуется наличие макро %(date_time)s
    optional string crop_iptv = 20;               // По аналогии с `crop`, только в формате для IP-TV Player: обрезка кадра WxH+X+Y. Например, "690x550+15+10". Документация: http://borpas.info/iptvplayer-docs#16
}

UserAgentRegexps - набор регулярных выражений для фильтрации источников на основе User-Agent

message UserAgentRegexps {
    repeated string regexp_list = 1;              // Обязательный параметр. Если регулярное выражение не валидно, оно будет отброшено.

    enum UserAgentRegexpType {
        INCLUDE = 0;                              // Отдавать источник только для указанных User-Agent'ов
        EXCLUDE = 1;                              // Отдавать источник всем, кроме указанных User-Agent'ов
    }

    required UserAgentRegexpType type = 2 [default = INCLUDE];
}

Category - описание категории каналов

message Category {
    // Порядок сортировки будет использован для отображения каналов в плеере, см. https://wiki.videolan.org/XSPF/#VLC_Extensions
    required string title = 1;                     // Человекочитаемое название категории. Дублирующиеся категории будут объединены
    repeated uint32 channels = 2;                  // Список Channel ID. Список каналов каждой категории будет дедуплицирован, а несуществующие каналы - удалены.
}

Settings - различные настройки

message Settings {
    optional UserAgentRegexps access_denied_channels_display_control = 1;   // Используется для перечисления User-Agent, которым можно/нельзя отдавать недоступные пользователю каналы.
}

Примеры использования

Запрос:

GET /channels

Тело ответа:

{
    "title": "Телевидение Электронного города",
    "channels":
    [
        {
            "id": 10338232,
            "alias": "vesti",
            "title": "Россия 24",
            "streams":
            [
                {
                    "id": 0,
                    "url": "http:\/\/localhost\/remote_pls\/streaming\/vesti\/tvrec\/playlist.m3u8",
                    "protected_path": "\/protected\/streaming\/vesti\/tvrec\/%(filename)s",
                    "type": 0,
                    "bandwidth": 1024,
                    "resolution": "720x576",
                    "codecs": "avc.zomgwtf",
                    "recordable": true,
                    "has_timeshift": true,
                    "timeshift_url": "http:\/\/peers.tv\/timeshift\/vesti\/16\/playlist.m3u8?start_time=%(offset)s",
                    "timeshift_header": "base-uri="http:\/\/hls-aaa\/timeshift\/vesti\/playlist.m3u8";duration=3600",
                },
                {
                    "id": 1,
                    "url": "udp:\/\/@239.1.15.3:1234",
                    "type": 1,
                    "bandwidth": 1024,
                    "resolution": "720x576",
                    "codecs": "avc.qwerty",
                    "recordable": false,
                    "has_timeshift": false,
                    "user_agents":
                    {
                        "regexp_list":
                        [
                            "^.*$",
                            "samsung",
                            "smarttv",
                            "^eltex"
                        ],
                        "type": 0
                    }
                }
            ],
            "identifier_url": "http:\/\/www.cn.ru\/entities\/10338232\/",
            "schedule_url": "http:\/\/www.cn.ru\/tv\/program\/vesti",
            "logo_url": "http:\/\/www.cn.ru\/data\/illustrations\/ills\/2013\/08\/01\/24493\/24493963.png",
            "status": 1,
            "territory_id": 17
        }
    ],
    "categories":
    [
        {
            "title": "Эфир",
            "channels": [10338245, 10338232]
        },
        {
            "title": "Познавательный",
            "channels": [10338246]
        }
    ],
    "settings":
    [
        "access_denied_channels_display_control":
        {
            "regexp_list":
            [
                "^.*$"
            ],
            "type": 1
        }
    ]
}