Engine API/en

Data exchange with TS Engine happens via TCP protocol.

By default TS Engine accepts incoming connections in port 62062.

General form of commands

Each command must consist of a string terminated by a separator \r\n

Most of commands have such form:

CMD [param1] [param2] ...

where

CMD - predefined command name

param1, param2 ... - command's parameters, separated by a space

Commands' types

All commands are divided into incoming and outgoing.

Incoming commands are sent from a client to TS Engine. Client is any software that uses TS Engine functions. Using incoming commands the client controls TS Engine.

Outgoing commends are sent from TS Engine to the client. This type of commands is used to inform the client about work of TS Engine.

Synchronous commands

Most of incoming commands are performed asynchronously, ie. for these commands there is no such thing as "response to command".

Examples of asynchronous commands:

- client sends LOADASYNC, after loading content TS Engine sends LOADRESP after a while

- client sends START, after the end of pre-buffering TS Engine sends PLAY

But there are also commands that are performed synchronously, in "request-response" mode. At the moment, there are two such commands: LOAD and GETPID.

Synchronous command assumes the response, sent from TS Engine to the client as a string, starting with ##.

Processing of synchronous commands from client's side should look like this:

- client sends a command (for example, "GETPID qwerty 0 0 0") and waits for response from TS Engine

- if a message starting with ## is received from TS Engine, this message is considered as response to synchronous command (for example, ##12345)

Incoming commands

HELLOBG

Used as a part of "handshake" procedure between client and TS Engine.

This command must be sent by client right after establishing tcp-connection with TS Engine.

Connection with TS Engine is successful, if client receives from TS Engine response to "handshake" - command HELLOTS

READY

Informs TS Engine that client is ready to receive outgoing commands

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>

These commands perform loading torrent-file's content. They are used to allow client to get a list of files' names in file of interest. LOAD commands are performed synchronously, LOADASYNC commands - asynchronously (response comes in outgoing command LOADRESP).

Preferred method is asynchronous loading.

Parameters:

request_id - random integer - identifier of LOADASYNC request; this identifier will be sent to client in LOADRESP command after a list of files will be received; this id serves to ensure that client in case of sending multiple LOAD requests knew exactly which of these requests is answered

torrent_url - link to torrent file (for example, http://sometracker.com/torrent/12345)

torrent_infohash - torrent's infohash

player_id - player's code

torrent_data - torrent-file's content, encoded in base64

developer_id - developer's code (if unknown, 0 must be sent)

affiliate_id - partner's code (if unknown, 0 must be sent)

zone_id - code of partner's zone (if unknown, 0 must be sent)

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>)

These commands are used to start loading a specific file from torrent or by direct link (START URL)

Parameters:

file_indexes - a list of file's indexes from torrent file, which have to be loaded. Client receives file's indexes in a LOADRESP message, separated by commas. Indexes start with zero and match a list of files that was received by LOAD command. For example, if there is only one video file in torrent file, then 0 index has to be sent.

If there are 5 video files in torrent and playback has to start from the first one, but others have to be loaded, then 0,1,2,3,4 have to be sent.

If the third file has to be played, without loading others, 2 has to be sent.

torrent_url - link to torrent file (for example, http://sometracker.com/torrent/12345)

torrent_infohash - torrent's infohash

player_id - player's code

torrent_data - torrent-file's content, encoded in base64

direct_url - direct link to file (for example, http://somesite.com/files/video.mp4)

developer_id - developer's code (if unknown, 0 must be sent)

affiliate_id - partner's code (if unknown, 0 must be sent)

zone_id - code of partner's zone (if unknown, 0 must be sent)

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

Getting code of the player through a set of parameters. This command is a synchronous command (see below). In response player's code or empty string (if player's code can't be received) is sent.

SHUTDOWN

Close connection with client.

STOP

Stop loading file that is being loaded at this moment.

DUR <video_url> <duration>

Inform TS Engine about duration of video file that is being played by client at this moment. This command must be sent right after client had determined content duration.

Parameters:

video_url - link to video, which was sent to client after the end of pre-buffering

duration - duration in milliseconds

PLAYBACK <video_url> <event>

Inform TS Engine about percentage of played video

This command is especially important when playing advertising video - transition to the main video happens only after TS Engine gets command PLAYBACK 100 (after client has played advertising video till the end)

Parameters:

video_url - link to video, which was sent to client after the end of pre-buffering

event - one of these events:

0 - starting playback

25 - 25% of video has been played

50 - 50% of video has been played

75 - 75% of video has been played

100 - 100% of video has been played

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

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 - ничего не выводим

Events

EVENT event_name param1_name=param1_value param2_name=param2_value ...

Parameters are not required.

Parameter values - urlencoded utf-8

Examples

>> - messages from client to TS Engine

<< - messages from TS Engine to client

1) Playback of torrent-file by link without commercials (TS Engine determines whether it's needed to play commercials).

Asynchronous command LOADASYNC is used to load torrent's content.

Torrent file contains one video file.

handshake

>>HELLOBG
<<HELLOTS

client is ready to receive messages

>>READY

advanced functions are available for user

<<AUTH 1

load torrent by link

>>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"}

get player's code (for example, to show it to user)

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

start video pre-buffering

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

pre-buffering is in the process

<<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

pre-buffering is finished, client gets a link for content playback

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

client sends content duration (~201 seconds)

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

client informs that playback was started

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

TS Engine loads content

<<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 doesn't have enough data for playback, starts buffering

<<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

buffering is finished

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

client lost 25% of content

>>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

client lost 50% of content

>>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

client lost 75% of content

>>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 content loading

>>STOP
<<STATE 0

disconnect

>>SHUTDOWN
<<SHUTDOWN