Engine API

Обмен данными с 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