'''Обмен данными с TS Engine происходит по протоколу TCP.'''
'''По умолчанию TS Engine принимает входящие соединения на порт 62062.'''
== Общий вид команд ==
Каждая команда должна состоять из строки, завершающейся разделителем \r\n
Большинство команд имеют такой вид:
<tt>'''CMD [param1] [param2] ...'''</tt>
где
<tt>'''CMD'''</tt> - предопределенное название команды
<tt>'''param1, param2 ...'''</tt> - параметры команды, разделенные пробелом
== Типы команд ==
Все команды делятся на входящие и исходящие.
Входящие команды отправляются от клиента к 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)
== Входящие команды ==
<tt>'''HELLOBG'''</tt>
Используется в рамках процедуры "рукопожатия" между клиентом и TS Engine.
Эта команда должна быть отправлена клиентом сразу после установления tcp-соединения с TS Engine.
Соединение с TS Engine считается успешным после того, как клиент получил от TS Engine ответ на "рукопожатие" - команду HELLOTS
<tt>'''READY'''</tt>
Информирует TS Engine о том, что клиент готов принимать исходящие команды
<tt>'''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></tt>
Данные команды выполняют загрузку содержимого торрент-файла и используются для того, чтобы клиент мог получить список названий
файлов в интересующем торрент-файле. Команды LOAD выполняются синхронно, команды LOADASYNC - асинхронно (ответ приходит в исходящей команде LOADRESP).
Более предпочтительным методом является асинхронная загрузка.
'''Параметры:'''
<tt>'''request_id'''</tt> - случайное целое число - идентификатор запроса LOADASYNC; этот же идентификатор будет отослан клиенту в команде LOADRESP после того,как будет получен список файлов; данный идентификатор служит для того, чтобы клиент в случае отправки нескольких запросов LOAD точно знал, на какой из этих запросов получен ответ
<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
<tt>'''torrent_infohash'''</tt> - infohash торрента
<tt>'''player_id'''</tt> - код плеера
<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
<tt>'''zone_id'''</tt> - код зоны партнера (если неизвестно, необходимо передавать 0)
<tt>'''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>)</tt>
Данные команды используются для начала загрузки определенного файла из торрент-файла либо для начала загрузки файла по прямой ссылке (START URL)
'''Параметры:'''
<tt>'''file_indexes'''</tt> - список индексов файлов из торрент-файла, которые необходимо загружать. Индексы файлов клиент получает в сообщении LOADRESP разделенных запятой. Индексы начинаются с нуля и соответствуют списку файлов,
который был получен в результате выполнения команды LOAD. Например, если в торрент-файле всего один видео-файл, то необходимо отправлять индекс 0.
Если в торренте пять видео-файлов и необходимо начать проигрывание первого, но при это загружать остальные, то отправляется 0,1,2,3,4.
Если нужно проиграть третий файл, и не загружать другие, отправляется 2.
<tt>'''torrent_url'''</tt> - ссылка на торрент файл (например, http://sometracker.com/torrent/12345)
<tt>'''torrent_infohash'''</tt> - infohash торрента
<tt>'''player_id'''</tt> - код плеера
<tt>'''torrent_data'''</tt> - содержимое торрент-файла в кодировке base64
<tt>'''direct_url'''</tt> - прямая ссылка на файл (например, http://somesite.com/files/video.mp4)
<tt>'''developer_id'''</tt> - код разработчика (если неизвестно, необходимо передавать 0)
<tt>'''affiliate_id'''</tt> - код партнера (если неизвестно, необходимо передавать 0)
<tt>'''zone_id'''</tt> - код зоны партнера (если неизвестно, необходимо передавать 0)
<tt>'''GETPID''' <infohash> <developer_id> <affiliate_id> <zone_id></tt>
Получение кода плеера по набору параметров. Эта команда является синхронной командой (см.ниже). В ответ отправляется код плеера, либо пустая строка, если код плеера не может быть получен
<tt>'''SHUTDOWN'''</tt>
Закрыть соединение с клиентом.
<tt>'''STOP'''</tt>
Остановить загрузку файла, который загружается в данный момент.
<tt>'''DUR''' <video_url> <duration></tt>
Сообщить TS Engine о длительности видео-файла, который в данный момент проигрывается клиентом.
Данная команда должна отправлять сразу после того, как клиент определил длительность контента.
'''Параметры:'''
<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
<tt>'''duration'''</tt> - длительность в миллисекундах
<tt>'''PLAYBACK''' <video_url> <event></tt>
Сообщить TS Engine о процентном соотношении проигранного видео
Данная команда особенно важна, когда идет прогрывание рекламных роликов - переход к основному видео происходит только после того,
как TS Engine получил команду PLAYBACK 100 (т.е. после того, как клиент полность проиграл рекламный ролик)
'''Параметры:'''
<tt>'''video_url'''</tt> - ссылка на видео, которая была отправлена клиенту после окончания пребуферизации
<tt>'''event'''</tt> - одно из данных событий:
0 - начало проигрывания
25 - проиграно 25% видео
50 - проиграно 50% видео
75 - проиграно 75% видео
100 - проиграно 100% видео
== Исходящие команды ==
<tt>'''HELLOTS'''</tt>
ответная команда в рамках процедуры рукопожатия
<tt>'''AUTH''' <auth_level></tt>
Уровень доступа пользователя
<tt>auth_level</tt> - целое число - уровень доступа
На данный момент возможны два значения уровня доступа:
0 - пользователю не доступны расширенные функции (перемотка и проигрывание файлов из торрента с несколькими видео-файлами)
1 - пользователю доступны расширенные функции
<tt>'''STATE''' <state_id></tt>
Информация о текущем статусе TS Engine
<tt>'''SHUTDOWN'''</tt>
TS Engine завершил работу
<tt>'''PLAY''' <video_url></tt>
<tt>'''PLAYAD''' <video_url></tt>
<tt>'''PLAYADI''' <video_url></tt>
Начать проигрывание видео по ссылке video_url (данная ссылка ведет на http-сервер, встроенный в TS Engine).
<tt>'''PLAY'''</tt> - проигрывание основного видео
<tt>'''PLAYAD'''</tt> - проигрывание непрерываемого рекламного ролика (пользователь не может перемотать либо пропустить данный рекламный ролик)
<tt>'''PLAYADI'''</tt> - проигрывание прерываемого рекламного ролика (пользователь может перемотать либо пропустить данный рекламный ролик)
<tt>'''PAUSE'''</tt>
TS Engine начал буферизацию, так как недостаточно данных для проигрывания видео без остановки
<tt>'''RESUME'''</tt>
TS Engine завершил буферизацию
<tt>'''LOADRESP''' <request_id> <response></tt>
Ответ на команду LOAD
<tt>'''request_id'''</tt> - идентификатор запроса
<tt>'''response'''</tt> - список файлов в формате json в такого вида:
{
"status": 1,
"infohash": "abcd1234",
"files": [
["file1.mp4", 0],
["file2.avi", 1],
["file3.mkv", 5]
]
}
<tt>'''status'''</tt> - 0: в торренте нет видео файлов, 1 - в торренте один видео файл, 2 - в торренте более одного видео файла
<tt>'''infohash'''</tt> - infohash торрента
<tt>'''files'''</tt> - список файлов; это массив, каждый элемент в котором состоит из массива из двух элементов: первый - название файла, второй - позиция файла в торренте (эта позиция должна отправляться в команде START для указания, какой именно файл необходимо загружать, если их несколько).
Имена файлов передаются в кодировке UTF-8 в urlencoded виде.
<tt>'''INFO''' <message_id>;<message_text></tt>
Информационное сообщение
<tt>'''message_id'''</tt> - код сообщения
<tt>'''message_text'''</tt> - текст сообщения
<tt>'''STATUS''' <status_string></tt>
Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента
<tt>'''status_string'''</tt> - строка описанного ниже формата
Если идет проигрывание основного контента
<tt>STATUS main:status_string</tt>
Если идет проигрывание рекламного ролика:
<tt>STATUS main:status_string|ad:status_string</tt>
<tt>'''status_string:'''</tt>
TS Engine ничего не делает - <tt>'''idle'''</tt>
ошибка - <tt>'''err;error_id;error_message'''</tt> (код и описание)
проверка - <tt>'''check;progress'''</tt>
пребуферизация - <tt>'''prebuf;progress;time'''</tt>
закачка - <tt>'''dl'''</tt>
буферизация - <tt>'''buf;progress;time'''</tt>
ожидание достаточной скорости - <tt>'''wait;time'''</tt>
Ко всем <tt>status_string</tt> (кроме <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'''</tt> - сколько всего закачано по данному файлу
<tt>'''immediate_progress'''</tt> - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке)
Все числа передаются как integer.
Все progress принимают значение от 0 до 100.
'''Примеры:'''
<tt>STATUS main:prebuf;45;30|ad:buf;69
STATUS main:dl|ad:dl</tt>
'''Пример трансформация статусов в текстовые сообщения, понятные пользователю:'''
<tt>check - Checking xx%
prebuf - Prebuffering xx%
buf - Buffering xx%
wait - Waiting sufficient download speed
err - выводим сообщение об ошибке
dl, idle - ничего не выводим</tt>
== События ==
<tt>'''EVENT event_name param1_name=param1_value param2_name=param2_value ...'''</tt>
Параметры не обязательны.
Значения параметров - <tt>'''urlencoded utf-8'''</tt>
== Примеры ==
<tt>'''>>'''</tt> - сообщения от клиента к TS Engine
<tt>'''<<'''</tt> - сообщения от TS Engine к клиенту
1) Проигрывание торрент-файла по ссылке без рекламных роликов (необходимость проигрывания рекламных роликов определяет TS Engine).
Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.
Торрент файл содержит один видео-файл.
рукопожатие
<tt>>>HELLOBG
<<HELLOTS</tt>
клиент готов принимать сообщения
<tt>>>READY</tt>
пользователю доступны расширенные функции
<tt><<AUTH 1</tt>
загрузить торрент по ссылке
<tt>>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": <nowiki>[["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]]</nowiki>, "infohash":
"4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}</tt>
узнать код плеера (например, чтобы показать его пользователю)
<tt>>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195</tt>
начать пребуферизацию видео
<tt>>>START TORRENT http://rutor.org/download/67346 0 0 0 0</tt>
идет процесс пребуферизации
<tt><<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</tt>
пребуферизация завершена, клиент получает ссылку для проигрывания контента
<tt><<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2</tt>
клиент отправляет длительность контента (~201 секунда)
<tt>>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964</tt>
клиент информирует о том, что началось проигрывание
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0</tt>
TS Engine загружает контент
<tt><<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</tt>
TS Engine недостаточно данных для проигрывания, начинает буферизация
<tt><<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</tt>
буферизация завершена
<tt><<RESUME
<<STATE 2
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0</tt>
клиент проиграл 25% контента
<tt>>>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</tt>
клиент проиграл 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>
клиент проиграл 75% контента
<tt>>>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</tt>
остановить загрузку контента
<tt>>>STOP
<<STATE 0</tt>
разорвать соединение
<tt>>>SHUTDOWN
<<SHUTDOWN</tt>
----
----
----
==Общие понятия==
ACE Stream Engine (далее - "движок") - приложение, которое обеспечивает весь функционал системы ACE Stream. Данное приложение работает в фоновом режиме и имеет минимальный графический интерфейс для
;Описание
:Информация о текущем статусе TS Engine движка
;Синтаксис
<tt>STATE ''state_id''</tt>
;Параметры
* <tt>''state_id''</tt>: состояние движка:
** 0(IDLE) - движок ничего не делает** 1(PREBUFFERING) - началась пребуферизация** 2(DOWNLOADING) - идет загрузка контента в обычном режиме** 3 (BUFFERING) - началась буферизация** 4 (COMPLETED) - загрузка контента завершена** 5 (CHECKING) - выполняется инициализация перед началом загрузки** 6 (ERROR) - ошибка
;Пример:
:>= 1
;ОписаниеСинтаксис <tt>STATUS ''status_string''</tt> :Данное сообщение отправляется периодически для информирования клиента о текущем статусе загрузки контента <tt>'''status_string'''</tt> - строка описанного ниже формата Если идет проигрывание основного контента <tt>STATUS main:status_string</tt> Если идет проигрывание рекламного ролика: <tt>STATUS main:status_string|ad:status_string</tt> <tt>'''status_string:'''</tt> движок ничего не делает - <tt>'''idle'''</tt> ошибка - <tt>'''err;error_id;error_message'''</tt> (код и описание) проверка - <tt>'''check;progress'''</tt> пребуферизация - <tt>'''prebuf;progress;time'''</tt> закачка - <tt>'''dl'''</tt> буферизация - <tt>'''buf;progress;time'''</tt> ожидание достаточной скорости - <tt>'''wait;time'''</tt> Ко всем <tt>status_string</tt> (кроме <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'''</tt> - сколько всего закачано по данному файлу <tt>'''immediate_progress'''</tt> - сколько непрерывных данных закачано начиная с текущей позиции (для отображения кол-ва закачанного в бегунке) Все числа передаются как integer. Все progress принимают значение от 0 до 100.
;Синтаксис'''Примеры:''' <tt>STATUS main:status_stringprebuf;45;30|ad:buf;69 STATUS main:status_stringdl|ad:status_stringdl</tt>
;Параметры'''Пример трансформация статусов в текстовые сообщения, понятные пользователю:нет'''
;Пример: <tt><nowiki><<STATUS main:check - Checking xx% prebuf;45;30|ad:- Prebuffering xx% buf;69- Buffering xx%<<STATUS main:dl|ad: wait - Waiting sufficient download speed err - выводим сообщение об ошибке dl</nowiki>, idle - ничего не выводим</tt>
=====<tt style="color: #009;">AUTH</tt>=====
=====<tt style="color: #009;">EVENT</tt>=====
Описание скоро будет
== Примеры ==
<tt>'''>>'''</tt> - сообщения от клиента к движку
<tt>'''<<'''</tt> - сообщения от движка к клиенту
1) Проигрывание торрент-файла по ссылке без рекламных роликов (необходимость проигрывания рекламных роликов определяет движок).
Для загрузки содержимого торрента используется асинхронная команда LOADASYNC.
Торрент файл содержит один видео-файл.
рукопожатие
<tt>>>HELLOBG
<<HELLOTS</tt>
клиент готов принимать сообщения
<tt>>>READY</tt>
пользователю доступны расширенные функции
<tt><<AUTH 1</tt>
загрузить торрент по ссылке
<tt>>>LOADASYNC 467763 TORRENT http://rutor.org/download/67346 0 0 0
<<LOADRESP 467763 {"status": 1, "files": <nowiki>[["Prey%202_%20E3%202011%20Official%20Trailer_2.mp4", 0]]</nowiki>, "infohash":
"4c78e1cf0df23b4f5a16a106829ebed710cb52e0"}</tt>
узнать код плеера (например, чтобы показать его пользователю)
<tt>>>GETPID 4c78e1cf0df23b4f5a16a106829ebed710cb52e0 0 0 0
<<##36ae4c89ab45b4010b1461c513da38d007356195</tt>
начать пребуферизацию видео
<tt>>>START TORRENT http://rutor.org/download/67346 0 0 0 0</tt>
идет процесс пребуферизации
<tt><<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</tt>
пребуферизация завершена, клиент получает ссылку для проигрывания контента
<tt><<PLAY http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974
<<STATE 2</tt>
клиент отправляет длительность контента (~201 секунда)
<tt>>>DUR http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 201964</tt>
клиент информирует о том, что началось проигрывание
<tt>>>PLAYBACK http://127.0.0.1:6878/content/4c78e1cf0df23b4f5a16a106829ebed710cb52e0/0.673752283974 0</tt>
движок загружает контент
<tt><<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</tt>
движку недостаточно данных для проигрывания, начинает буферизация
<tt><<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</tt>
буферизация завершена
<tt><<RESUME
<<STATE 2
<<STATUS main:dl;0;0;141;0;0;8;0;4898816;0;0</tt>
клиент проиграл 25% контента
<tt>>>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</tt>
клиент проиграл 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>
клиент проиграл 75% контента
<tt>>>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</tt>
остановить загрузку контента
<tt>>>STOP
<<STATE 0</tt>
разорвать соединение
<tt>>>SHUTDOWN
<<SHUTDOWN</tt>
