Media Locator API

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

Оглавление

Введение

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

Логика взаимодействия клиентского ПО, серверов Регистратуры и серверов Оператора-вещателя подразумевает согласованность идентификаторов выпусков телепрограмм, фильмов, серий сериалов и т.д. (далее в тексте – идентификаторы элементов медийного каталога). В настоящем документе не описывается механизм согласования идентификаторов.

Термины и определения

В этом документе используются термины и определения, описанные в документах «О программных интерфейсах сервисов Инетры» и «Термины и определения».

Взаимодействие с API

API подразумевает доступ только аутентифицированного пользователя (возможно, анонимного), пользующегося авторизованным приложением. Таким образом здесь закладывается возможность внедрения системы оплаты для получения контента.

В следствие чего данное API должно быть доступно только по HTTPS. Формат запроса:

https://<path_to_api>/<api_version>/<method>.<format>?[params]

Где:

Значения всех параметров перед передачей серверу необходимо кодировать для предотвращения неоднозначной интерпретации так, как это рекомендуется в RFC3986.

Коды ответов сервера должны соответствовать стандартным кодам HTTP-ответов для соответствующих ситуаций. Если по запросу не найдено никакой информации, сервер должен вернуть нормальный (код 200) пустой ответ.

Аутентификация

Для аутентификации пользователя клиент должен передать полученный ранее токен доступа, выданный службой контрагента, реализующей Auth API, по схеме аутентификации в соответствии с типом токена.

Для авторизации по типу токена «Bearer» рекомендуется использовать HTTP заголовок Authorization, пример:

Authorization: Bearer 18dasd81230dah12032

Если в рамках контрагента не объявлена служба, реализующая Auth API, то клиент должен обратиться к API без указания токена доступа. Если будет возвращен ответ с кодом 401, то клиент должен рассматривать службу Media Locator как временно недоступную.

Интерпретация прав доступа

При получении информации о местах расположения контента из медийных каталогов в сообщении Rip могут быть переданы условия доступа:

Ниже описана интерпретация совместного использования атрибутов условного доступа в виде сочетаний характера и параметров доступа:

В рассмотренных случаях для атрибута allowed_till HTTP ответ с кодом 401 в процессе воспроизведения записи должен быть интерпретировать как окончание подписки.

В остальных, неуказанных выше, случаях атрибуты pending_till, allowed_till должны быть проигнорированы клиентом.

Интерпретации указанного сервером времени производится с учетом текущего времени сервера, переданного им в ответе в HTTP заголовке Date.

Фильтрация контента

При обращении к сервису MediaLocator клиент может сообщить дополнительную информацию, которая позволит сформировать ответ, содержащий информацию о местах расположения только поддерживаемого клиентом контента.

По поддерживаемым функциям

Клиент может передать список поддерживаемых функций при помощи HTTP заголовка Client-Capabilities. Возможные значения:

HTTP заголовок Client-Capabilities задается грамматикой в форме ABNF (см. RFC2616):

Client-Capabilities = "Client-Capabilities" ":" 1#feature
feature = token

Замечание:

Пример задания заголовка

Client-Capabilities: paid_content,adult_content

Рекомендации по использованию API

Телевизионный контент

Если для элемента медийного каталога можно установить связь с телеканалом, то рекомендуется при обращении к MediaLocator API учитывать признак наличия архива у источников канала контрагента. Если у контрагента нет источников вещания канала с признаком наличия архива, то вероятно, что для элемента каталога для того же канала не будут присутствовать записи.

Клиент не должен запрашивать информацию о местоположении контента для элементов медийного каталога, которые являются еще не вышедшими в эфир выпусками телепередач.

Общие параметры запросов

параметр тип смысл
token строка токен доступа, может быть выдан службой аутентификации контрагента. (устарело с версии 1.3.2)

Параметр token не указывается, если контрагент не имеет службы аутентификации, реализующего Auth API.

Стандартные коды ответов

Для каждого метода API предусмотрены стандартные коды ответов (RFC2616). Ниже описана интерпретация некоторых кодов:

Если аутентификация возможна, то для кодов 401, 403 должен быть передан HTTP заголовок WWW-Authenticate с указанием ожидаемой схемы аутентификации и дополнительнной информации (если применимо). Например, для схемы «Bearer» может быть указан дополнительный атрибут error со значением:

Методы

sources — Получение ссылок на источники вещания элементов каталога

Параметр Значение по умолчанию Описание
id отсутствует Список логических идентификаторов элементов каталога (через запятую)

Важно не путать элемент медийного каталога, например, выпуск телепередачи (telecast), и экземпляр записи выпуска телепередачи или фильма (rip). В параметре id передается список идентификаторов элементов каталога.

Формат ответа: сообщение SourcesReply.

Замечания:

Нишевый контент

Пример получения ссылки на источник нишевого контента:

{ «replies»: [ { «catalogue_item_id»: 405623041, «niche»: [ { «video_id»: «1952cca28b042a3dc747f2b039beb61928d080cd», «video_url»: «https://storage.yandexcloud.net/inetra-test/fulm2/fulm/playlist.m3u8» } ] } ] }

timeshift — получение ссылки на источник вещания со смещением от эфирного

Параметр по умолчанию описание
stream_id отсутствует идентификатор источника вещания (из IPTV)
offset отсутствует смещение в секундах от эфира (положительное целое)
start_over отсутствует признак перехода на начало эфирной передачи (логическое)

Позволяет получить ссылку на источник вещания со смещением от эфира. В целях оптимизации нагрузки сервер может переопределить запрошенное смещение, в этом случае в ответе будет указано фактическое смещение, отличное от запрошенного.

Замечания:

Рекомендуется использовать параметр start_over для реализации функции «Начать с начала».

Формат ответа: TimeshiftReply.

Пример успешного взаимодействия

Запрос

GET /medialocator/1/timeshift.json?stream_id=232&start_over=true HTTP/1.1
Host: api.peers.tv
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Ответ

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "uri":"http://hls.peers.tv/timeshift/5kanal/16/playlist.m3u8?offset=130&token=2YotnFZFEjr1zCsicMWpAA",
  "offset": 130
}

Описание сообщений

SourcesReply — ответ на метод sources

message SourceReply {
  optional int64 catalogue_item_id = 1;
  repeated Rip rips = 2;
  repeated Rip trailers = 3;
  repeated VOD vod = 4;
}

message SourcesReply {
  repeated SourceReply replies = 1;
}

message VOD {
   optional VODType type = 1;   
   optional string video_id = 2;
   optional string video_url = 3;
   optional DModel distribution_model = 4;
   optional string auth_url = 5;
   optional string stream_url = 6;

   enum VODType {
        RUTUBE= 1;
        TVIGLE = 2;
        IVI = 3;
        MEGOGO = 4;
    }   

   enum DModel {
        FREE= 0;
        AVOD = 1;
        SVOD = 2;
        TVOD = 3;
    }   
}

Замечания:

Rip — информация о рипе

enum RipDefinition {
  SD = 0;
  HD = 1;
}

enum RipStatus {
  ACCESS_ALLOWED = 200;
  ACCESS_PENDING = 220;
  ACCESS_PURCHASED = 221;
  ACCESS_DENIED = 403;
}

enum StreamingType {
  PROTOCOL_DEFAULT = 0;
  HTTP_LIVE_STREAMING = 1;
}

message Rip {
  optional int64 id = 1;
  repeated RipPart parts = 2;
  repeated string snapshots = 3;
  optional RipDefinition definition = 4;
  optional RipStatus status = 5 [default = ACCESS_ALLOWED];
  optional StreamingType streaming_type = 6 [default = PROTOCOL_DEFAULT];
  optional int64 allowed_till = 7;
  optional int64 pending_till = 8;
  optional bool ad_targeting = 9;
}

Замечания:

Интерпретация атрибутов status, allowed_till, pending_till описана в разделе «Интерпретация прав доступа»

RipPart — часть рипа

message RipPart {
  optional ContainerInfo container_info = 1;
  repeated Location locations = 2;
  optional uint32 start_position = 3 [default=0, deprecated=true];
  optional uint32 end_position = 4 [deprecated=true];

  optional float playback_start_time = 5 [default=0];
  optional float playback_end_time = 6;
}

Замечания:

Для получения точных меток начала и остановки воспроизведения рекомендуется использовать атрибуты playback_start_time, playback_end_time, значения атрибутов — неотрицательные.

ContainerInfo — информация о контейнере

message ContainerInfo {
  optional string format = 1;
  optional string format_profile = 2;
  repeated TrackInfo tracks = 3;
}

Замечания:

TrackInfo — информация о дорожке

enum TrackType {
  VIDEO = 0;
  AUDIO = 1;
  SUBTITLE = 2;
}

message TrackInfo {
  optional TrackType type = 1;
  optional string codec = 2;
  optional string format = 3;
  optional string format_profile = 4;
  optional string language = 5;
  optional uint32 duration = 6;
  optional uint32 bitrate = 7;
  repeated Location locations = 8;
  // for video
  optional uint32 width = 9;
  optional uint32 height = 10;
  optional float fps = 11;
  // for audio
  optional int32 channel_count = 12;
}

Замечания:

Location — источник вещания

message Location {
  optional string uri = 1;
  optional uint32 usage_weight = 2;
}

Замечания:

TimeshiftReply

message TimeshiftReply {
   optional string uri = 1;
   optional uint32 offset = 2;
}

Замечания:

Ожидайте в следующих версиях

История версий

Изменения в версии 1.1

Изменения в версии 1.2

Изменения в версии 1.3

Изменения в версии 1.3.1

Изменения в версии 1.3.2

Изменения в версии 1.3.3

Изменение в версии 1.4 (TVREC–484)

Изменение в версии 1.4.1 (TVREC–595)

Изменение в версии 1.5.0 (TVREC–629)

Изменение в версии 1.6.0 (TVREC–673)

Изменение в версии 1.6.1

Изменение в версии 1.7.0 (TVREC–688)

Изменение в версии 1.8.0 (TVREC–943)

Изменение в версии 1.9.0 (PTVTUBE–165)

Изменение в версии 1.10.0

Изменение в версии 1.11.0

Изменение в версии 1.12.0