Difference between revisions of "Engine API"

Revision as of 18:29, 8 February 2013

Обмен данными с TS Engine происходит по протоколу TCP.

По умолчанию TS Engine принимает входящие соединения на порт 62062.

Общий вид команд

Каждая команда должна состоять из строки, завершающейся разделителем \r\n

Большинство команд имеют такой вид:

CMD [param1] [param2] ...

где

CMD - предопределенное название команды

param1, param2 ... - параметры команды, разделенные пробелом

Типы команд

Все команды делятся на входящие и исходящие.

Входящие команды отправляются от клиента к TS Engine. Клиентом является любое программное обеспечение, которое использует функционал TS Engine. С помощью входящих команд клиент управляет работой TS Engine.

Исходящие команды отправляются от TS Engine к клиенту. Данный тип команд используется для информирования клиента о работе TS Engine.

Синхронные команды

Большинство входящих команд выполняются асинхронно, т.е. для таких команд нет понятия "ответ на команду".

Примеры асинхронных команд:

- клиент отправляет LOADASYNC, после загрузки содержимого TS Engine отправляет LOADRESP через некоторое время

- клиент отправляет START, после окончания пребуферизации TS Engine отправляет PLAY

Но есть также команды, которые выполняются синхронно, в режиме "запрос-ответ". На данный момент таких команд две: LOAD и GETPID.

Синхронная команда предполагает ответ, который отправляется от TS Engine к клиенту в виде строки, начинающейся на ##.

Обработка синхронных команд со стороны клиента должна выглядеть таким образом:

- клиент отправляет команду, например "GETPID qwerty 0 0 0" и ждет, пока от TS Engine придет ответ

- если от TS Engine получено сообщение, которое начинается на ##, то данное сообщение считается ответом на синхронную команду (например, ##12345)

Входящие команды

HELLOBG

Используется в рамках процедуры "рукопожатия" между клиентом и TS Engine.

Эта команда должна быть отправлена клиентом сразу после установления tcp-соединения с TS Engine.

Соединение с TS Engine считается успешным после того, как клиент получил от TS Engine ответ на "рукопожатие" - команду HELLOTS

READY

Информирует TS Engine о том, что клиент готов принимать исходящие команды

LOAD TORRENT <torrent_url> <developer_id> <affiliate_id> <zone_id>

LOAD INFOHASH <torrent_infohash> <developer_id> <affiliate_id> <zone_id>

LOAD PID <player_id>

LOAD RAW <torrent_data> <developer_id> <affiliate_id> <zone_id>

LOADASYNC <request_id> TORRENT <torrent_url> <developer_id> <affiliate_id> <zone_id>

LOADASYNC <request_id> INFOHASH <torrent_infohash> <developer_id> <affiliate_id> <zone_id>

LOADASYNC <request_id> PID <player_id>

LOADASYNC <request_id> RAW <torrent_data> <developer_id> <affiliate_id> <zone_id>

Данные команды выполняют загрузку содержимого торрент-файла и используются для того, чтобы клиент мог получить список названий файлов в интересующем торрент-файле. Команды LOAD выполняются синхронно, команды LOADASYNC - асинхронно (ответ приходит в исходящей команде LOADRESP).

Более предпочтительным методом является асинхронная загрузка.

Параметры:

request_id - случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOAD точно знал, на какой из этих запросов получен ответ

torrent_url - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)

torrent_infohash - infohash торрента

player_id - код плеера

torrent_data - содержимое торрент-файла в кодировке base64

developer_id - код разработчика (если неизвестно, необходимо передавать 0)

affiliate_id - код партнера (если неизвестно, необходимо передавать 0)

zone_id - код зоны партнера (если неизвестно, необходимо передавать 0)

START TORRENT <torrent_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>

START INFOHASH <torrent_infohash> <file_indexes> <developer_id> <affiliate_id> <zone_id>

START PID <player_id> <file_indexes>

START RAW <torrent_data> <file_indexes> <developer_id> <affiliate_id> <zone_id>

START URL <direct_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>)

Данные команды используются для начала загрузки определенного файла из торрент-файла либо для начала загрузки файла по прямой ссылке (START URL)

Параметры:

file_indexes - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов, который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.

Если в торренте пять видео-файлов и необходимо начать проигрывание первого, но при это загружать остальные, то отправляется 0,1,2,3,4.

Если нужно проиграть третий файл, и не загружать другие, отправляется 2.

torrent_url - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)

torrent_infohash - infohash торрента

player_id - код плеера

torrent_data - содержимое торрент-файла в кодировке base64

direct_url - прямая ссылка на файл (например, http://somesite.com/files/video.mp4)

developer_id - код разработчика (если неизвестно, необходимо передавать 0)

affiliate_id - код партнера (если неизвестно, необходимо передавать 0)

zone_id - код зоны партнера (если неизвестно, необходимо передавать 0)

GETPID <infohash> <developer_id> <affiliate_id> <zone_id>

Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен

SHUTDOWN

Закрыть соединение с клиентом.

STOP

Остановить загрузку файла, который загружается в данный момент.

DUR <video_url> <duration>

Сообщить TS Engine о длительности видео-файла, который в данный момент проигрывается клиентом. Данная команда должна отправлять сразу после того, как клиент определил длительность контента.

Параметры:

video_url - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации

duration - длительность в миллисекундах

PLAYBACK <video_url> <event>

Сообщить TS Engine о процентном соотношении проигранного видео

Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному видео происходит только после того, как TS Engine получил команду PLAYBACK 100 (т.е. после того, как клиент полность проиграл рекламный ролик)

Параметры:

video_url - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации

event - одно из данных событий:

0 - начало проигрывания

25 - проиграно 25% видео

50 - проиграно 50% видео

75 - проиграно 75% видео

100 - проиграно 100% видео

Исходящие команды

HELLOTS

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

AUTH <auth_level>

Уровень доступа пользователя

auth_level - целое число - уровень доступа

На данный момент возможны два значения уровня доступа:

0 - пользователю не доступны расширенные функции (перемотка и проигрывание файлов из торрента с несколькими видео-файлами)

1 - пользователю доступны расширенные функции

STATE <state_id>

Информация о текущем статусе TS Engine

SHUTDOWN

TS Engine завершил работу

PLAY <video_url>

PLAYAD <video_url>

PLAYADI <video_url>

Начать проигрывание видео по ссылке video_url (данная ссылка ведет на http-сервер, встроенный в TS Engine).

PLAY - проигрывание основного видео

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

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

PAUSE

TS Engine начал буферизацию, так как недостаточно данных для проигрывания видео без остановки

RESUME

TS Engine завершил буферизацию

LOADRESP <request_id> <response>

Ответ на команду LOAD

request_id - идентификатор запроса

response - список файлов в формате json в такого вида:

{
 "status": 1,
 "infohash": "abcd1234",
 "files": [
   ["file1.mp4", 0],
   ["file2.avi", 1],
   ["file3.mkv", 5]
 ]
}

status - 0: в торренте нет видео файлов, 1 - в торренте один видео файл, 2 - в торренте более одного видео файла

infohash - infohash торрента

files - список файлов; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция файла в торренте (эта позиция должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько).

Имена файлов передаются в кодировке UTF-8 в urlencoded виде.

INFO <message_id>;<message_text>

Информационное сообщение

message_id - код сообщения

message_text - текст сообщения

STATUS <status_string>

Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента

status_string - строка описанного ниже формата

Если идет проигрывание основного контента

STATUS main:status_string

Если идет проигрывание рекламного ролика:

STATUS main:status_string|ad:status_string

status_string:

TS Engine ничего не делает - idle

ошибка - err;error_id;error_message (код и описание)

проверка - check;progress

пребуферизация - prebuf;progress;time

закачка - dl

буферизация - buf;progress;time

ожидание достаточной скорости - wait;time

Ко всем status_string (кроме idle, err, check) добавляются общие данные:

total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded

total_progress - сколько всего закачано по данному файлу

immediate_progress - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке)

Все числа передаются как integer.

Все progress принимают значение от 0 до 100.

Примеры:

STATUS main:prebuf;45;30|ad:buf;69
STATUS main:dl|ad:dl

Пример трансформация статусов в текстовые сообщения, понятные пользователю:

check - Checking xx%
prebuf - Prebuffering xx%
buf - Buffering xx%
wait - Waiting sufficient download speed
err - выводим сообщение об ошибке
dl, idle - ничего не выводим

События

EVENT event_name param1_name=param1_value param2_name=param2_value ...

Параметры не обязательны.

Значения параметров - urlencoded utf-8

Примеры

>> - сообщения от клиента к TS Engine

<< - сообщения от TS Engine к клиенту

1) Проигрывание торрент-файла по ссылке без рекламных роликов (необходимость проигрывания рекламных роликов определяет TS Engine).

Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.

Торрент файл содержит один видео-файл.

рукопожатие

>>HELLOBG
<<HELLOTS

клиент готов принимать сообщения

>>READY

пользователю доступны расширенные функции

<<AUTH 1

загрузить торрент по ссылке

>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": [["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]], "infohash":  
"4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}

узнать код плеера (например, чтобы показать его пользователю)

>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195

начать пребуферизацию видео

>>START TORRENT http://rutor.org/download/67346 0 0 0 0

идет процесс пребуферизации

<<STATE 1
<<STATUS main:prebuf;0;2147483447;0;0;0;0;0;0;0;0;0;0
<<STATUS main:prebuf;0;2132;0;0;29;0;0;8;0;131072;0;0
<<STATUS main:prebuf;8;942;0;0;60;0;0;9;0;393216;0;0
<<STATUS main:prebuf;50;591;0;0;87;0;0;8;0;835584;0;0
<<STATUS main:prebuf;75;497;0;0;98;0;0;8;0;1146880;0;0
<<STATUS main:prebuf;91;448;0;0;105;0;0;8;0;1441792;0;0

пребуферизация завершена, клиент получает ссылку для проигрывания контента

<<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2

клиент отправляет длительность контента (~201 секунда)

>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964

клиент информирует о том, что началось проигрывание

>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0

TS Engine загружает контент

<<STATUS main:dl;0;0;110;0;0;8;0;1622016;0;0
<<STATUS main:dl;0;0;128;0;0;8;0;2965504;0;0
<<STATUS main:dl;0;0;130;0;0;8;0;3129344;0;0

TS Engine недостаточно данных для проигрывания, начинает буферизация

<<PAUSE
<<STATE 3
<<STATUS main:buf;0;315;0;0;130;0;0;8;0;3260416;0;0
<<STATUS main:buf;90;299;0;0;133;0;0;8;0;3866624;0;0
<<STATUS main:buf;90;278;0;0;138;0;0;8;0;4390912;0;0

буферизация завершена

<<RESUME
<<STATE 2
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0

клиент проиграл 25% контента

>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 25
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0
<<STATUS main:dl;0;0;146;0;0;7;0;8388608;0;0

клиент проиграл 50% контента

>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 50
<<STATUS main:dl;0;0;145;0;0;7;0;9404416;0;0

клиент проиграл 75% контента

>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 75
<<STATUS main:dl;0;0;146;0;0;7;0;9568256;0;0

остановить загрузку контента

>>STOP
<<STATE 0

разорвать соединение

>>SHUTDOWN
<<SHUTDOWN

Общие понятия

ACE Stream Engine (далее - "движок") - приложение, которое обеспечивает весь функционал системы ACE Stream. Данное приложение работает в фоновом режиме и имеет минимальный графический интерфейс для

изменения различных настроек.

ACE Stream Engine API (далее - API) - программный интерфейс, позволяющий сторонним приложениям работать с движком. Под сторонними приложениями, как правило, подразумеваются медиа плееры, работающе

с системой ACE Stream.

Клиент - стороннее приложение, которое работает с движком посредством API.

Схема работы API

Обмен данными с движком происходит по протоколу TCP. Общая схема работы выглядит так:

клиент устанавливает TCP-соединение с движком
клиент и движок обмениваются рукопожатиями
клиент и движок обмениваются сообщениями
одна из сторон завершает соединение

Установление соединения

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

На Linux используется фиксированный порт: 62062

На Windows используется динамический порт. Движок после запуска создает файл acestream.port в директории, в которой находится сам движок (файл tsengine.exe), и записывает в данный файл порт, на

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

движок, можно считать из реестра:

HKEY_CURRENT_USER\Software\TorrentStream\EnginePath

Ключ EnginePath содержит абсолютный путь к исполняемому файлу движка (tsengine.exe). По умолчанию это %APPDATA%\TorrentStream\engine\tsengine.exe

Алгоритм установления соединения (Windows):

считать из реестра ключ HKEY_CURRENT_USER\Software\TorrentStream\EnginePath
1. если ключ отсутствует - движок не установлен
2. запомнить путь к исполняемому файлу движка (engine_path) и директории движка (engine_dir)
считать содержимое файла engine_dir/acestream.port и запомнить порт
если данный файл отсутствует - запустить движок, дождаться создания файла acestream.port и считать его содержимое
установить TCP-соединение на localhost на указанный порт
если не получилось установить соединение - движок не запущен и его нужно запустить
обменяться рукопожатием и начать обмен сообщениями

Алгоритм установления соединения (Linux):

установить TCP-соединение на localhost на порт 62062
если не получилось установить соединение - движок не запущен и его нужно запустить (/usr/bin/acestreamengine-client-gtk)
обменяться рукопожатием и начать обмен сообщениями

Рукопожатие

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

клиент отсылает сообщение

HELLOBG version=<api_version>

движок отсылает в ответ

HELLOTS version=<engine_version>

Каждое сообщение должна завершаться символами перевода строки CRLF (\r\n)

<api_version>: версия API, которую поддерживает клиент. Этот параметр служит для поддержки обратной совместимости новых версий движка со старыми клиентами. Текущая версия API - 3. Если клиент не указал версию,

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

<engine_version>: версия движка (например, 2.0.8)

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

Обмен сообщениями

Каждое сообщение представляет собой ASCII-строку, которая завершается символами перевода строки CRLF (\r\n)

Примерный алгоритм приема сообщений выглядит таким образом:

клиент в цикле ждет поступления данных по TCP-соединению
при получении данных они добавляются в буфер
клиент проверяет, есть ли в буфере символы CRLF. Если есть, то из буфера вырезается сообщение (строка от начала буфера до символов CRLF) и отправляется в обработчик сообщений
клиент должен учитывать возможность получения нескольких сообщений одновременно (т.е. повторять предыдущий шаг, пока в буфере не будет символов CRLF)

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

То же самое должен делаь клиент при закрытии - перед закрытием отослать движку команду SHUTDOWN

Сообщения

Типы сообщений

Все сообщения условно делятся на две группы: команды и события.

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

События носят информационный характер. Например, событие STATUS информирует клиента о статусе загрузки (идет ли в данный момент пребуферизация, буферизация, какая скорость загрузки и т.д.)

Синхронные команды

Практически все команды являются асинхронными, т.е. не предполагают наличие ответа от другой стороны.

Исключением являются две команды:

LOAD (сихронная загрузка информации о потоке)
GETCID (получение Content ID для потока)

Для этих команд есть понятие ответа на команду. Ответ передается в виде строки, которая начинается на ##.

Алгоритм обработки синхронных команд такой:

клиент отправляет движку синхронную команду (например, GETCID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0) и ждет данных от движка
когда от движка приходят данные, клиент проверяет, начинается ли полученный ответ на ## (например, ##36ae4c89ab45b4010b1461c513da38d007356195)
если это так, то строка от символов ## до CRLF является ответом на синхронную команду (причем ответ может быть пустой, т.е. выглядеть так: ##)
если нет, значит ответ на команду не может быть получен

Мы не рекомендуем использовать синхронную команду LOAD, так как она подразумевает блокирование потока на стороне клиента. Эта команда является устаревшей и вместо нее следует использовать

асинхронную версию LOADASYNC

Ответ на команду GETCID приходит практически мгновенно, поэтому ее использование не приводит к блокированию. Однако есть одно замечание по использованию данной команды:

Команду GETCID не следует отправлять, если движок находится в состоянии starting

Список сообщений

В примерах сообщения от клиента к движку отмечены >>, от движка к клиенту - <<

Команды от клиента к движку

`READY`

Версия API: >= 1

Описание: Информирует движок о том, что клиент готов принимать команды. Это должна быть первая команда после рукопожатия.

Синтаксис

READY

Параметры: нет

Пример

>>READY

`LOADASYNC`

Версия API: >= 1

Описание: Получить описание контента по идентификатору. Идентификатором может быть content id, ссылка на транспортный файл (.torrent, .acelive), инфохеш транспортного файла и т.п. Описание представляет

собой список названий файлов либо потоков, которые содержатся в транспортном файле. Основное назначение этой команды - возможность сформировать и показать пользователю плейлист.

Синтаксис

LOADASYNC request_id TORRENT url developer_id affiliate_id zone_id
LOADASYNC request_id INFOHASH infohash developer_id affiliate_id zone_id
LOADASYNC request_id RAW data developer_id affiliate_id zone_id
LOADASYNC request_id PID content_id

Параметры

request_id: случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный

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

url: ссылка на транспортный файл
infohash: инфохеш транспортного файла
data: содержимое транспортного файла в кодировке base64
content_id: идентификатор контента в системе ACE Stream (Content ID)
developer_id: код разработчика (если неизвестно, необходимо передавать 0)
affiliate_id: код партнера (если неизвестно, необходимо передавать 0)
zone_id: код зоны партнера (если неизвестно, необходимо передавать 0)

Формат ответа: Ответ приходит в формате JSON со следующими полями:

status:
- 0 - транспортный файл не содержит аудио/видео файлов
- 1 - транспортный файл содержит один аудио/видео файл
- 2 - транспортный файл содержит более одного аудио/видео файла
- 100 - ошибка получения данных
files: список файлов/потоков; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция в транспортном файле (эта позиция

должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько)

infohash: инфохеш транспортного файла
checksum: хешсумма транспортного файла

Параметры infohash и checksum клиенту нужны для того, чтобы в дальнейшем получить Content ID с помощью команды GETCID

Названия файлов возвращаются в виде urlencoded строк в кодировке UTF-8

Пример

>>LOADASYNC 12345 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 12345 {"status": 1, "files": [["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]], "infohash": "4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}

`START`

Версия API: >= 1

Описание: Начать проигрывание указанного контента

Синтаксис

START TORRENT url file_indexes developer_id affiliate_id zone_id stream_id
START INFOHASH <infohash> <file_indexes> <developer_id> <affiliate_id> <zone_id>
START PID <content_id> <file_indexes>
START RAW  <file_indexes> <developer_id> <affiliate_id> <zone_id>
START URL direct_url <file_indexes> <developer_id> <affiliate_id> <zone_id>
START EFILE efile_url

Параметры

url: ссылка на транспортный файл
infohash: инфохеш транспортного файла
content_id: идентификатор контента в системе ACE Stream (Content ID)
data: содержимое транспортного файла в кодировке base64
direct_url: прямая http-ссылка на контент (для проигрывания без транспортного файла)
efile_url: ссылка на .acemedia файл
file_indexes: список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с

нуля и соответствуют списку файлов, который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.

developer_id:
affiliate_id:
zone_id:
stream_id:

Если необходимо в параметрах передать ссылку на файл, который находится в локальной файловой системе, следует использовать формат file:///path/to/file.

Примеры

>>START TORRENT http://rutor.org/download/67346 0 0 0 0
START PID xxxxxx 0
START EFILE file:///c:\acestream\test.acemedia

`STOP`

Версия API: >= 1

Описание: Остановить воспроизведение и загрузку

Синтаксис

STOP

Параметры: нет

Пример

>>STOP

`GETPID`

Версия API: 1

Эта команда устарела и больше не используется. Вместо нее следует использовать команду GETCID

`GETCID`

Версия API: >= 2

Описание: Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен

Синтаксис

GETCID checksum=checksum infohash=infohash developer=developer_id affiliate=affiliate_id zone=zone_id

Параметры

checksum: хешсумма транспортного файла (значение клиент из команды LOADRESP)
infohash: инфохеш транспортного файла (значение клиент из команды LOADRESP)
developer_id: код разработчика (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)
affiliate_id: код партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)
zone_id: код зоны партнера (если неизвестно, необходимо передавать 0 либо не передавать данный параметр)

Пример

>>GETCID checksum=xxxxx infohash=xxxxx
<<##xxxxxxxxx

`GETADURL`

Описание скоро будет

`USERDATA`

Описание скоро будет

`SAVE`

Описание скоро будет

`LIVESEEK`

Описание скоро будет

`SHUTDOWN`

Версия API: >= 1

Описание: Клиент завершил работу

Синтаксис

SHUTDOWN

Параметры: нет

Пример

>>SHUTDOWN

Команды от движка к клиенту

`PLAY, PLAYAD, PLAYADI`

Версия API: 1

Эти команды устарела и больше не используется. Вместо них следует использовать команду START

`START`

Версия API: >= 2

Описание: Начать прогрывание контента. Эта команда отправляется после завершения пребуферизации. Движок отсылает плееру http-ссылку, по которой плеер может начать проигрывание контента. Данная ссылка

обрабатывается http-серверов, встроенным в движок.

Синтаксис

START url [ad=1 [interruptible=1]] [pos=position]

Параметры

url: ссылка для проигрывания
ad=1: флаг, указывающий на то, что ссылка url ведет на рекламный видеоролик, который клиент должен проиграть перед началом воспроизведения основного контента
interruptible=1: флаг, указывающий на то, что должен проиграться прерываемый рекламный ролик
position: целое число от 0 до 100, которое указывает с какой позиции клиент должен начать проигрывание (например, position=50 означает, что клиент должен начать проигрывание с

позиции 50%, т.е. с середины контента)

Пример

<<START http://127.0.0.1:6878/content/xxxx
<<START http://127.0.0.1:6878/content/xxxx ad=1
<<START http://127.0.0.1:6878/content/xxxx ad=1 interruptible=1
<<START http://127.0.0.1:6878/content/xxxx pos=0

`PAUSE`

Версия API: >= 1

Описание: Движок начал буферизацию, клиент по возможности должен остановиться на паузу до получения команды RESUME

Синтаксис

PAUSE

Параметры: нет

Пример

<<PAUSE

`RESUME`

Версия API: >= 1

Описание: Движок завершил буферизацию, клиент может продолжить воспроизведение.

Синтаксис

RESUME

Параметры: нет

Пример

<<RESUME

`STOP`

Версия API: >= 1

Описание: Клиент должен остановить воспроизведение контента

Синтаксис

STOP

Параметры: нет

Пример

<<STOP

`SHUTDOWN`

Версия API: >= 1

Описание: Движок завершил работу

Синтаксис

SHUTDOWN

Параметры: нет

Пример

<<SHUTDOWN

События от клиента к движку

`DUR`

Версия API: >= 1

Описание: Сообщить движку о длительности контента, который в данный момент проигрывается клиентом. Данная команда должна отправлять сразу после того, как клиент определил длительность контента.

Синтаксис

DUR video_url duration

Параметры

video_url: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде START
duration: длительность в миллисекундах

Пример

Клиент определить длительность контента: 3780 секунд:
>>DUR http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 3780000

`PLAYBACK`

Версия API: >= 1

Описание: Сообщить движку о прогрессе проигранного контента (сколько процентов проигралось).; Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному контенту происходит только после того, как движок получил команду PLAYBACK 100 (т.е. после того, как

клиент полность проиграл рекламный ролик)

Синтаксис

PLAYBACK video_url event

Параметры

video_url: ссылка на видео, которая была отправлена клиенту после окончания пребуферизации в команде START
event: одно из указанных событий:
- 0: начало проигрывания
- 25: проиграно 25% видео
- 50: проиграно 50% видео
- 75: проиграно 75% видео
- 100: проиграно 100% видео (воспроизведение завершено)

Пример

>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 0
>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 25
>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 50
>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 75
>>PLAYBACK http://127.0.0.1:6878/content/5b5ba8c462f4014d8b57377c97d2e13caee52cdd/0.685119063624 100

`EVENT`

События от движка к клиенту

`STATE`

Версия API: >= 1

Описание: Информация о текущем статусе TS Engine

Синтаксис

STATE 'state_id'

Параметры

state_id: состояние движка:
- 0
- 1
- 2

Пример

<<STATE 0

`STATUS`

Версия API: >= 1

Описание: Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента

Синтаксис

STATUS main:status_string
STATUS main:status_string|ad:status_string

Параметры: нет

Пример

<<STATUS main:prebuf;45;30|ad:buf;69
<<STATUS main:dl|ad:dl

`AUTH`

Версия API: >= 1

Описание: Уровень доступа пользователя

Синтаксис

AUTH user_auth_level

Параметры

user_auth_level: уровень доступа пользователя

Пример

Пользователь не зарегистрирован:
<<AUTH 0

Пользователь зарегистрирован:
<<AUTH 1

`EVENT`

Описание скоро будет

@@ Line 701: / Line 701: @@
   <tt><nowiki>>>STOP</nowiki></tt>
-----
 =====<tt style="color: #009;">GETPID</tt>=====
 ;Версия API

Difference between revisions of "Engine API"

Revision as of 18:29, 8 February 2013

Contents

Общий вид команд

Типы команд

Синхронные команды

Входящие команды

Исходящие команды

События

Примеры

Общие понятия

Схема работы API

Установление соединения

Рукопожатие

Обмен сообщениями

Сообщения

Типы сообщений

Синхронные команды

Список сообщений

Команды от клиента к движку

READY

LOADASYNC

START

STOP

GETPID

GETCID

GETADURL

USERDATA

SAVE

LIVESEEK

SHUTDOWN

Команды от движка к клиенту

PLAY, PLAYAD, PLAYADI

START

PAUSE

RESUME

STOP

SHUTDOWN

События от клиента к движку

DUR

PLAYBACK

EVENT

События от движка к клиенту

STATE

STATUS

AUTH

EVENT

Navigation menu

Search

`READY`

`LOADASYNC`

`START`

`STOP`

`GETPID`

`GETCID`

`GETADURL`

`USERDATA`

`SAVE`

`LIVESEEK`

`SHUTDOWN`

`PLAY, PLAYAD, PLAYADI`

`START`

`PAUSE`

`RESUME`

`STOP`

`SHUTDOWN`

`DUR`

`PLAYBACK`

`EVENT`

`STATE`

`STATUS`

`AUTH`

`EVENT`