API — различия между версиями

Версия 14:08, 10 февраля 2015

Термины

Контент – содержательная часть видео- или радиотрансляции в цифровом виде.

- Сервис – программно-аппаратный комплекс предоставления доступа к IPTV как к услуге.

- Клиент – приложение или устройство, получающее доступ к Сервису посредством учет- ной записи.

- Абонент – физический пользователь сервиса SUNDUK.TV

- Абонемент – учетная запись клиента. Логин и пароль цифровые – для удобства набора со стандартного пульта управления устройства (settopbox).

- Сервер вещания – streamserver – программно-аппаратный комплекс для организации трансляции потокового видео и радиосигнала.

- Ссылка вещания – URL, по адресу которого сервер вещания транслирует контент.

- Middleware – комплекс сервисов авторизации и управления абонементами, потоками вещания, персональными настройками.

- API – интерфейс Middleware для программного взаимодействия с клиентом.

Принцип работы

Провайдер транслирует видеопотоки телевизионных и радио каналов в сети Интернет. Видеокон- тент предоставляется посредством транспортного потока HTTP/TS с распределенных серверов провайдера. Контент закодирован видеокодеком H.264 и аудиокодеком AAC (подробные техни- ческие характеристики потока представлены в справочном разделе настоящего руководства). Сервис предоставляется на платной основе, в виду чего становится невозможным предоставлять доступ к вещанию обычными средствами. В отличие от ссылок типовых списков воспроизведения (playlists), ссылки вещания не могут быть постоянными, поэтому они динамически генерируются на время сессии работы клиента. Для генерации уникальной ссылки необходимо реализовать методы работы с сессией клиента. При первом обращении к системе необходимо авторизоваться и инициировать сессию. Ответ сервера включает в себя ключ сессии, который необходимо передавать при каждом обращении. Для удобства реализации сервер принимает ключ сессии как в виде параметра URL, так и в виде COOKIES.

Общий алгоритм приложения можно представить следующим образом:

1. авторизация /login и получение списка настроек клиента

2. получение списка каналов, групп каналов, текущего EPG на каждый канал. /channel_list

3. при выборе абонентом канала необходимо получить ссылку вещания для этого канала /get_url

4. проигрывание полученной ссылки воспроизведения

5. подгрузка следующего фрагмента EPG при окончании телепередачи /epg_current

6. загрузка EPG на весь день при просмотре программы телепередач за этот день и при вы- боре телепередачи из архива.

Использование API

Работа с API подразумевает работу с сетью и не накладывает на приложение клиента никаких ограничений по выбору средств реализации. Другими словами – программная часть клиента мо- жет быть реализована на любом языке программирования, который может использовать библио- теки работы с сетью и протокол HTTP. Поскольку типы ответов могут быть как в формате XML, так и в формате JSON, рекомендуется использовать готовые библиотеки для работы с этими форматами данных. Мы рекомендуем использовать формат JSON как наиболее удачный формат для работы с ассоциативными (хэш) массивами. Также рекомендуется использовать автономное хранилище для хранения промежуточных данных (ключ сессии, настройки клиента, всевозможные списки и т.п.) Все запросы к API отправляются по протоколу HTTP, формируются по специально сформирован- ному URL и имеют следующий вид:

httр://iptv.sunduk.tv/api/<тип ответа>/<имя функции>?param1=value&param2=value...

<тип ответа> задает формат выходных данных. Данные могут быть типов: XML, JSON, JSONP

Примеры вызовов:

httр://iptv.sunduk.tv/api/xml/epg?cid=2&day=260212

httр://iptv.sunduk.tv/api/json/epg?cid=2&day=260212

httр://iptv.sunduk.tv/api/jsonp/epg?cid=2&day=260612&callback=process

Все возвращаемые сообщения имеют вид ассоциативного массива.

В случае ошибочного запроса API возвращает XML-пакет следующего содержания:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error>
    <message>ERROR_MESSAGE</message>
    <code>ERROR_CODE</code>
  </error>
  <servertime>SERVER_TIME</servertime>
</response>

message - сообщение об ошибке

code - код ошибки

servertime - время на сервере (формат unixtime)

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

Все данные, обозначающие дату и время, представлены в формате unixtime. Каждый ответ серве- ра имеет отпечаток времени сервера (для синхронизации) с тегом <servertime>

Cookie

Для идентификации и создания сессии используется стандартный механизм HTTP-сессий с под- держкой COOKIE. При первом входе необходимо выполнение login. При корректном входе возвращается парамет- ры состояния, данные по клиенту и COOKIE, которые необходимо передавать при последующих запросах. В COOKIE хранится идентификатор сессии. Если запрос не содержит COOKIE, то это вызо- вет ошибку. Для корректного завершения сессии необходимо вызвать метод logout. COOKIE уста- навливается стандартным HTTP ответом, поэтому если клиент использует браузер или фреймворк, то COOKIE будут передаваться автоматически, в противном случае клиент должен позаботиться об сохранении ключа сессии. Также возможна передача параметров &<имя сессии>=<ключ сессии> через url. <Имя сессии> при этом необходимо брать из ответа пакета функции /login. Подобный метод из соображений без- опасности является не желательным, ровно как и передача login методом GET. Рекомендуем ис- пользовать HTTPS (безопасное шифрованное соединение через SSL) для авторизации.

Функции API

Функция login

Описание функции: функция выполняет логин клиента.

Вызов: /login?login=<login>&pass=<password>&device=<apple|default:all>&settings=all

Входные параметры для функции:

login - номер абонемента, выданный клиенту

pass - пароль абонемента

device - Параметр, указывающий на тип устройства, работающего с API. Генерируют- ся соответствующие потоки и ссылки вещания. Влияет на списки возможных для устройства каналов, ссылки вещания и т.п. На данный момент работает с двумя параметрами: apple и all. По умолчанию установлен в all и генери- рует ссылки для vlc. (поток TS)

setting=all - Выводит значения всех текущих настроек клиента. Рекомендуется для использования предварительной загрузки всех настроек клиента.

Пример ответа по запросу /login?login=1234567&pass=1234567&device=all&settings=all

<?xml version="1.0" encoding="UTF-8"?>
<response>
<sid>3basjk82caac5cbklcqgqac3h2</sid>
<sid_name>MWARE_SSID</sid_name>
<account>
  <login>1234567</login>
  <packet_name>Test packet</packet_name>
  <packet_expire>1586410112</packet_expire>
</account>
<services>
  <vod>1</vod>
  <archive>1</archive>
</services>
<settings>
  <timeshift>
    <value>0</value>
    <list>
      <item>0</item>
      <item>1</item>
      <item>2</item>
      <item>3</item>
      <item>4</item>
      <item>7</item>
      <item>8</item>
      <item>9</item>
      <item>10</item>
      <item>11</item>
      <item>12</item>
    </list>
  </timeshift>
  <timezone>
    <value>0</value>
  </timezone>
  <http_caching>
    <value>3000</value>
    <item>
      <item>1500</item>
      <item>3000</item>
      <item>5000</item>
      <item>8000</item>
      <item>15000</item>
    </item>
  </http_caching>
  <stream_server>
    <value>91.224.187.34</value>
    <list>
<item>
<ip>91.224.187.34</ip>
        <descr>Europe South</descr>
      </item>
      <item>
        <ip>91.224.186.2</ip>
        <descr>Europe North</descr>
      </item>
      <item>
        <ip>217.19.223.2</ip>
        <descr>USA East Coast</descr>
      </item>
      <item>
        <ip>217.19.219.34</ip>
        <descr>USA West Coast</descr>
      </item>
      <item>
        <ip>217.19.220.2</ip>
        <descr>Middle East</descr>
      </item>
      <item>
        <ip>103.246.216.34</ip>
        <descr>Asia</descr>
      </item>
    </list>
  </stream_server>
  <bitrate>
    <value>1500</value>
    <list>
      <item>2500</item>
      <item>1500</item>
      <item>900</item>
      <item>320</item>
    </list>
  </bitrate>
</settings>
<servertime>1334861376</servertime>
</response>

sid - Идентификатор сессии

sid_name - Имя переменной идентификатора сессии

account -  Блок данных абонемента

login - Логин

packet_name -  Название пакета

packet_expire - Дата и время окончания абонемента

services - Блок флагов сервисов

vod - Флаг видеотеки. При установленном значении 1 абонементу доступна услуга «ви- деотека»

archive - Флаг архива. При установленном значении 1 абонементу доступна услуга «архив»

Функция account

Описание функции: возвращает информацию об аккаунте, аналогично функции login.

Вызов:

/account

Функция logout

Описание функции: выполняет отключение клиента от сервиса.

Вызов без параметров

/logout

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <message>M_LOGOUT_OK</message>
  <servertime>1277807573</servertime>
</response>

message - Сообщение об логауте

servertime - Время на сервере (в формате unixtime)

Функция channel_list

Описание функции: получение списка каналов.

Для вывода информации о скрытых каналах следует использовать /channel_list?show=all&protect_code=<пароль закрытых каналов> В этом случае будет показан спи- сок всех каналов с дополнительным тегом <hide>0</hide>, который указывает скрыт ли канал в обычном режиме.

В списке для каждого канала также имеется «таблица» возможных сочетаний bitrate и timeshift. Может сложиться ситуация, когда установленный системный bitrate в сочетании с timeshift не за- дан для некоторых каналов. В этом случае каналы не попадают в список /channel_list. Информа- ция доступна в теге <stream_params>

show - Режим отображения списка каналов. all = показ всех каналов в т.ч. скрытых; любое другое значение, в т.ч. отсутствие параметра устанавли- вает обычный режим отображения каналов.

protect_code - цифровой пароль для закрытых каналов. Обязательный параметр при show=all

Функция возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <groups>
    <item>
      <id>GROUP_ID</id>
      <name>GROUP_NAME</name>
      <color>CSS_CODE</color>
      <channels>
        <item>
          <id>CHANNEL ID</id>
          <name>CHANNEL_NAME</name>
          <stream_params>
            <item>
              <rate>BITRATE</rate>
              <ts> TIMESHIFT</ts>
            </item>
          </stream_params>
          <is_video>IS_VIDEO</is_video>
          <need_bandwidth>NEED_BANDWIDTH<need_bandwidth>
          <protected>PROTECTED</protected>
          <have_archive>HAVE_ARCHIVE</have_archive>
          <icon>ICON_PATH</icon>
          <epg_progname>EPG_PROGNAME</epg_progname>
          <epg_start>EPG_START</epg_start>
          <epg_end>EPG_STOP</epg_end>
</item>
        ...
      </channels>
    </item>
  </groups>
  <servertime>1277807687</servertime>
</response>

groups/item/id - идентификатор группы

groups/item/name - название группы

groups/item/color -  CSS код цвета группы

groups/item/channels/item/id - идентификатор канала

groups/item/channels/item/name -  название канала

groups/item/channels/item/stream_params - возможные параметры потоков

groups/item/channels/item/stream_params/item/rate - возможный битрейт канала. Устанавливается в настройках переменной bitrate

groups/item/channels/item/stream_params/ item/ts - таймшифт в часах. Например: значение 2 - за- держка вещания на 2 часа. Получить url вещания возможно установив в настройках переменную timeshift

groups/item/channels/item/is_video -  флаг потокового видео 0/1 1-видео, 0-радио

groups/item/channels/item/need_bandwidth - рекомендуемый битрейт канала

groups/item/channels/item/protected - флаг “защиты канала по паролю” 0/1

groups/item/channels/item/have_archive - флаг “имеет ли канал архив” 0/1

groups/item/channels/item/icon -  относительный путь к файлу иконки канала

groups/item/channels/item/epg_progname - название текущей телепередачи

groups/item/channels/item/epg_start - дата и время начала текущей передачи

groups/item/channels/item/epg_stop - дата и время окончания текущей передачи

Пример ответа по запросу /api/xml/channel_list

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <groups>
    <item>
      <id>1</id>
      <name>test1</name>
      <color>CSS_CODE</color>
      <channels>
        <item>
          <id>3</id>
          <name>Pоссия</name>
          <stream_params>
             <item>
                <rate>1500</rate>
                <ts>0</ts>
             </item>
             <item>
                <rate>900</rate>
                <ts>0</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>1</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>2</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>3</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>4</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>8</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>9</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>10</ts>
             </item>
             <item>
                <rate>1500</rate>
                <ts>11</ts>
             </item>
          </stream_params>
          <is_video>1</is_video>
          <protected>0</protected>
          <have_archive>1</have_archive>
          <icon>/img/ico/3.gif</icon>
          <epg_progname>ВЕСТИ-МОСКВА</epg_progname>
          <epg_start>1277807400</epg_start>
          <epg_end>1277808600</epg_end>
          <hide>1</hide>
</item>
        ...
      </channels>
    </item>
    <item>
      <id>2</id>
      <name>Новости</name>
      <color>#ef0000</color>
      <channels>
        <item>
          <id>6</id>
          <name>РТР Вести</name>
          <is_video>1</is_video>
          <protected>0</protected>
          <icon>/img/ico/6.gif</icon>
          <epg_progname>"Вести. Сейчас. Главные события".</epg_progname>
          <epg_start>1277807400</epg_start>
          <epg_end>1277807700</epg_end>
</item>
        ...
      </channels>
    </item>
  </groups>
  <servertime>1277807687</servertime>
</response>

Функция /get_url

Описание функции: получение ссылки вещания на заданный канал.

Вызов: /get_url?cid=<ИД канала>&gmt=<дата время позиции архива>&protect_code=<пароль для закрытых каналов>

url - Идентификатор канала, полученный из функции channel_list

gmt - Дата/время позиции архива в формате unixtime

protect_code - Цифровой пароль для закрытых каналов. Если канал закрыт, а пароль не передан, либо передан неверный пароль, то в тэге <url> возвращается слово "protected".

Архив. Сервисом организована запись некоторых телеканалов сроком до 14 дней для последую- щего вещания по требованию. Каналы имеющие архивную запись помечены флагом have_archive в списке каналов. Доступ к записанным данным возможен через указание параметра gmt для функции get_url, где указано время в формате unixtime. Архив доступен по истечении 30 минут после прямого эфира. Рекомендовано на стороне клиента ограничить доступ к несуществующему в архиве промежутку времени во избежание недоразумений. При попытки воспроизвести еще не записанный фрагмент будет воспроизведен ближайший доступный в архиве фрагмент.

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<url>http/ts://217.19.222.34:18046/?ticket=W4z3WFdoSRnMMXHgYFq...md4ZGtVyT6mjgqGZk%3D
:http-caching=1500 :no-http-reconnect</url>
<servertime>1277808472</servertime>
</response>

Параметр URL специально сгенерирован для проигрывания через VLC с соответствующими опти- мизированными параметрами. URL генерируется только один раз. Для повторного просмотра ка- нала необходимо получить заново сгенерированный URL. При попытке трансляции канала не- сколькими сгенерированными URL одновременно, будет транслироваться только URL, получен- ный последним. Таким образом, возможна трансляция только одного потока для одной сессии.

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

В некоторых случаях возникает необходимость фильтра каналов. По разным причинам абоненты не всегда желают видеть в списках некоторые каналы. Был разработан механизм скрытия кана- лов. Для абонента это выглядит как закрытая по паролю область со списком каналов, где можно включить/выключить каналы.

Функция /rule

Описание функции: работа с правилами.

/rule?cmd=<hide_channel|show_channel|get_list|reset_channels>&cid=<id_канала>&protect_code=< protect_code>

cmd - Команда механизма правил список возможных команд см. ниже

cid - Идентификатор канала

protect_code - цифровой пароль для закрытых каналов. Обязательный параметр

Возможные команды механизма правил:

hide_channel - Скрыть канал ID которого передан через параметр cid

show_channel - Отображать канал ID которого передан через параметр cid

get_list -  Получить список ID каналов

reset_channels - Сбросить список правил (обнулить)

Ответ команды cmd=<hide_channel show_channel reset_channels>

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <action>{hide_channel | show_channel | reset_channels}</action>
  <message>Complete</message>
  <servertime>1335611391</servertime>
</response>

Ответ при cmd= show_channel

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <list>
    <item>45</item>
    <item>139</item>
    <item>391</item>
</list>
  <servertime>1335611205</servertime>
</response>

Есть возможность получить весь список каналов с флагом скрытый <hide>1</hide> путем парамет- ра show=all и protect_code=<пароль> функции /channel_list

Набор функций для работы с EPG

Телевизионная программа передач (EPG) требует особого подхода к реализации и понимания происходящих процессов. Генерация EPG на стороне сервера достаточно трудоемкий процесс и сопряжен с опасностью перегрузки системы при неправильной реализации. Каждый разработчик желает чтобы его приложение максимально быстро отвечало требованиям пользователя, но эти требования не всегда оправданы. Мы рекомендуем разработчикам использовать механизм ке- ширования данных EPG на сколько это возможно. Время жизни cache в этом случае целесообразно будет устанавливать в 3 часа. Это оптимальное значение. Особого смысла загружать ВЕСЬ EPG нет, поскольку данные не всегда будут востребованы. Идеальным вариантом был бы механизм фоновой подгрузки EPG основанный на событии окончания телепрограммы. Другими словами, при окончении телепередачи следует загружать данные о следующей телепередачи (или о не- скольких). Для реализации этого меанизма была разработана функция /epg_current. Просьба обратить внимание на тот факт, что многие пользователи привыкли к так называемому сёрфингу каналов – простое перелистывание с канала на канал не особо вчитываясь в содержимое EPG. Или же путем «пробежки» по каналам выбирать нужный им канал. В этом случае не стоит немедленно подгружать EPG по событию перехода на канал, а выдержать паузу 0.6 секунды (значение было выявлено эмпирически).

Функция epg

Описание функции: получение программы передач для заданного канала на заданную дату.

Вызов:

/epg?cid=<идентификатор канала>&day=<дата формата DDMMYY>

Входные параметры для функции:

cid - Идентификатор канала, полученный из функции channel_list

day - Дата вида DDMMYY (Пример: 15 января 2014года = 150114)

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg> <item>
      <ut_start>UT_START</ut_start>
      <progname>PROG_NAME</progname>
    </item>
... </epg>
  <servertime>SERVER_TIME</servertime>
</response>

ut_start - Дата и время начала передачи в формате unixtime

progname - Название передачи

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg> <item>
      <ut_start>1277521800</ut_start>
      <progname>"Вся Россия".</progname>
    </item>
    <item>
      <ut_start>1277522700</ut_start>
      <progname>"Диалоги о животных".</progname>
</item>
... </epg>
  <servertime>1277809426</servertime>
</response>

Функция epg3

Описание функции: получение программы телепередач доступных каналов со времени, указанного в dtime на следующие period часов.

Вызов:

/epg3?dtime=<Дата и время старта EPG>&period=<на сколько часов вперед>

Необходима для организации функционала "сетки вещания", как на http://tvschedule.zap2it.com/tvlistings/ . Программа генерируется с учетом timeshift переменной, выставленной пользователем в настройках.

Входные параметры для функции:

dtime - дата и время (Unixtime) начала EPG. По умолчанию выбирается текущий момент (по серверному времени).

period - на сколько часов вперед. По умолчанию выдается EPG на ближайшие 3 часа.

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<item>
  <id>ID</id>
  <name>NAME</name>
  <epg>
       <item>
         <ut_start>UT_START</ut_start>
         <progname>PROGNAME</progname>
         <t_start>T_START</t_start>
       </item>
  </epg>
</item>
<servertime>SERVER_TIME</servertime>
</response>

id - ID канала

name - Название канала

ut_start -  Дата и время начала передачи в формате unixtime

progname - Название передачи

t_start - Время начала в виде ЧЧ:ММ

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<item>
  <id>2</id>
  <name>Первый</name>
  <epg>
       <item>
         <ut_start>1278944400</ut_start>
         <progname>"ХОЧУ ЗНАТЬ" с Михаилом Ширвиндтом</progname>
         <t_start>17:20</t_start>
       </item>
  </epg>
</item>
<servertime>1278944765</servertime>
</response>

Функция epg_next

Описание функции: возвращает EPG на текущее время и на 3 последующих телепередачи канала с заданным ID.

Вызов:

/epg_next?cid=<id канала>

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
  <item>
    <ts>TS</ts>
    <progname>PROGNAME </progname>
</item>
  </epg>
<servertime>SERVERTIME</servertime>
</response>

ts - Дата и время начала передачи в формате Unixtime

progname - Название передачи

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
  <item>
    <ts>1294834800</ts>
    <progname>ХОЧУ ЗНАТЬ
- с Михаилом Ширвиндтом</progname>
  </item>
    <item>
    <ts>1294840200</ts>
    <progname>ФЕДЕРАЛЬНЫЙ СУДЬЯ</progname>
  </item>
</epg>
<servertime>1294835324</servertime>
</response>

Функция epg_current

Описание функции: для вывода данных об текущем EPG нескольких каналов. Реализована для ди- намичной подрузки данных EPG. Содержит время начала и конца передачи. При установленном epg=3 Возвращает данные о трех следующих передачах начиная с текущей.

Вызов: /epg_current?cids=<id1,id3,id3>&epg=3

ВНИМАНИЕ! Идентификаторы каналов должны быть переданы через запятую.

Ответ функции:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
  <item>
    <cid>CID</cid>
    <epg>
      <epg_progname>EPG_PROGRAM </epg_progname>
      <epg_start>EPG_START</epg_start>
      <epg_end>EPG_STOP</epg_end>
    </epg>
  </item>
</epg>
<servertime>SERVERTIME</servertime>
</response>

cid - Идентификатор канала

epg_progname - Название передачи

epg_start - Дата и время начала передачи в формате unixtime

epg_end - Время окончания передачи в формате unixtime

Пример вызова: /epg_current?cids=2,5,7

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
  <item>
    <cid>2</cid>
    <epg>
      <epg_progname>"Вечерний Ургант".</epg_progname>
      <epg_start>1334863800</epg_start>
      <epg_end>1334865600</epg_end>
    </epg>
  </item>
</epg>
<servertime>1334864091</servertime>
</response>

При установленном параметре epg=3

<?xml version="1.0" encoding="UTF-8"?>
<response>
<epg>
  <item>
    <cid>2</cid>
    <epg>
      <item>
        <ts>1334863800</ts>
        <progname>"Вечерний Ургант".</progname>
      </item>
      <item>
        <ts>1334865600</ts>
        <progname>Ночные новости.</progname>
      </item>
      <item>
        <ts>1334866800</ts>
        <progname>"На ночь глядя".</progname>
      </item>
    </epg>
  </item>
  <item>
    <cid>5</cid>
    <epg>
      <item>
        <ts>1334858400</ts>
        <progname>Д/ф "Траектория судьбы".</progname>
      </item>
      <item>
        <ts>1334864400</ts>
        <progname>События. 25-й час.</progname>
      </item>
      <item>
        <ts>1334866500</ts>
        <progname>"Культурный обмен".</progname>
      </item>
    </epg>
  </item>
  <item>
    <cid>7</cid>
    <epg>
      <item>
        <ts>1334863800</ts>
        <progname>Х/ф "Стигматы".
Триллер. Мама Фрэнки прислала ей из Мексики распятие, после чего у девушки начали по-
являться стигматы - раны на запястьях, следы ударов плетью на спине. США, 1999. Режис-
сер: Руперт Уэйнрайт. В ролях: Патрисия Аркетт, Гэбриэл Бирн, Джонатан
Прайс.</progname>
</item>
     <item>
        <ts>1334870700</ts>
        <progname>Т/с "Живая мишень", 7 и 8 с.</progname>
      </item>
      <item>
        <ts>1334877000</ts>
        <progname>Т/с "Трюкачи", 3 и 4 с.</progname>
      </item>
    </epg>
  </item>
</epg>
<servertime>1334864162</servertime>
</response>

Работа с "Любимыми каналами"

Набор функций был введен для совместимости со старым механизмом «любымих каналов». Идея состояла в том, что клиент мог бы запрограммировать свой пульт на 12 горячих кнопок для быст- рого доступа к любимым каналам. Как показала практика, идея себя не оправдала, поскольку ее реализация относится в большей мере к клиентской части и информация об выбранных клиентом каналах должна храниться на клиентском оборудовании.

Функция favorites

Описание функции: вызов любимых каналов. Организовано хранение 12 любимых каналов. Каждая ячейка именуется индексом place. В ней содержится идентификатор канала.

Вызов без входных параметров возвращает список заданных «любимых» каналов:

/favorites

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<favorites>
  <item>
       <place>PLACE</place>
       <channel_id>CHANNEL_ID</channel_id>
</item>
  </favorites>
<servertime>SERVERTIME</servertime>
</response>

place - Номер ячейки

channel_id - Идентификатор канала

servertime - Время на сервере в формате unixtime

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<favorites>
  <item>
       <place>2</place>
       <channel_id>2</channel_id>
  </item>
  <item>
       <place>8</place>
       <channel_id>3</channel_id>
  </item>
</favorites>
<servertime>1278944963</servertime>
</response>

Функция favorites_set

Описание функции: устанавливает в заданную ячейку любимый канал. Если установить cid=0, то канал удалится из списка любимых.

Вызов:

/favorites_set?place=<номер ячейки для хранения>&cid=<идентификатор канала>

Входные параметры для функции:

place - Номер ячейки для хранения любимого канала

cid - Идентификатор канала, полученный из функции channel_list

Возвращает ответ вида:

(пакет сообщение об успешном выполнении либо пакет ошибки)

Функция settings

Описание функции: получение значения переменной настройки.

Вызов: 

/settings?var=<http_caching|stream_server|timeshift|timezone|bitrate>

Если у переменной настройки есть список возможных значений, то они передаются в массиве с параметром list.

Входные параметры для функции:

var - http_caching - время буферизации потока в миллисекундах

       stream_server - IP сервера трансляции. Возможные значения передаются в массиве List

       timeshift - смещение по времени. Возможные значения передаются в массиве List

       timezone - часовой пояс. Возможные значения от -12 до +12

       bitrate - Значение bitrate каналов. Возможные значения 1500 и 900. для некоторых типов device (см /login) могут быть указаны специфичные bitrate

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<settings>
  <name>timeshift</name>
  <value>3</value>
  <list>
       <item>0</item>
       <item>1</item>
       <item>2</item>
       <item>3</item>
       <item>4</item>
       <item>8</item>
       <item>9</item>
       <item>10</item>
       <item>11</item>
  </list>
</settings>
<servertime>1278946045</servertime>
</response>

Если у переменной настройки есть список возможных значений, то они передаются в массиве с параметром list.

Функция settings_set

Описание функции: установка значения переменной настройки.

Вызов:

/settings_set?var=<pcode|http_caching|stream_server|timeshift|timezone|bitrate>&val=<значение>

Входные параметры для функции:

var - pcode - установка пароля для закрытых каналов. Необходима передача дополнительных параметров: old_code - старый пароль, new_code - новый пароль, confirm_code - подтверждение нового пароля

       http_caching - Дополнительный параметр val передает возможное значение для установки

       stream_server - установить IP сервер трансляции. val передает возможное значение для установки

       timeshift - val передает возможное значение для установки.

       timezone - часовой пояс. Возможные значения от -12 до +12

       bitrate - Значание bitrate каналов. Возможные значения 1500 и 900. для некоторых типов device (см /login) могут быть указаны специфичные bitrate

Видеотека

«Видео по требованию» Video-on-demand (VOD). Возможность просмотра файлов в режиме online из каталога. Отдельный раздел для абонента, где представлен набор фильмов, разделенный по категориям, жанрам, рейтингам и т.п.

Функция vod_list

Описание функции: получение списка фильмов из базы видеотеки. Фильмы выводятся в порядке, заданном параметром type, списками по 20 фильмов.

Вызов:

/vod_list?type=<best|last|text>&page=<N>&query=<запрос>&genre=<id_жанра>&nums=<NN>

Входные параметры для функции:

type - best - лучшие фильмы согласно рейтинга по просмотрам; last - тот же список фильмов но отсортирован по дате добавления в обратном порядке; text - поиск в базе по названию фильма. Строка для поиска в query

page - Номер страницы списка. По умолчанию установлен 1-й номер страницы.

query - Строка для поиска. Работает, если установлен параметр type=text

genre - id - фильтр по жанрам. Показывает фильмы только указанного жанра. Возможно перечисление выводимых жанров через знак `|`. Например: genre=205|206|215

nums -  Количество фильмов на страницу. По умолчанию: 20

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<type>TYPE</type>
<total>TOTAL</total>
<count>COUNT</count>
<page>PAGE</page>
<rows>
  <item>
       <id>ID</id>
       <dt_modify>DT_MODIFY</dt_modify>
       <name>NAME </name>
       <name_orig>NAME_ORIG</name_orig>
       <description>DESCRIPTION</description>
       <poster>POSTER</poster>
       <year>YEAR</year>
       <rate_imdb>RATE_IMDB</rate_imdb>
       <rate_kinopoisk>RATE_KINOPOISK</rate_kinopoisk>
       <rate_mpaa>RATE_MPAA</rate_mpaa>
       <country>COUNTRY</country>
       <genre_str>детектив</genre_str>
</item> ...
<rows>
</response>

type - текущий тип запроса

total - всего записей, удовлетворяющих запросу

count -  количество на текущей странице

page - номер страницы

id -  идентификатор фильма (не файла для вещания!)

dt_modify - дата последней модификации (YYYY-MM-DD HH:MM:SS)

name -  название фильма

name_orig - оригинальное название фильма (если др.язык)

description -  описание фильма

poster - относительная ссылка на картинку постера. Относительно http://iptv.sunduk.tv/

year -  год выпуска фильма

rate_imdb - значение рейтинга IMDB

rate_kinopoisk - значение рейтинга kinopoisk.ru

rate_mpaa - значение рейтинга MPAA

country -  страна производства

genre_str - строка жанров (список жанров фильма собранный в строку и разделенные запятыми)

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<type>best</type>
<total>60</total>
<count>20</count>
<page>1</page>
<rows>
  <item>
       <id>119</id>
       <dt_modify>2010-12-24 14:35:18</dt_modify>
       <name>Убить Шакала </name>
       <name_orig></name_orig>
<description>Ограблен ювелирный магазин. Объявлен всесоюзный розыск бандита по кличке Шакал. А тем временем в поезде, следующем из Киева в Крым, происходит загадоч- ное убийство. Прибывший на место преступления следователь Петров обнаруживает связь между этим убийством и ограблением…</description>
       <poster>/img/vod/470616.jpg</poster>
ра. Относительно http://iptv.kartina.tv/]
       <year>1991</year>
       <rate_imdb>0.000</rate_imdb>
       <rate_kinopoisk>6.500</rate_kinopoisk>
       <rate_mpaa></rate_mpaa>
       <country>СССР</country>
       <genre_str>детектив</genre_str>
</item> ...
<rows>
</response>

Функция vod_info

Описание функции: получение полной информации о фильме.

Вызов:

/vod_info?id=<id фильма>&protect_code=<родительский пароль>

Входные параметры для функции:

id - идентификатор фильма, полученный из функции vod_list

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<film>
  <id>ID</id>
  <name>NAME</name>
  <name_orig>NAME_ORIG</name_orig>
  <description>DESCRIPTION</description>
  <poster>POSTER</poster>
  <length>LENGTH</length>
  <genre_str>GENRE_STR</genre_str>
  <year>YEAR</year>
  <director>DIRECTOR</director>
  <scenario>SCENARIO</scenario>
  <actors>ACTORS</actors>
 <rate_imdb>RATE_IMDB</rate_imdb>
 <rate_kinopoisk>RATE_KINOPOISK</rate_kinopoisk>
 <rate_mpaa>RATE_MPAA</rate_mpaa>
 <country>COUNTRY</country>
 <studio>STUDIO</studio>
 <awards>AWARDS</awards>
 <budget>BUDGET</budget>
 <images>IMAGES</images>
 <videos>
       <item>
         <id>ID</id>
         <title>TITLE</title>
         <format>DVD</format>
         <url>URL</url>
         <size>SIZE</size>
         <length>LENGTH</length>
         <codec>CODEC</codec>
         <width>WIDTH</width>
         <height>HEIGTH</height>
         <track1_codec>TRACK1_CODEC</track1_codec>
         <track1_lang>TRACK1_LANG</track1_lang>
         <track2_codec>TRACK2_CODEC</track2_codec>
         <track2_lang>TRACK2_LANG</track2_lang>
         <track3_codec>TRACK3_CODEC</track3_codec>
         <track4_lang>TRACK3_LANG</track3_lang>
       </item>
  </videos>
  <genres>
       <item>
<id>ID</id>
         <name>NAME</name>
       </item>
  </genres>
</film>
<servertime>SERVERTIME</servertime>
</response>

id - идентификатор фильма, полученный из функции vod_list

name -  название фильма

name_orig - оригинальное название фильма (если др.язык)

description -  описание фильма

poster - относительная ссылка на картинку постера. Относительно http://iptv.sunduk.tv/

length - длина фильма в минутах

genre_str -  жанры фильма, разделенные запятыми

year - год выпуска

director - режиссер

scenario - сценарист

actors -  в ролях

rate_imdb - значение рейтинга IMDB

rate_kinopoisk - значение рейтинга kinopoisk.ru

rate_mpaa - значение рейтинга MPAA

country -  страна производства

studio - студия

awards -  награды

budget - бюджет

images -  скриншоты (если есть)

password_protect - 1 или 0 закрыт или открыт контет по родительскому паролю. Устанавливается функцией /vod_manage

videos - файлы фильма (серии)

videos/item/id - идентификатор файла

title -  название серии. Если фильм односерийный, поле может быть не задано

format - качество. tv|dvd|hd|fullhd|etc

url - имя файла (справочное, не используется.)

size - размер файла

codec - кодек

width -  ширина картинки

height - высота картинки

track1_codec - аудио кодек дорожки 1

track1_lang - язык звукового трека 1

track2_codec -  аудио кодек дорожки 2

track2_lang - язык звукового трека 2

track3_codec - аудио кодек дорожки 3

track4_lang - язык звукового трека 3

genres -   массив жанров фильма

genres/id - идентификатор жанра

genres/name - наименование жанра

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<film>
  <id>119</id>
  <name>Убить Шакала </name>
  <name_orig></name_orig>
<description>Ограблен ювелирный магазин. Объявлен всесоюзный розыск бандита по клич- ке Шакал. А тем временем в поезде, следующем из Киева в Крым, происходит загадочное убийство. Прибывший на место преступления следователь Петров обнаруживает связь между этим убийством и ограблением…</description>
  <poster>/img/vod/470616.jpg</poster>
  <length>73</length>
  <genre_str>детектив</genre_str>
  <year>1991</year>
  <director>Григорий Кохан</director>
  <scenario>Николай Оганесов, Григорий Кохан</scenario>
  <actors>Евгений Жариков, Олег Масленников, Нина Колчина-Бунь,  Давид Бабаев, Римас
Моркунас, Евгений Смирнов, Вячеслав Езепов,  Бимболат Ватаев, Александр Быструшкин,
Степан Олексенко</actors>
  <rate_imdb>0.000</rate_imdb>
  <rate_kinopoisk>6.500</rate_kinopoisk>
  <rate_mpaa></rate_mpaa>
  <country>СССР</country>
  <studio></studio>
  <awards></awards>
  <budget>0</budget>
  <images></images>
  <videos>
       <item>
         <id>161</id>
         <title></title>
         <format>dvd</format>
         <url>KILL_JACKAL.m4v</url>
         <size>0</size>
         <lenght>0</lenght>
         <codec>h264</codec>
         <width>0</width>
         <height>0</height>
         <track1_codec>aac</track1_codec>
         <track1_lang></track1_lang>
         <track2_codec></track2_codec>
         <track2_lang></track2_lang>
         <track3_codec></track3_codec>
         <track3_lang></track3_lang>
       </item>
  </videos>
  <genres>
       <item>
        <id>209</id>
         <name>детектив</name>
       </item>
  </genres>
</film>
<servertime>1294761468</servertime>
</response>

Функция vod_geturl

Описание функции: получение ссылки для вещания потока видео.

Вызов:

/vod_geturl?fileid=<ид файла>&protect_code=<родительский пароль>

Входные параметры для функции:

fileid - идентификатор файла, полученный из функции vod_info

protect_code - родительский пароль. Используется только для контента с пометкой <password_protect>

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<url>http://vod.kartina.tv/Tass_02.m4v?ticket=mkcuTmdjrxyJAOE5Nb6EZNxeNin3IDojbkF0...W
QlzY4CMP%2F5%2BIr8Y%3D :http-caching=1500 :no-http-reconnect</url>
<servertime>1294826729</servertime>
</response>

Функция vod_genres

Описание функции: возвращает список жанров.

Вызов без параметров:

/vod_genres

Внимание! Не рекомендуется делать статичную копию справочника, поскольку жанры могут изменяться и появляться по мере поступления новых фильмов.

Возвращает ответ вида:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<genres>
  <item>
       <id>ID</id>
       <name>NAME</name>
  </item>
...
<item>
<id>ID</id>
       <name>NAME</name>
  </item>
</genres>
<servertime>SERVERTIME</servertime>
</response>

id - id жанра

name - наименование жанра

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<genres>
  <item>
       <id>205</id>
       <name>биографический</name>
  </item>
...
<item>
       <id>234</id>
       <name>фэнтези</name>
  </item>
</genres>
<servertime>1294827021</servertime>
</response>

Функция vod_favlist

Описание функции: выводит список отобранных любимых фильмов

Вызов без параметров:

/vod_favlist

Формат ответа идентичен формату списка /vod_list

Функция vod_favadd

Описание функции: добавление фильма с идентификатором id в список любимых фильмов.

Вызов:

/vod_favadd?id=<ID фильма>

Функция vod_favsub

Описание функции: удаление фильма с идентификатором id из списка любимых фильмов.

Вызов:

/vod_favsub?id=<ID фильма>

Режимы видеотеки

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

blood - Контент, содержащий жестокие кровавые сцены

violence - Жестокие сцены насилия

obscene -  Грубые нецензурные выражения

porn - Порнография и откровенные сцены

horror - Ужасы

Каждый из рейтингов для каждого абонента может быть состояниях: доступным (show), скрытом (hide), доступным по паролю (pass).

По умолчанию установлены следующие параметры рейтинга: blood=show, violence=show, obscene=show, porn=hide, horror=hide.

Функция vod_manage

Описание функции: родительский контроль над категориями фильмов.

Вызов:

/vod_manage?cmd=<get_rates|set_user_rates>&protect_code=<родительский пароль>

cmd - команда механизма контроля контента. get_rates – получить список установленных для абонента значений. set_user_rates – установить абоненту значения.

protect_code - пароль закрытых каналов. Обязательный параметр.

При следующем вызове: /vod_manage?cmd=get_rates возвращается следующий массив:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>
  <item>
    <id_rate>ID_RATE</id_rate>
    <rate_name>RATE_NAME</rate_name>
    <action>pass</action>
</item>
  ...
</result>
<servertime>1330354248</servertime>
</response>

id_rate - id категории

rate_name - наименование категории

action - Установленное действие show | hide | pass

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>
  <item>
    <id_rate>1</id_rate>
    <rate_name>blood</rate_name>  [кровавые сцены]
    <action>pass</action>
  </item>
  <item>
    <id_rate>2</id_rate>
    <rate_name>violence</rate_name>  [насилие]
    <action>pass</action>
  </item>
  <item>
    <id_rate>3</id_rate>
    <rate_name>obsence</rate_name>  [маты, нецензурщина и пахабщина]
    <action>pass</action>
  </item>
  <item>
    <id_rate>4</id_rate>
    <rate_name>porn</rate_name>  [порно]
    <action>hide</action>
  </item>
</result>
<servertime>1330354248</servertime>
</response>

Установка настроек в функции vod_manage: cmd=set_user_rates

/vod_manage?cmd=set_user_rates&<blood|violence|obsence|porn|horror>=<show|pass|hide>&prot ect_code=

Устанавливает режимы отображения контента по настройкам рейтинга.

Можно передать одновременно несколько параметров. Например:

/vod_manage?cmd=set_user_rates

      &blood=pass
      &violence=hide
      &obsence=show
      &porn=pass
      &protect_code=<code>

0 - Unknown error - Неизвестная ошибка 1 - Incorrect request - Неверный запрос