Difference between revisions of "Engine API/en"

From Ace Stream Wiki
Jump to: navigation, search
(Примеры)
(Examples)
 
(4 intermediate revisions by the same user not shown)
Line 50: Line 50:
 
<tt>'''HELLOBG'''</tt>
 
<tt>'''HELLOBG'''</tt>
  
Используется в рамках процедуры "рукопожатия" между клиентом и TS Engine.
+
Used as a part of "handshake" procedure between client and TS Engine.
  
Эта команда должна быть отправлена клиентом сразу после установления tcp-соединения с TS Engine.
+
This command must be sent by client right after establishing tcp-connection with TS Engine.
  
Соединение с TS Engine считается успешным после того, как клиент получил от TS Engine ответ на "рукопожатие" - команду HELLOTS
+
Connection with TS Engine is successful, if client receives from TS Engine response to "handshake" - command HELLOTS
  
  
 
<tt>'''READY'''</tt>
 
<tt>'''READY'''</tt>
  
Информирует TS Engine о том, что клиент готов принимать исходящие команды
+
Informs TS Engine that client is ready to receive outgoing commands
  
  
Line 78: Line 78:
 
'''LOADASYNC''' <request_id> '''RAW''' <torrent_data> <developer_id> <affiliate_id> <zone_id></tt>
 
'''LOADASYNC''' <request_id> '''RAW''' <torrent_data> <developer_id> <affiliate_id> <zone_id></tt>
  
Данные команды выполняют загрузку содержимого торрент-файла и используются для того, чтобы клиент мог получить список названий
+
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).
файлов в интересующем торрент-файле. Команды LOAD выполняются синхронно, команды LOADASYNC - асинхронно (ответ приходит в исходящей команде LOADRESP).
 
  
Более предпочтительным методом является асинхронная загрузка.
+
Preferred method is asynchronous loading.
  
'''Параметры:'''
+
'''Parameters:'''
  
<tt>'''request_id'''</tt> - случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOAD точно знал, на какой из этих запросов получен ответ
+
<tt>'''request_id'''</tt> - 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
  
<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
+
<tt>'''torrent_url'''</tt> - link to torrent file (for example, http://sometracker.com/torrent/12345)
  
<tt>'''torrent_infohash'''</tt> - infohash торрента
+
<tt>'''torrent_infohash'''</tt> - torrent's infohash
  
<tt>'''player_id'''</tt> - код плеера
+
<tt>'''player_id'''</tt> - player's code
  
<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
+
<tt>'''torrent_data'''</tt> - torrent-file's content, encoded in base64
  
<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
+
<tt>'''developer_id'''</tt> - developer's code (if unknown, 0 must be sent)
  
<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
+
<tt>'''affiliate_id'''</tt> - partner's code (if unknown, 0 must be sent)
  
<tt>'''zone_id'''</tt> - код зоны партнера (если неизвестно, необходимо передавать 0)
+
<tt>'''zone_id'''</tt> - code of partner's zone (if unknown, 0 must be sent)
  
  
Line 112: Line 111:
 
'''START URL''' <direct_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>)</tt>
 
'''START URL''' <direct_url> <file_indexes> <developer_id> <affiliate_id> <zone_id>)</tt>
  
Данные команды используются для начала загрузки определенного файла из торрент-файла либо для начала загрузки файла по прямой ссылке (START URL)
+
These commands are used to start loading a specific file from torrent or by direct link (START URL)
  
'''Параметры:'''
+
'''Parameters:'''
  
<tt>'''file_indexes'''</tt> - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов,
+
<tt>'''file_indexes'''</tt> - 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.
который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.
 
  
Если в торренте пять видео-файлов и необходимо начать проигрывание первого, но при это загружать остальные, то отправляется 0,1,2,3,4.
+
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.
  
Если нужно проиграть третий файл, и не загружать другие, отправляется 2.
+
If the third file has to be played, without loading others, 2 has to be sent.
  
<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
+
<tt>'''torrent_url'''</tt> - link to torrent file (for example, http://sometracker.com/torrent/12345)
  
<tt>'''torrent_infohash'''</tt> - infohash торрента
+
<tt>'''torrent_infohash'''</tt> - torrent's infohash
  
<tt>'''player_id'''</tt> - код плеера
+
<tt>'''player_id'''</tt> - player's code
  
<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
+
<tt>'''torrent_data'''</tt> - torrent-file's content, encoded in base64
  
<tt>'''direct_url'''</tt> - прямая ссылка на файл (например, http://somesite.com/files/video.mp4)
+
<tt>'''direct_url'''</tt> - direct link to file (for example, http://somesite.com/files/video.mp4)
  
<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
+
<tt>'''developer_id'''</tt> - developer's code (if unknown, 0 must be sent)
  
<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
+
<tt>'''affiliate_id'''</tt> - partner's code (if unknown, 0 must be sent)
  
<tt>'''zone_id'''</tt> - код зоны партнера (если неизвестно, необходимо передавать 0)
+
<tt>'''zone_id'''</tt> - code of partner's zone (if unknown, 0 must be sent)
  
  
 
<tt>'''GETPID''' <infohash> <developer_id> <affiliate_id> <zone_id></tt>
 
<tt>'''GETPID''' <infohash> <developer_id> <affiliate_id> <zone_id></tt>
  
Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен
+
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.
  
  
 
<tt>'''SHUTDOWN'''</tt>
 
<tt>'''SHUTDOWN'''</tt>
  
Закрыть соединение с клиентом.
+
Close connection with client.
  
  
 
<tt>'''STOP'''</tt>
 
<tt>'''STOP'''</tt>
  
Остановить загрузку файла, который загружается в данный момент.
+
Stop loading file that is being loaded at this moment.
  
  
 
<tt>'''DUR''' <video_url> <duration></tt>
 
<tt>'''DUR''' <video_url> <duration></tt>
  
Сообщить TS Engine о длительности видео-файла, который в данный момент проигрывается клиентом.
+
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:'''
  
<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
+
<tt>'''video_url'''</tt> - link to video, which was sent to client after the end of pre-buffering
  
<tt>'''duration'''</tt> - длительность в миллисекундах
+
<tt>'''duration'''</tt> - duration in milliseconds
  
  
 
<tt>'''PLAYBACK''' <video_url> <event></tt>
 
<tt>'''PLAYBACK''' <video_url> <event></tt>
  
Сообщить TS Engine о процентном соотношении проигранного видео
+
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)
как TS Engine получил команду PLAYBACK 100 (т.е. после того, как клиент полность проиграл рекламный ролик)
 
  
'''Параметры:'''
+
'''Parameters:'''
  
<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
+
<tt>'''video_url'''</tt> - link to video, which was sent to client after the end of pre-buffering
  
<tt>'''event'''</tt> - одно из данных событий:
+
<tt>'''event'''</tt> - one of these events:
  
0 - начало проигрывания
+
0 - starting playback
  
25 - проиграно 25% видео
+
25 - 25% of video has been played
  
50 - проиграно 50% видео
+
50 - 50% of video has been played
  
75 - проиграно 75% видео
+
75 - 75% of video has been played
  
100 - проиграно 100% видео
+
100 - 100% of video has been played
  
== Исходящие команды ==
+
== Outgoing commands ==
  
 
<tt>'''HELLOTS'''</tt>
 
<tt>'''HELLOTS'''</tt>
  
ответная команда в рамках процедуры рукопожатия
+
response command as a part of handshake procedure
  
  
 
<tt>'''AUTH''' <auth_level></tt>
 
<tt>'''AUTH''' <auth_level></tt>
  
Уровень доступа пользователя
+
User's access level
  
<tt>auth_level</tt> - целое число - уровень доступа
+
<tt>auth_level</tt> - integer - access level
  
На данный момент возможны два значения уровня доступа:
+
At this moment two values of access level are available:
  
0 - пользователю не доступны расширенные функции (перемотка и проигрывание файлов из торрента с несколькими видео-файлами)
+
0 - advanced features are not available for user (rewind and playback of torrent files with several video files)
  
1 - пользователю доступны расширенные функции
+
1 - advanced features are available for user
  
  
 
<tt>'''STATE''' <state_id></tt>
 
<tt>'''STATE''' <state_id></tt>
  
Информация о текущем статусе TS Engine
+
Information about current state of TS Engine
  
  
 
<tt>'''SHUTDOWN'''</tt>
 
<tt>'''SHUTDOWN'''</tt>
  
TS Engine завершил работу
+
TS Engine finished its work
  
  
Line 226: Line 222:
 
<tt>'''PLAYADI''' <video_url></tt>
 
<tt>'''PLAYADI''' <video_url></tt>
  
Начать проигрывание видео по ссылке video_url (данная ссылка ведет на http-сервер, встроенный в TS Engine).
+
Start playing video by video_url link (this link leads to http-server, embedded in TS Engine).
  
<tt>'''PLAY'''</tt> - проигрывание основного видео
+
<tt>'''PLAY'''</tt> - playback of the main video
  
<tt>'''PLAYAD'''</tt> - проигрывание непрерываемого рекламного ролика (пользователь не может перемотать либо пропустить данный рекламный ролик)
+
<tt>'''PLAYAD'''</tt> - playback of uninterrupted advertising video (user can't rewind or skip this advertising video)
  
<tt>'''PLAYADI'''</tt> - проигрывание прерываемого рекламного ролика (пользователь может перемотать либо пропустить данный рекламный ролик)
+
<tt>'''PLAYADI'''</tt> - playback of interrupted advertising video (user can rewind or skip this advertising video)
  
  
 
<tt>'''PAUSE'''</tt>
 
<tt>'''PAUSE'''</tt>
  
TS Engine начал буферизацию, так как недостаточно данных для проигрывания видео без остановки
+
TS Engine began buffering, because there's not enough data for video playback without interruptions
  
  
 
<tt>'''RESUME'''</tt>
 
<tt>'''RESUME'''</tt>
  
TS Engine завершил буферизацию
+
TS Engine finished buffering
  
  
 
<tt>'''LOADRESP''' <request_id> <response></tt>
 
<tt>'''LOADRESP''' <request_id> <response></tt>
  
Ответ на команду LOAD
+
Response to LOAD command
  
<tt>'''request_id'''</tt> - идентификатор запроса
+
<tt>'''request_id'''</tt> - request identifier
  
<tt>'''response'''</tt> - список файлов в формате json в такого вида:
+
<tt>'''response'''</tt> - a list of files in json format in this form:
 
  {
 
  {
 
   "status": 1,
 
   "status": 1,
Line 262: Line 258:
 
  }
 
  }
  
<tt>'''status'''</tt> - 0: в торренте нет видео файлов, 1 - в торренте один видео файл, 2 - в торренте более одного видео файла
+
<tt>'''status'''</tt> - 0: there are no video files in torrent, 1 - there is one video file in torrent, 2 - there are more than one video files in torrent
  
<tt>'''infohash'''</tt> - infohash торрента
+
<tt>'''infohash'''</tt> - torrent infohash
  
<tt>'''files'''</tt> - список файлов; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция файла в торренте (эта позиция должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько).
+
<tt>'''files'''</tt> - a list of files; this is an array, each element of which consists of an array with two elements: the first - file's name, the second - file's position in torrent (this position must be sent inside START command to specify which file to download, if there are several of them).
  
Имена файлов передаются в кодировке UTF-8 в urlencoded виде.
+
Files' names are transferred in UTF-8 encoding in urlencoded form.
  
  
 
<tt>'''INFO''' <message_id>;<message_text></tt>
 
<tt>'''INFO''' <message_id>;<message_text></tt>
  
Информационное сообщение
+
Info message
  
<tt>'''message_id'''</tt> - код сообщения
+
<tt>'''message_id'''</tt> - message code
  
<tt>'''message_text'''</tt> - текст сообщения
+
<tt>'''message_text'''</tt> - message text
  
  
Line 283: Line 279:
 
<tt>'''STATUS''' <status_string></tt>
 
<tt>'''STATUS''' <status_string></tt>
  
Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента
+
This message is sent periodically to inform client about current state of content download.
  
<tt>'''status_string'''</tt> - строка описанного ниже формата
+
<tt>'''status_string'''</tt> - string in format described below
  
  
Если идет проигрывание основного контента
+
If the main content is being played:
  
 
  <tt>STATUS main:status_string</tt>
 
  <tt>STATUS main:status_string</tt>
  
  
Если идет проигрывание рекламного ролика:
+
If advertising video is being played:
  
 
  <tt>STATUS main:status_string|ad:status_string</tt>
 
  <tt>STATUS main:status_string|ad:status_string</tt>
Line 300: Line 296:
 
<tt>'''status_string:'''</tt>
 
<tt>'''status_string:'''</tt>
  
TS Engine ничего не делает - <tt>'''idle'''</tt>
+
TS Engine does nothing - <tt>'''idle'''</tt>
  
ошибка - <tt>'''err;error_id;error_message'''</tt> (код и описание)
+
error - <tt>'''err;error_id;error_message'''</tt> (code and description)
  
проверка - <tt>'''check;progress'''</tt>
+
checking - <tt>'''check;progress'''</tt>
  
пребуферизация - <tt>'''prebuf;progress;time'''</tt>
+
prebuffering - <tt>'''prebuf;progress;time'''</tt>
  
закачка - <tt>'''dl'''</tt>
+
download - <tt>'''dl'''</tt>
  
буферизация - <tt>'''buf;progress;time'''</tt>
+
buffering - <tt>'''buf;progress;time'''</tt>
  
ожидание достаточной скорости - <tt>'''wait;time'''</tt>
+
waiting for sufficient speed - <tt>'''wait;time'''</tt>
  
  
Ко всем <tt>status_string</tt> (кроме <tt>idle, err, check</tt>) добавляются общие данные:
+
Common data is added to all <tt>status_string</tt> (except <tt>idle, err, check</tt>):
  
 
  <tt>total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded</tt>
 
  <tt>total_progress;immediate_progress;speed_down;http_speed_down;speed_up;peers;http_peers;downloaded;http_downloaded;uploaded</tt>
  
<tt>'''total_progress'''</tt> - сколько всего закачано по данному файлу
+
<tt>'''total_progress'''</tt> - how much of this file is downloaded
  
<tt>'''immediate_progress'''</tt> - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке)
+
<tt>'''immediate_progress'''</tt> - how much uninterruptible data is downloaded starting from the current position (to show amount of downloaded data)
  
  
Все числа передаются как integer.
+
All numbers are sent as integer.
  
Все progress принимают значение от 0 до 100.
+
All progress takes values from 0 to 100.
  
  
'''Примеры:'''
+
'''Examples:'''
 
  <tt>STATUS main:prebuf;45;30|ad:buf;69
 
  <tt>STATUS main:prebuf;45;30|ad:buf;69
 
  STATUS main:dl|ad:dl</tt>
 
  STATUS main:dl|ad:dl</tt>
  
'''Пример трансформация статусов в текстовые сообщения, понятные пользователю:'''
+
'''Example of tranformation statuses into text messages that user can understand:'''
  
 
  <tt>check - Checking xx%
 
  <tt>check - Checking xx%
Line 339: Line 335:
 
  buf - Buffering xx%
 
  buf - Buffering xx%
 
  wait - Waiting sufficient download speed
 
  wait - Waiting sufficient download speed
  err - выводим сообщение об ошибке
+
  err - showing an error message
  dl, idle - ничего не выводим</tt>
+
  dl, idle - doing nothing</tt>
  
== События ==
+
== Events ==
  
 
<tt>'''EVENT event_name param1_name=param1_value param2_name=param2_value ...'''</tt>
 
<tt>'''EVENT event_name param1_name=param1_value param2_name=param2_value ...'''</tt>
  
Параметры не обязательны.
+
Parameters are not required.
 
 
Значения параметров - <tt>'''urlencoded utf-8'''</tt>
 
 
 
  
 +
Parameter values - <tt>'''urlencoded utf-8'''</tt>
  
 
==Examples==
 
==Examples==
Line 437: Line 431:
 
  <<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0</tt>
 
  <<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0</tt>
  
client lost 25% of content
+
client has played 25% of content
  
 
  <tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 25
 
  <tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 25
Line 443: Line 437:
 
  <<STATUS main:dl;0;0;146;0;0;7;0;8388608;0;0</tt>
 
  <<STATUS main:dl;0;0;146;0;0;7;0;8388608;0;0</tt>
  
client lost 50% of content
+
client has played 50% of content
  
 
  <tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 50
 
  <tt>>>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</tt>
 
  <<STATUS main:dl;0;0;145;0;0;7;0;9404416;0;0</tt>
  
client lost 75% of content
+
client has played 75% of content
  
 
  <tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 75
 
  <tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 75

Latest revision as of 12:01, 26 December 2012

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

Outgoing commands

HELLOTS

response command as a part of handshake procedure


AUTH <auth_level>

User's access level

auth_level - integer - access level

At this moment two values of access level are available:

0 - advanced features are not available for user (rewind and playback of torrent files with several video files)

1 - advanced features are available for user


STATE <state_id>

Information about current state of TS Engine


SHUTDOWN

TS Engine finished its work


PLAY <video_url>

PLAYAD <video_url>

PLAYADI <video_url>

Start playing video by video_url link (this link leads to http-server, embedded in TS Engine).

PLAY - playback of the main video

PLAYAD - playback of uninterrupted advertising video (user can't rewind or skip this advertising video)

PLAYADI - playback of interrupted advertising video (user can rewind or skip this advertising video)


PAUSE

TS Engine began buffering, because there's not enough data for video playback without interruptions


RESUME

TS Engine finished buffering


LOADRESP <request_id> <response>

Response to LOAD command

request_id - request identifier

response - a list of files in json format in this form:

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

status - 0: there are no video files in torrent, 1 - there is one video file in torrent, 2 - there are more than one video files in torrent

infohash - torrent infohash

files - a list of files; this is an array, each element of which consists of an array with two elements: the first - file's name, the second - file's position in torrent (this position must be sent inside START command to specify which file to download, if there are several of them).

Files' names are transferred in UTF-8 encoding in urlencoded form.


INFO <message_id>;<message_text>

Info message

message_id - message code

message_text - message text


STATUS <status_string>

This message is sent periodically to inform client about current state of content download.

status_string - string in format described below


If the main content is being played:

STATUS main:status_string


If advertising video is being played:

STATUS main:status_string|ad:status_string


status_string:

TS Engine does nothing - idle

error - err;error_id;error_message (code and description)

checking - check;progress

prebuffering - prebuf;progress;time

download - dl

buffering - buf;progress;time

waiting for sufficient speed - wait;time


Common data is added to all status_string (except idle, err, check):

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

total_progress - how much of this file is downloaded

immediate_progress - how much uninterruptible data is downloaded starting from the current position (to show amount of downloaded data)


All numbers are sent as integer.

All progress takes values from 0 to 100.


Examples:

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

Example of tranformation statuses into text messages that user can understand:

check - Checking xx%
prebuf - Prebuffering xx%
buf - Buffering xx%
wait - Waiting sufficient download speed
err - showing an error message
dl, idle - doing nothing

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